Qubic Development Environment

Welcome to the Qubic Development Environment, an integrated platform for building, testing, and deploying Qubic smart contracts and applications. This environment provides a complete set of tools designed to streamline your Qubic development workflow.

Features

Qubic Smart Contracts – Best Practices & Development Guide

📌 Introduction
Qubic smart contracts (SCs) are self-executing programs that run within the Qubic ecosystem. They automate logic, manage balances, and interact with the blockchain to process transactions securely and efficiently. This guide provides best practices, structure, and essential components for writing effective Qubic SCs.

---

How Qubic Smart Contracts Work

1. Each SC has its own balance – funds sent to the SC are tracked internally.
2. Transactions interact with the SC – functions in the SC execute based on received inputs.
3. Epoch-based execution – Qubic SCs operate in epoch cycles (BEGIN_EPOCH and END_EPOCH events).
4. State persistence – unlike traditional C++, Qubic SCs use state storage to persist data across transactions.

---

Structure of a Qubic Smart Contract

A Qubic SC typically consists of the following components:

1. State Variables
   • SCs do not support local variables inside functions—all important values must be stored in state.
   • Example:

   struct State {
       uint64_t totalDeposits;
       uint64_t lastEpochBalance;
   };

2. Public Functions
   • Smart contracts expose public functions that can be called by users.
   • Functions must follow correct qpi function usage.
   • Example:

   PUBLIC void deposit(uint64_t amount) {
       require(amount > 0, "Deposit must be positive");
       state.totalDeposits += amount;
   }

3. Epoch-Based Event Handling
   • SCs rely on epoch events to track funds and manage state.
   • The BEGIN_EPOCH function is used for updating balance:

   PUBLIC void begin_epoch() {
       ::Entity entity;
       bit status = qpi.getEntity(SELF, entity);
       require(status, "Failed to fetch entity");
       state.lastEpochBalance = entity.incomingAmount - entity.outgoingAmount;
   }

   • The END_EPOCH function is used for distributing rewards:

   PUBLIC void end_epoch() {
       print("End of epoch processing complete.");
   }

---

Best Practices for Writing Qubic Smart Contracts

1. Smart Contract Initialization
   • Always initialize all state variables explicitly to avoid unexpected behavior.
   • Example:

   INITIALIZE
   state.totalDeposits = 0;
   state.lastEpochBalance = 0;

2. Managing Smart Contract Balances
   • Fetch SC balance dynamically using:

   ::Entity entity;
   bit status = qpi.getEntity(SELF, entity);
   uint64_t current_balance = entity.incomingAmount - entity.outgoingAmount;

   • Never assume a fixed amount—always track incoming and outgoing funds dynamically.
3. Handling Transactions Correctly
   • Ensure transactions are properly validated before modifying state.
   • Example:

   PUBLIC void transfer(uint64_t amount) {
       require(amount > 0, "Amount must be greater than zero");
       require(state.totalDeposits >= amount, "Insufficient funds");
       state.totalDeposits -= amount;
   }

4. Using State Variables Correctly
   • Store all necessary data in state—Qubic SCs do not retain local variables between calls.
   • Example:

   struct ContractState {
       uint64_t lastEpochBalance;
       uint64_t totalRewards;
   };
   ContractState state;

5. Reward Distribution & Staking
   • If an SC distributes staking rewards, use END_EPOCH to calculate and distribute correctly.
   • Example approach:

   uint64_t rewards = (state.lastEpochBalance * 5) / 100; // Example 5% reward
   state.totalRewards += rewards;

6. Security Best Practices
   • Require conditions before modifying state:

   require(state.totalDeposits > 0, "No funds available");

   • Validate input values:

   require(amount > 0, "Invalid amount");

   • Use qpi.getEntity() for correct SC balance fetching.

---

Example: Simple Qubic Smart Contract

This contract allows users to deposit funds, check their balance, and track epoch-based fund changes.

using namespace qpi;

class SimpleQubicContract {
public:
    struct State {
        uint64_t totalDeposits;
        uint64_t lastEpochBalance;
    };

    State state;

    // Deposit function
    PUBLIC void deposit(uint64_t amount) {
        require(amount > 0, "Deposit must be positive");
        state.totalDeposits += amount;
        print("Deposited: ", amount);
    }

    // Fetch SC balance dynamically
    PUBLIC uint64_t get_balance() {
        ::Entity entity;
        bit status = qpi.getEntity(SELF, entity);
        require(status, "Failed to fetch balance");
        return entity.incomingAmount - entity.outgoingAmount;
    }

    // Epoch event handler
    PUBLIC void begin_epoch() {
        ::Entity entity;
        bit status = qpi.getEntity(SELF, entity);
        require(status, "Failed to fetch entity");
        state.lastEpochBalance = entity.incomingAmount - entity.outgoingAmount;
        print("Updated balance for new epoch.");
    }
};

---

Getting Started

Smart Contract IDE

The Smart Contract IDE is designed specifically for developing smart contracts for the Qubic platform:

• Write contracts with syntax highlighting and code completion
• Test your contracts locally before deployment
• Submit contracts directly to the testnet
• Get AI-powered suggestions for contract optimization and security improvements

CLI IDE

The CLI IDE provides a powerful interface for interacting with the Qubic blockchain through command-line instructions:

• Execute common Qubic CLI commands directly from the browser
• Save and manage code files for your projects
• Compile and run your code with built-in Docker integration
• Receive AI assistance for generating optimal commands and troubleshooting

The CLI commands allow users to perform various operations on the Qubic blockchain. Here are all the commands and how to use them:

• ./qubic-cli -help: Prints the help message with all available commands.
• ./qubic-cli -nodeip <IPv4_ADDRESS>: Specifies the IP address of the target node for querying blockchain information.
• ./qubic-cli -nodeport <PORT>: Specifies the port of the target node for querying blockchain information.
• ./qubic-cli -seed <SEED>: Specifies the 55-character seed private key.
• ./qubic-cli -conf <file>: Specifies the configuration file.
• ./qubic-cli -scheduletick <TICK_OFFSET>: Specifies the offset number of scheduled tick that will perform a transaction.
• ./qubic-cli -force: Executes an action even if an error has been detected.
• ./qubic-cli -getbalance <IDENTITY>: Retrieves the balance of a specified identity.
• ./qubic-cli -getasset <IDENTITY>: Prints a list of assets of a specified identity.
• ./qubic-cli -queryassets <QUERY_TYPE> <QUERY_STRING>: Queries and prints asset information based on the specified query type and string.
• ./qubic-cli -sendtoaddress <TARGET_IDENTITY> <AMOUNT>: Sends a specified amount of qubic to a target identity.
• ./qubic-cli -sendtoaddressintick <TARGET_IDENTITY> <AMOUNT> <TICK>: Sends a specified amount of qubic to a target identity in a specific tick.
• ./qubic-cli -qutilsendtomanyv1 <FILE>: Performs multiple transactions within one tick based on the data in the specified file.
• ./qubic-cli -qutilburnqubic <AMOUNT>: Burns a specified amount of qubic.
• ./qubic-cli -gettickdata <TICK_NUMBER> <OUTPUT_FILE_NAME>: Gets tick data and writes it to a specified file.
• ./qubic-cli -readtickdata <FILE_NAME>: Reads tick data from a file and prints the output on screen.
• ./qubic-cli -checktxonfile <TX_HASH> <TICK_DATA_FILE>: Checks if a transaction is included in a tick based on the tick data from a file.
• ./qubic-cli -checktxontick <TICK_NUMBER> <TX_HASH>: Checks if a transaction is included in a tick online.
• ./qubic-cli -getcurrenttick: Fetches the current tick information of the node.
• ./qubic-cli -sendspecialcommand <COMMAND_IN_NUMBER>: Performs a special command to the node.
• ./qubic-cli -togglemainaux <MODE_0> <MODE_1>: Remotely toggles Main/Aux mode on the node.
• ./qubic-cli -setsolutionthreshold <EPOCH> <SOLUTION_THRESHOLD>: Remotely sets the solution threshold for future epochs.
• ./qubic-cli -refreshpeerlist: Remotely refreshes the peer list of the node.
• ./qubic-cli -forcenexttick: Remotely forces the next tick on the node to be empty.
• ./qubic-cli -reissuevote: Remotely re-issues (re-sends) a vote on the node.
• ./qubic-cli -sendrawpacket <DATA_IN_HEX> <SIZE>: Sends a raw packet to the node IP.
• ./qubic-cli -synctime: Syncs the node time with local time.
• ./qubic-cli -getminingscoreranking: Gets the current mining score ranking.
• ./qubic-cli -getvotecountertx <COMPUTOR_LIST_FILE> <TICK>: Gets vote counter transaction of a tick.
• ./qubic-cli -getquorumtick <COMP_LIST_FILE> <TICK_NUMBER>: Gets quorum tick data.
• ./qubic-cli -getcomputorlist <OUTPUT_FILE_NAME>: Gets computor list of the current epoch.
• ./qubic-cli -getnodeiplist: Prints a list of node IPs from a seed node IP.
• ./qubic-cli -gettxinfo <TX_ID>: Gets transaction information.
• ./qubic-cli -checktxontick <TICK_NUMBER> <TX_ID>: Checks if a transaction is included in a tick.
• ./qubic-cli -checktxonfile <TX_ID> <TICK_DATA_FILE>: Checks if a transaction is included in a tick based on a file.
• ./qubic-cli -readtickdata <FILE_NAME> <COMPUTOR_LIST>: Reads tick data from a file.
• ./qubic-cli -sendcustomtransaction <TARGET_IDENTITY> <TX_TYPE> <AMOUNT> <EXTRA_BYTE_SIZE> <EXTRA_BYTE_IN_HEX>: Performs a custom transaction.
• ./qubic-cli -dumpspectrumfile <SPECTRUM_BINARY_FILE> <OUTPUT_CSV_FILE>: Dumps spectrum file into CSV.
• ./qubic-cli -dumpuniversefile <UNIVERSE_BINARY_FILE> <OUTPUT_CSV_FILE>: Dumps universe file into CSV.
• ./qubic-cli -dumpcontractfile <CONTRACT_BINARY_FILE> <CONTRACT_ID> <OUTPUT_CSV_FILE>: Dumps contract file into CSV.
• ./qubic-cli -makeipobid <CONTRACT_INDEX> <NUMBER_OF_SHARE> <PRICE_PER_SHARE>: Participates in an IPO.
• ./qubic-cli -getipostatus <CONTRACT_INDEX>: Views IPO status.
• ./qubic-cli -getsysteminfo: Views current system status.

Each command is designed to facilitate interaction with the blockchain efficiently and effectively, allowing for a seamless development experience.