Compute contracts

Pre-launch technical reference. Any token amounts, fees, collateral, rewards, or economic behavior below describe experimental testnet software, not finalized launch terms or promised benefits. Launch tokenomics remain to be determined.

These are the contracts that let a machine operator sell compute on Citrate Market and let a buyer pay for verified work. Six contracts form one settlement loop: a buyer posts a job, an operator runs it, the result is verified by tier, and payment settles on the public ledger. This page is for operators, buyers, and anyone integrating against the marketplace.

What it is

Citrate Market is the part of the public ledger where compute is bought and sold. An operator runs a Citrate Node off-chain to do the actual work, on hardware they control; the contracts here record the agreement, hold the escrow, decide whether the returned work was valid, and split the payment. The heavy data, the model weights and the inputs, never live on-chain. What the ledger keeps is a hash, a proof, and a receipt.

The loop has six parts:

• ComputeMarketplace runs the single-provider job lifecycle: post, bid, assign, execute, verify, settle.
• ComputePool and ComputePoolTraining are the multi-provider variants, one for pooled inference with a throughput guarantee, one for distributed training across many workers.
• ComputeVerifier decides whether a returned result is valid, by one of three tiers.
• ComputePricingOracle maps compute cost and SALT price so a job can be quoted.
• BulkComputeGateway lets an institution pre-fund credits with a stablecoin and spend them later.

All six share one governance pattern. Each inherits a Governable mixin with a two-step transfer (transferGovernance then acceptGovernance), an onlyGovernance modifier, and a governance() reader. Five of the six also inherit ReentrancyGuard; the pricing oracle does not move value, so it does not need it.

Operators sell into this surface through Operators, sell compute and run the daemon described in run a node. The on-chain verification leans on the compute precompiles, in particular the Halo2-KZG inference verifier at 0x0108.

How to use it

The single-provider path, from a buyer's side, runs like this.

1. Quote the work. Ask ComputePricingOracle what one PFLOP-hour costs in SALT with saltPerPflopHour(), or estimate a specific job with estimateJobCost(modelHash, inputTokens, outputTokens, verificationTier).
2. Post the job. Call postJobWithMethod(...) on ComputeMarketplace with the model hash, the input hash, a maximum price, a verification tier, a payment method, a bid window, and an execution window. The escrow is taken from msg.value in SALT, or debited from bulk credits if you chose that method.
3. Wait for bids and assign. Operators call bidOnJob. Anyone can then call assignBestBid, which scores the bids on price, reputation, current load, and verification fit, and assigns the winner.
4. The operator executes. They call startExecution, optionally post a Tier-1 commitment with submitCommitment, then return the result with submitResult. Submitting the result triggers verification inline.
5. Settle. Once the verifier returns Valid and no dispute is open, call completeJob. Payment splits into the provider's share, a burn, and a treasury fee.

To sell instead of buy, register first: registerProvider(supportedModels) with a stake of at least MIN_PROVIDER_STAKE, then bid on jobs that match your models. To pool with other operators, see ComputePool below; to join a training run, see ComputePoolTraining.

Reference

The audited public surface of each contract, with the function names as they appear in source. The canonical truth is the Solidity in contracts/src; treat ABIs as coming from the published package, not hand-copied from here.

ComputeMarketplace

contracts/src/ComputeMarketplace.sol, contract ComputeMarketplace is ReentrancyGuard, Governable. The single-provider job lifecycle, with escrow in SALT or bulk credits, a burn and a treasury fee on settlement, provider staking and slashing, timeouts, and disputes. The constructor takes a verifier and a treasury address and deploys a fresh Burner at construction.

Views include getJob, getJobBids, getProvider, getProviderCount, and providerSupportsModel. Governance setters are setTreasury, setSlashingContract, setBurner, setBulkGateway, and setPricingOracle.

The settlement receipt is one event:

event JobCompleted(
    uint256 indexed jobId,
    address indexed provider,
    uint256 providerPayment,
    uint256 burned,
    uint256 treasuryFee
);

The split is 95% to the provider, 2.5% burned, and 2.5% to the treasury. The burn and the fee each equal the price divided by BME_BURN_DIVISOR and TREASURY_DIVISOR, both 40. The lifecycle is captured in enum JobState { Posted, Bidding, Assigned, Executing, Verifying, Completed, Expired, Timeout, Failed, Disputed }, and the payment choice in enum PaymentMethod { SALT, BulkCredits }.

ComputePool

contracts/src/ComputePool.sol, contract ComputePool is ReentrancyGuard, Governable. Multi-provider GPU pools with per-GPU staking, payment shared in proportion to GPU contribution, slashing on a missed throughput guarantee, and a coordinator election. The constructor takes no arguments; the deployer becomes governance.

Views include getPool, getPoolMembers, getPoolGPUCount, getMember, getJob, isPoolSolvent, coordinatorFor(poolId, epoch), and decodePoolJobSpec. The pool kinds are enum PoolMode { InferencePool, DataParallel, PipelineParallel }.

ComputePoolTraining

contracts/src/ComputePoolTraining.sol, contract ComputePoolTraining is ReentrancyGuard, Governable. A distributed-training lifecycle: recruit workers, commit one Merkle root per epoch, challenge a step with a fraud proof, finalize. Only the per-epoch roots are stored on-chain; the individual step commitments live off-chain in the training mesh. The constructor takes a governance address.

Views include getJob, getWorker, getWorkerList, getEpochRoot, getChallenge, and heldStake. The job states are enum JobState { Recruiting, Training, Awaiting, Finalized, Aborted } and a challenge runs through enum ChallengeState { None, Voting, ResolvedUphold, ResolvedReject }.

ComputeVerifier

contracts/src/ComputeVerifier.sol, contract ComputeVerifier is ReentrancyGuard, Governable. The output-verification dispatcher. Every entry point is onlyMarketplace: the marketplace configures a job's tier, then asks the verifier to rule. There are three tiers, plus a bisection-bounded dispute path. The constructor takes the marketplace address.

The tiers are enum VerificationTier { Commitment, ZKProof, TEE } and the verdict is enum VerificationResult { Pending, Valid, Invalid }. A job above VALUE_THRESHOLD (10 SALT) cannot settle on a bare commitment; the verifier upgrades it to the ZK tier. The constant INFERENCE_PROOF_VERIFY = address(0x0108) points at the Halo2-KZG verifier precompile, described in precompiles. The ZK tier is a research preview (the v1 circuit is small, not a full-model proof), and hardening is in progress. The TEE tier is inert on chain 40204 today because no TEE oracle is registered with ComputeVerifier (teeOracleCount() returns 0).

ComputePricingOracle

contracts/src/ComputePricingOracle.sol, contract ComputePricingOracle is IComputePricingOracle, Governable (interface at contracts/src/interfaces/IComputePricingOracle.sol). A quorum oracle that maps compute cost in USD cents per PFLOP-hour and SALT price in USD cents, by a 67% committee vote, rate limited to a 10% change per update, with staleness tracking. The constructor takes the two opening prices, both of which must be above zero.

Key constants: QUORUM = 67, MAX_STALENESS = 7200, MAX_PRICE_CHANGE_BPS = 1000, TOKENS_TO_PFLOP_FACTOR = 1e12, and verification multipliers of 1.0x for Commitment, 1.5x for ZK, and 2.0x for TEE.

BulkComputeGateway

contracts/src/BulkComputeGateway.sol, contract BulkComputeGateway is ReentrancyGuard, Governable. Lets an institution buy compute credits in PFLOP-hours with a stablecoin, routed to a treasury and priced through the oracle; an authorized spender, typically the marketplace, debits those credits. The constructor takes a treasury, an oracle, and a governance address.

The receipt is event CreditsPurchased(address indexed institution, address indexed stablecoin, uint256 usdAmount, uint256 creditsReceived, uint256 purchaseIndex).

Design rationale

The split between on-chain record and off-chain work is the whole point. A model run is large and private, so it happens on the operator's own hardware; the ledger keeps only the hash, the proof, and the receipt. That is why ComputeVerifier offers three tiers rather than one. A small job can settle on a cheap commitment, a job above the value threshold must carry a zero-knowledge proof checked by the 0x0108 precompile (a research preview), and a job that needs hardware attestation is designed to require a TEE oracle signature (inert on 40204 until an oracle is registered). The buyer chooses how much assurance to pay for, and the contract enforces a floor for high-value work.

The training pool stores only one Merkle root per epoch. Putting every step commitment on-chain would be ruinous, so the design keeps the steps in the off-chain mesh and lets any worker challenge a step with a fraud proof. The chain has to store little and still adjudicate honestly. Pricing sits behind a quorum oracle rather than a single feed so that no one member can move the price more than 10% or push a stale number through.

Failure modes

These contracts hold escrow and stake, so the failure paths matter.

• A provider misses the execution deadline. Anyone calls timeoutJob, which slashes 5% of the provider's stake. In this build the escrow is refunded to the requester rather than held for reassignment; there is no reassignment path yet.
• A returned result is wrong. The verifier fails closed. A ZK proof that reverts, returns the wrong length, or returns anything other than the success word is treated as Invalid, so a bad proof never settles as valid. Above the value threshold a bare commitment is rejected and upgraded to the ZK tier.
• A buyer disputes a result. They post the 10 SALT dispute bond and the marketplace runs a bounded bisection, at most 10 rounds, with governance or the marketplace resolving the outcome.
• A pool misses its throughput guarantee. Governance calls reportSLAViolation, which slashes 10% of the pool's stake.
• A training worker commits a bad step. A challenger posts the 1 SALT bond and submits a Merkle fraud proof; a committee vote at a quorum of 2 upholds or rejects it, and an upheld challenge slashes the cheating worker.

The pool coordinator election depends on an off-chain coordinator binary to record seeds, because the on-chain coordinatorFor derives randomness from a recent block hash and that is only reliable for the most recent few hundred blocks. Off-chain proof generators for both ZK verification and training Merkle proofs must match the on-chain wire format exactly, or valid-looking proofs will be rejected.

Access and canon

Tier: commercial for the marketplace, pools, gateway, and oracle, and academic for ComputeVerifier, which is the formal-methods and proof surface. These contracts are open on the public ledger and anyone can read them; the full lifecycle, scoring, and settlement design is paid-seat depth.

No secrets appear on this page. There are no private keys, mnemonics, internal hostnames, or credentials. The only hardcoded address is the public protocol precompile 0x0108. Identity verification through VERI, Citrate's in-house verification, is part of membership; node and consensus code do not check operator identity.

Source and verification

• Source: citrate-chain/contracts/src/, in ComputeMarketplace.sol, ComputePool.sol, ComputePoolTraining.sol, ComputeVerifier.sol, BulkComputeGateway.sol, ComputePricingOracle.sol, and the interface interfaces/IComputePricingOracle.sol.
• Audited against citrate-chain SHA 9d5959e.
• Status: Implemented, pre-audit, on testnet 40204. The timeout-reassignment gap, the off-chain coordinator-seed dependency, and the assumed 6-decimal stablecoins are open items noted above and not yet externally audited. Re-verify deployed bytecode with eth_getCode if the chain has been re-rolled.