Skip to main content

Celium Collateral Contract

1. Introduction​

What is the Collateral Contract?​

The Collateral Contract is a smart contract operating on a Bittensor EVM-compatible network. It serves as a decentralized escrow system where compute providers (miners) deposit collateral to back their services. This contract is the foundation of trust and accountability on the network, ensuring that miners are financially incentivized to provide reliable and honest compute resources.

Why It Matters​

In a decentralized compute network, trust is paramount. Customers and validators need assurance that the miners they engage with will perform their tasks correctly and without malicious intent. The collateral contract provides this assurance by:

  • Securing Services: Miners lock up capital (TAO tokens) as a security deposit. This collateral can be slashed if they fail to meet their obligations.
  • Building Reputation: A miner with substantial collateral signals a serious commitment to the network.
  • Enabling Trustless Interactions: It allows parties who don't know each other to engage in high-value transactions with a reduced risk of fraud or non-performance.

Target Audience​

This document is intended for:

  • Miners (Compute Providers): Individuals or organizations providing compute resources (Executors) to the network.
  • Subnet Owners (Trustees): The owner of the subnet who is responsible for managing the collateral contract and acting as its final arbiter.
  • Validators: Entities responsible for evaluating the performance of miners' executors and assigning scores which inform the Trustee's decisions.
  • Customers: Users of the compute resources who benefit from the security provided by the collateral system.

2. Core Concepts​

Collateral​

The security deposit, denominated in TAO, that a miner locks into the contract for each of their compute machines (Executors). This deposit is a prerequisite for an executor to be eligible for scores and rewards from validators.

Executor​

A single compute resource (e.g., a server or VM) provided by a miner. Each executor is identified by a unique ID (executorId) and must be backed by its own collateral.

Trustee​

The owner of the subnet, who holds the ultimate authority to slash collateral or deny reclaim requests based on evidence of miner malpractice.

Validator​

An entity in the subnet responsible for testing and scoring the performance and honesty of miners' executors. The reports and scores from validators serve as crucial evidence for the Trustee's decisions.

Slashing​

The act of seizing a miner's collateral as a penalty for malicious behavior. Slashed funds are burned. This action is performed by the Trustee.

Reclaiming​

The process by which a miner can withdraw their collateral. This process includes a time-delayed safety window (DECISION_TIMEOUT) during which the Trustee can intervene if necessary.

3. How It Works: The Lifecycle of Collateral​

The process follows a clear lifecycle from depositing funds to eventually reclaiming them.

Collateral Architecture

  1. Setup: A miner first needs an EVM-compatible wallet (like MetaMask) and TAO tokens on the correct network.
  2. Deposit: The miner uses the provided CLI to add an executor and deposit TAO as collateral for it. The first deposit for an executorId permanently links that executor to the miner's wallet address.
  3. Active Service: The executor is now active and can be hired for compute jobs, with its collateral serving as a security bond.
  4. Initiate Reclaim: When the miner wishes to decommission the executor, they initiate a reclaim request. This locks the reclaimable collateral in a "pending" state.
  5. Trustee Review (Decision Timeout): A waiting period begins. During this time, the Trustee can review the miner's record. If there are any unresolved issues or disputes (e.g., the executor failed a recent job), the Trustee can deny the reclaim request.
  6. Finalize Reclaim: If the timeout period passes without the Trustee denying the request, anyone (including the miner) can finalize the reclaim. The contract then transfers the collateral back to the miner's wallet.
  7. Slashing (Exception): If at any point an executor is proven to have acted maliciously, the Trustee can slash its entire collateral, which is then burned.

4. For Miners: Step-by-Step Guide​

Follow these steps to set up your executors and manage your collateral.

Step 1: Prepare an EVM-Compatible Wallet (ETH)​

Your collateral is managed through an EVM-compatible wallet. You need the private key of this wallet to authorize transactions. We recommend using MetaMask, a widely-trusted browser extension wallet.

  1. Install MetaMask: If you don't have it, install the MetaMask browser extension.
  2. Create a New Wallet: Follow the instructions to create a new wallet. Crucially, write down your 12-word Secret Recovery Phrase and store it in a secure, offline location. This is the only way to recover your wallet if you lose access.
  3. Add the Bittensor Network:
    • Open MetaMask and click the network dropdown at the top-left.
    • Select "Add network" and then "Add a network manually".
    • Enter the network details for the Bittensor chain you are using (e.g., Mainnet, Testnet). You can find the specific RPC URL and Chain ID in the official Bittensor or Datura documentation.
  4. Get Your Private Key:
    • In MetaMask, click the three dots (⋮) next to your account name.
    • Select "Account details", then click "Show private key".
    • Enter your password to reveal the key. Never share this key with anyone.
    • Copy this private key. You will need it to configure your miner environment.

Step 2: Associate EVM-Compatible Address with the Hotkey​

To let validators to identify your ETH address, you need to associate ETH address with your current hotkey in SN 51.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py associate-eth

Step 3: Manage Executors and Collateral via CLI​

You will interact with the collateral contract using a command-line interface (CLI). All commands should be run from within your miner's runtime environment (e.g., a Docker container).

Add an Executor​

Adds a new compute machine to the network. Skip if you've already done.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py add-executor \
--address <ip> \
--port <port>

This will output a unique executor_id. Save this ID, as you will need it for all future actions related to this executor.

Deposit Collateral​

Important: To be eligible for scores and rewards from validators, your executor must have a minimum amount of collateral deposited. This ensures you have enough collateral to cover 24 hours of rental fees for your machine.

The required amount is calculated as follows: required_collateral = REQUIRED_DEPOSIT_AMOUNT[GPU_TYPE] * GPU_COUNT

Rental prices in TAO per GPU type can be found here

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py deposit-collateral \
--address <ip> \
--port <port> \
--deposit_amount <amount_in_tao>
  • --address: IP address of executor.
  • --port: Port for executor.
  • --deposit_amount: The amount of TAO to deposit. Must meet the MIN_COLLATERAL_INCREASE set by the contract.

Check Executor Collateral​

View the current collateral for an executor.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py get-executor-collateral \
--address <ip> \
--port <port>

Reclaim Collateral​

Initiate the process to withdraw all available collateral from an executor. This starts the DECISION_TIMEOUT.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py reclaim-collateral \
--executor_uuid <executor_id>

View Your Reclaim Requests​

Check the status of all your pending and past reclaim requests.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py get-reclaim-requests

This will show details including the reclaim_request_id and its current status.

Finalize a Reclaim Request​

After the DECISION_TIMEOUT has passed, finalize the request to receive your funds.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py finalize-reclaim-request \
--reclaim_request_id <reclaim_request_id>

Remove an Executor​

Remove an executor from your list. Note: This can only be done if the executor has zero collateral.

docker exec -it miners-miner-1 \
pdm run /root/app/src/cli.py remove-executor \
--address <address> \
--port port

5. Key Roles in the Ecosystem​

The Trustee (Subnet Owner)​

The subnet owner is entrusted with the TRUSTEE role. Their responsibility is to act as the final, trusted arbiter for the collateral contract.

  • Adjudicate Disputes: The Trustee reviews evidence to make final decisions on slashing.
  • Deny Reclaims: The Trustee will deny a reclaim request if the associated executor is currently rented by a customer. This prevents miners from withdrawing collateral for machines that are in active use.
  • Slash Collateral: The Trustee will slash an executor's collateral if a miner is proven to have removed the machine or its rental container from the network while it was actively rented. This is considered a critical failure and breach of contract with the customer.

Validators​

Validators are the backbone of network quality control. They test executors and assign scores that determine a miner's reputation and rewards. A validator's primary rule is to only score and reward executors that have sufficient collateral.

Their responsibilities include:

  • Verify Collateral: Before interacting with an executor, a validator first checks if its deposited collateral meets the minimum requirement. The formula is: Required Collateral = (Rental Price per GPU per Hour) * (Number of GPUs) * 24. Executors below this threshold are ignored.
  • Evaluate Performance: For executors that meet the collateral requirement, validators constantly send test jobs and score them on speed, correctness, and uptime.
  • Report Malpractice: If a validator detects that a rented machine has suddenly gone offline or been removed from the network, they report it. This reporting serves as crucial data for the Trustee to make a slashing decision.

6. FAQ​

Q: What happens if I lose the private key to my wallet?
A: Your funds are irrecoverable. The private key is the only thing that proves your ownership. This is why it is critical to back up your Secret Recovery Phrase.

Q: Can I add more collateral to an executor?
A: Yes. You can call the deposit-collateral command multiple times for the same executor.

Q: Why isn't my executor receiving scores or rewards?
A: The most common reason is insufficient collateral. Validators will only score executors that have enough collateral deposited to cover 24 hours of their market rental price. Please use the formula (Rental Price per GPU per Hour) * (Number of GPUs) * 24 to ensure you have deposited enough TAO.

Q: Under what circumstances will my collateral be slashed?
A: Slashing is the most severe penalty and is reserved for cases where you remove an executor (or its rental container) from the network while it is actively being rented. This action harms the customer and damages the network's reputation, resulting in the loss of your full collateral for that executor.

Q: Why was my reclaim request denied?
A: A reclaim request will be denied by the Trustee (the subnet owner) if the executor is currently being rented by a customer. You must wait for the rental period to end before you can successfully reclaim your collateral.

Q: Who is the Trustee?
A: The Trustee is the owner of the subnet. They are the designated address with the special authority to slash collateral and deny reclaims to maintain the health and integrity of their subnet.

Q: Do I still need to finalize reclaim request when my collateral is slashed?
A: Yes, you still need to finalize reclaim request for your executor though the collateral for that executor is slashed. This is because if you don't fianlize the reclaim request, you can't request reclaim for that executor in the future since previous reclaim is still pending.