Documentation

Quickstart

The devnet contract path is Solana-native. SDK examples on this page are wrapper targets: the wrapper must build payment indexes, payment nonce hashes, payer token delegates, epoch PDAs, Merkle settlement artifacts, and masterpool v3 accounts before sending transactions.

This page separates current devnet v3 behavior from mainnet targets. Devnet v3 is live with 300-second epochs, a 60-second challenge window, a 3 percent payment-tax cap, zero upfront provider-stake transfer, and proof-based claims. The mainnet target keeps a 1-hour epoch, treasury split and buyback policy, bounded governance, and protocol-owned liquidity as whitepaper-level launch commitments.

Install

npm install @clawfarm/sdk

Configure devnet

import { ClawFarm } from '@clawfarm/sdk'

const cf = new ClawFarm({
  cluster: 'devnet',
})

SDK wrapper target

A contract-aligned wrapper records wallet-paid usage through masterpool v3, then settles ended epochs through aggregate roots and Merkle claims.

TypeScript

const payment = await cf.payments.record({
  providerWallet,
  payer: connectedWallet.publicKey,
  payerUsdcToken,
  paymentDelegate,
  paymentIndex: 42n,
  paymentNonceHash,
  baseChargeUsdc: '0.025000',
  taxRateBps: 300,
  taxSweepThresholdAmount: 0n,
})

const settlement = await cf.epochs.commitSettlement({
  epochId: payment.epochId,
  usageRoot,
  providerRoot,
  buyerRoot,
  artifactHash,
  artifactUriHash,
  totals: payment.epochTotals,
  providerPoolClaf,
  buyerPoolClaf,
})

await cf.epochs.finalizeSettlement({ epochId: settlement.epochId })

await cf.epochs.claimProviderEpoch({
  epochId: settlement.epochId,
  leafIndex,
  totalProviderUsdc,
  providerWeight,
  providerClafReward,
  proof,
})

await cf.epochs.claimBuyerReward({
  epochId: settlement.epochId,
  leafIndex,
  buyerWeight,
  buyerClafReward,
  proof,
})

Python

payment = cf.payments.record(
    provider_wallet=provider_wallet,
    payer=connected_wallet.public_key,
    payer_usdc_token=payer_usdc_token,
    payment_delegate=payment_delegate,
    payment_index=42,
    payment_nonce_hash=payment_nonce_hash,
    base_charge_usdc="0.025000",
    tax_rate_bps=300,
    tax_sweep_threshold_amount=0,
)

settlement = cf.epochs.commit_settlement(
    epoch_id=payment.epoch_id,
    usage_root=usage_root,
    provider_root=provider_root,
    buyer_root=buyer_root,
    artifact_hash=artifact_hash,
    artifact_uri_hash=artifact_uri_hash,
    totals=payment.epoch_totals,
    provider_pool_claf=provider_pool_claf,
    buyer_pool_claf=buyer_pool_claf,
)

cf.epochs.finalize_settlement(epoch_id=settlement.epoch_id)

cf.epochs.claim_provider_epoch(
    epoch_id=settlement.epoch_id,
    leaf_index=leaf_index,
    total_provider_usdc=total_provider_usdc,
    provider_weight=provider_weight,
    provider_claf_reward=provider_claf_reward,
    proof=proof,
)

cf.epochs.claim_buyer_reward(
    epoch_id=settlement.epoch_id,
    leaf_index=leaf_index,
    buyer_weight=buyer_weight,
    buyer_claf_reward=buyer_claf_reward,
    proof=proof,
)

Rust

let payment = cf.payments().record()
    .provider_wallet(provider_wallet)
    .payer(connected_wallet.pubkey())
    .payer_usdc_token(payer_usdc_token)
    .payment_delegate(payment_delegate)
    .payment_index(42)
    .payment_nonce_hash(payment_nonce_hash)
    .base_charge_usdc("0.025000")
    .tax_rate_bps(300)
    .tax_sweep_threshold_amount(0)
    .send()
    .await?;

let settlement = cf.epochs().commit_settlement()
    .epoch_id(payment.epoch_id)
    .usage_root(usage_root)
    .provider_root(provider_root)
    .buyer_root(buyer_root)
    .artifact_hash(artifact_hash)
    .artifact_uri_hash(artifact_uri_hash)
    .totals(payment.epoch_totals)
    .provider_pool_claf(provider_pool_claf)
    .buyer_pool_claf(buyer_pool_claf)
    .send()
    .await?;

cf.epochs().finalize_settlement(settlement.epoch_id).send().await?;

cf.epochs().claim_provider_epoch()
    .epoch_id(settlement.epoch_id)
    .leaf_index(leaf_index)
    .total_provider_usdc(total_provider_usdc)
    .provider_weight(provider_weight)
    .provider_claf_reward(provider_claf_reward)
    .proof(proof.clone())
    .send()
    .await?;

cf.epochs().claim_buyer_reward()
    .epoch_id(settlement.epoch_id)
    .leaf_index(leaf_index)
    .buyer_weight(buyer_weight)
    .buyer_claf_reward(buyer_claf_reward)
    .proof(proof)
    .send()
    .await?;

Current devnet contract shape

The SDK wrapper target maps to `clawfarm_masterpool_v3`. The current masterpool records payments directly, accumulates epoch totals, commits settlement roots, and verifies Merkle proofs for claims. Model IDs, endpoint metadata, and price metadata remain off-chain inputs to wrapper artifacts.

Gateway wrapper target

A gateway API may collect usage metadata, but it must create or return Solana transactions that follow the current masterpool v3 shape. It is not a contract-native REST endpoint.

POST /devnet/payment-transactions
{
  "providerWallet": "<provider-wallet>",
  "payer": "<payer-wallet>",
  "payerUsdcToken": "<payer-usdc-token>",
  "paymentIndex": "42",
  "paymentNonceHash": "<client-generated-nonce-hash>",
  "metadata": {
    "model": "model-l-001",
    "unit": "tokens"
  },
  "baseChargeUsdc": "0.025000",
  "taxRateBps": 300,
  "taxSweepThresholdAmount": "0"
}

The gateway wrapper response should contain a transaction or signing payload for `record_payment_v3`. Epoch settlement wrappers later commit aggregate roots and claim proofs.

Gateway selection

Applications or gateways choose the provider before payment recording. Masterpool v3 records payment identities, base charge, tax, epoch accumulator state, and payment bitmap state; finalized epoch roots later carry usage, provider, and buyer allocation data.

Provider

Providers register one wallet-controlled ProviderAccountV3. Current registration initializes staking state without requiring an upfront collateral transfer.

The masterpool account does not store endpoint infrastructure; applications and gateways bind endpoint metadata outside the on-chain provider account.

Models

Model identifiers remain off-chain metadata used by applications and gateway directories. Masterpool v3 records payment and settlement artifacts, not model IDs.

Protocol

ClawFarm Phase 1 is a payment-driven epoch settlement protocol for AI inference on Solana.

Architecture

WALLET / APP LAYER
  Users · Builders · Agents · Provider operators

OFF-CHAIN DIRECTORY
  Provider choices · Model labels · Endpoint metadata · Price metadata

MASTERPOOL V3 PAYMENT LAYER
  ProviderAccountV3 · EpochPaymentAccumulator · EpochPaymentBitmap · Treasury and provider pending vaults

EPOCH SETTLEMENT LAYER
  EpochSettlementBatch · EpochSettlementChallenge · EpochSettlementRoot · EpochClaimBitmap · Merkle proof claims

Smart contracts

Payment lifecycle

1. Wallet authorizes bounded Test USDC settlement through a payer token delegate.
2. App or gateway prepares payment_index, payment_nonce_hash, base_charge_atomic, and tax_rate_bps.
3. Masterpool v3 records payment, transfers tax to treasury, transfers base charge to provider pending, and marks the epoch payment bitmap.
4. Epoch payment accumulator stores payment count plus total base, tax, and gross USDC.
5. After the epoch ends, an authorized submitter commits usage, provider, and buyer Merkle roots into an EpochSettlementBatch.
6. Settlement challenges may invalidate a pending batch until accepted or rejected by authority.
7. After the challenge deadline, finalization writes an EpochSettlementRoot.
8. Providers and buyers claim USDC or CLAF with Merkle proofs against the finalized root.

Phase 1 economics

Challenges

Devnet parameters

Reproducibility

Contract builds should be verified against the current clawfarm-masterpool repository. The command below exposes the v3 bootstrap wrapper surface for testnet/devnet setup flows.

V3 wrapper command surface

yarn phase1:v3:bootstrap:testnet --help

Contract build

git clone <contract-source-url>
cd clawfarm-masterpool
anchor build
anchor test

Resources

Reference files and mirrors for developers, providers, and auditors.