Documentation

Quickstart

The devnet contract path is Solana-native. SDK examples on this page are wrapper targets: the wrapper must build the compact receipt fields, proof instruction, token delegate, PDAs, and masterpool accounts before sending the transaction.

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 should prepare receipt hashes first, then submit the prepared receipt with a gateway-capable signer proof and payer payment delegate.

TypeScript

const prepared = await cf.receipts.prepare({
  providerWallet,
  payer: connectedWallet.publicKey,
  payerUsdcToken,
  requestNonce,
  metadata: {
    model: 'model-l-001',
    unit: 'tokens',
  },
  promptTokens: 420,
  completionTokens: 180,
  chargeUsdc: '0.025000',
})

const receipt = await cf.receipts.submit(prepared, {
  gatewaySigner,
  paymentDelegate,
})

console.log(receipt.receiptPda)
console.log(receipt.economicRecordPda)

Python

prepared = cf.receipts.prepare(
    provider_wallet=provider_wallet,
    payer=connected_wallet.public_key,
    payer_usdc_token=payer_usdc_token,
    request_nonce=request_nonce,
    metadata={"model": "model-l-001", "unit": "tokens"},
    prompt_tokens=420,
    completion_tokens=180,
    charge_usdc="0.025000",
)

receipt = cf.receipts.submit(
    prepared,
    gateway_signer=gateway_signer,
    payment_delegate=payment_delegate,
)

Rust

let prepared = cf.receipts().prepare()
    .provider_wallet(provider_wallet)
    .payer(connected_wallet.pubkey())
    .payer_usdc_token(payer_usdc_token)
    .request_nonce(request_nonce)
    .metadata_model("model-l-001")
    .metadata_unit("tokens")
    .prompt_tokens(420)
    .completion_tokens(180)
    .charge_usdc("0.025000")
    .build()
    .await?;

let receipt = cf.receipts()
    .submit(prepared)
    .gateway_signer(gateway_signer)
    .payment_delegate(payment_delegate)
    .send()
    .await?;

Current devnet contract shape

The SDK wrapper target maps to `attestation.submit_receipt`. The contract does not accept model IDs or endpoint metadata as direct receipt fields; those values belong in metadata that the wrapper hashes.

Gateway wrapper target

A gateway API may collect receipt metadata, but it must create or return a Solana transaction that follows the current devnet contract shape. It is not a contract-native REST endpoint.

POST /devnet/receipt-transactions
{
  "providerWallet": "<provider-wallet>",
  "payer": "<payer-wallet>",
  "payerUsdcToken": "<payer-usdc-token>",
  "requestNonce": "<client-generated-nonce>",
  "metadata": {
    "model": "model-l-001",
    "unit": "tokens"
  },
  "promptTokens": 420,
  "completionTokens": 180,
  "chargeUsdc": "0.025000"
}

The gateway wrapper response should contain a transaction or signing payload that includes the ed25519 proof instruction and `attestation.submit_receipt` accounts.

Gateway selection

Applications or gateways choose the provider before receipt submission. The on-chain programs record the provider wallet, payer, payment amount, token usage, receipt hash, and epoch weights.

Provider

Providers register one wallet-controlled ProviderAccount and stake Test USDC on devnet.

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

Models

Model identifiers are off-chain labels used by applications and gateway directories. The current on-chain receipt stores compact hashes, wallet identities, token counts, payment amount, and epoch weights.

Protocol

ClawFarm Phase 1 is a receipt-driven 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

ATTESTATION LAYER
  ProviderSigner records · Compact receipts · Challenge lifecycle · Finalization authority

MASTERPOOL LAYER
  ProviderAccount · Test USDC split · Epoch weight · Locked CLAW streams · Vault accounting

Smart contracts

Receipt lifecycle

1. Wallet authorizes bounded Test USDC settlement through a payer token delegate.
2. App or gateway prepares request_nonce_hash, metadata_hash, charge_atomic, and receipt_hash.
3. A configured gateway-capable signer signs receipt_hash, and the transaction includes the ed25519 proof instruction.
4. Attestation submits the compact receipt and records payment through masterpool CPI.
5. Masterpool splits Test USDC into provider-pending and treasury vaults.
6. Receipt survives or fails the challenge window.
7. Finalized receipts activate buyer/provider epoch weight and release provider pending USDC.
8. Finalized epochs create locked CLAW streams for claimable rewards.

Phase 1 economics

Challenges

Devnet parameters

Reproducibility

Contract state and builds should be verified against the current clawfarm-masterpool repository.

Devnet state check

npx clawfarm phase1 status --cluster devnet

Contract build

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

Resources

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