An Unofficial Guide to Writing Qubic Smart Contracts
This unofficial guide provides an overview of developing Qubic Smart Contracts, detailing key functions, memory allocation, and testing procedures to ensure robust and efficient deployment.
Qsilver · Jun 27, 2024.
Introduction
Welcome to the unofficial guide to writing Qubic Smart Contracts (SC). This guide aims to provide a clear and concise overview of how to develop and implement smart contracts within the Qubic ecosystem, drawing from the core QPI documentation.
Overview of Qubic Smart Contracts
Currently, the primary documentation for writing SCs is the QPI file on GitHub. QPI stands for Qubic Programming Interface, analogous to an API (Application Programming Interface) but specific to Qubic.
The QPI file includes:
- Prohibited Characters: No multiplication or division operators, no preprocessor directives.
- Core Code Structure:
- 5000 lines of code: Defines every type of variable size from single bits to arrays with millions of elements.
- 1000 lines of code: Manages various queues and related data types for efficient data handling.
- Final few hundred lines: Enable access to the Qubic network state.
Key Functions in QPI
Here are some of the essential functions provided in the QPI:
id arbitrator() const;
id computor(uint16 computorIndex) const; // [0..675]
uint8 day() const; // [1..31]
uint8 dayOfWeek() const; // [0..6]
uint16 epoch() const; // [0..9'999]
bit getEntity() const; // Returns “true” if the entity has been found, “false” otherwise
uint8 hour() const; // [0..23]
sint64 invocationReward() const;
id invocator() const; // Returns the id of the user/contract that triggered this contract; returns NULL_ID if none
template <typename T> id K12(const T& data) const;
uint16 millisecond() const; // [0..999]
uint8 minute() const; // [0..59]
uint8 month() const; // [1..12]
id nextId(const id& currentId) const;
sint64 numberOfPossessedShares() const;
id originator() const; // Returns the id of the user who triggered the entire chain of invocations; returns NULL_ID if none
uint8 second() const; // [0..59]
bit signatureValidity() const;
uint32 tick() const; // [0..999'999'999]
uint8 year() const; // [0..99] (0 = 2000, 1 = 2001, …, 99 = 2099)What Does This Mean?
Qubic Smart Contracts are Turing complete, meaning you can implement virtually any computational logic. However, certain restrictions ensure that SCs run in a highly compartmentalized and secure environment.
Memory Allocation
SCs use a static memory allocation model where all memory must be preallocated. This design is crucial for managing data structures efficiently within a 1GB RAM limit. Although this limit is set to double in the future, it remains a fixed allocation, requiring careful planning of memory usage.
Library Usage
Currently, you cannot use external libraries in SCs; all necessary code must be included directly in the source. Over time, as more SCs incorporate various libraries, these may become available for public use within other SCs.
Transactions and RCF Network Messages
Each SC has a unique address derived from a public key, with the contract ID being the lowest 64 bits. SCs are invoked via transactions sent to this address, with inputData specifying the operation. Additionally, the state of an SC can be queried using RCF network messages.
Example: Airdrop SC
An airdrop SC could iterate through a dataset and distribute QU or tokens to each address in one tick per SC transaction. With a current limit of 1024 transactions per tick, this could result in up to 500 million transfers per tick. The actual throughput depends on the complexity of the SC.
How to Test Your SC
- Develop your SC: Write and debug your smart contract code.
- Update qubic-cli: Ensure your SC transactions and RCF functions are integrated.
- Create a Testnet Core Update: Integrate your SC into a testnet environment.
- Run Tests: Use qubic-cli to query your testnet node and validate SC performance.
- Stress Testing: Perform load testing and automated tests to ensure stability.
- Submit for Approval: Once debugging is complete, submit your SC for quorum approval and then proceed to IPO.
By following these steps, you can ensure that your smart contracts are robust, efficient, and ready for deployment in the Qubic network. Happy coding!
Read Qsilver’s “Unofficial” Series
- An Unofficial Qubic Interim Whitepaper
- Qubic Crypto Details
- An Unofficial Guide to Qubic Services Integration
- An Unofficial Guide to Qubic Services Integration
For the latest updates, join the Valis Discord, follow us on X, and bookmark our blog.