# CITRATE.md

A starter for coding agents building on Citrate. It describes the network the way an agent needs it:
where the endpoints are, how to deploy, how to ask for a signature, and one example that runs. Nothing
here is marketing. Where a capability is not wired yet, this file says so. Confirm exact signatures and
addresses at https://docs.citrate.ai.

## 1. What this is

Citrate Core is a desktop app that runs a full node on chain 40204 on the developer's machine. It exposes
a local endpoint your agent can call, holds the developer's keys on the device, and gives you a chain you
can read and write. The public testnet RPC is https://rpc.citrate.ai. Mainnet is targeted for Q2 2027;
SALT has no cash value until then.

- Confirm the chain is live: call `eth_chainId` at https://rpc.citrate.ai. It returns `0x9d0c` (40204).
- Explorer: https://explorer.citrate.ai. The deployed-contract table is public.

## 2. Endpoints and SDKs

- Chain RPC: EVM-compatible JSON-RPC. Public testnet at https://rpc.citrate.ai; the local node exposes the
  same interface for reads and writes (see docs for the local port the app binds).
- Inference: OpenAI-shaped and Anthropic-shaped routes, so an existing OpenAI or Anthropic client works by
  changing only its base URL to the local endpoint. See docs.citrate.ai for the local base URL.
- SDKs:
  - TypeScript: `npm i @citratelabs/sdk` (marketplace bindings: `@citratelabs/marketplace-sdk`)
  - Python: `pip install citrate-labs-sdk`

The SDKs wrap settlement, verification, identity, and payments. An agent authenticates via OIDC or
Sign-In-With-Ethereum and deterministically owns a counterfactual ERC-4337 smart account; the SDK computes
and verifies the address on chain, and no one holds a key for the agent.

## 3. The seven precompiles (0x1000 to 0x1004)

Chain 40204 is EVM-compatible, extended with deterministic AI precompiles for inference in the range
0x1000 to 0x1004. They run in deterministic Q16.16 fixed point, so a result computed on one machine
verifies bit-identically on another. Each precompile's address, input encoding, and output encoding are
listed in the docs; read them there rather than guessing an ABI.

## 4. How to deploy

Deployment is EVM-equivalent. Anything Solidity-compatible deploys unchanged against the node or the
public RPC, with your usual toolchain (Foundry, Hardhat, viem, ethers). Point the tool at the node's RPC
and deploy as you would on any EVM chain. Chain id is 40204.

## 5. How to request a signature (the Signature Ceremony)

Your agent never holds the custody key. To move funds or send a transaction on the human's behalf:

1. The agent builds the transaction and proposes it through the SDK.
2. The human approves it once, on their own device, in Citrate Core.
3. That single approval yields exactly one signature. Undecodable transactions are blocked until the human
   acknowledges them.

One approval, one signature. Background helpers (for example messaging) receive a derived, one-way key,
never the custody key. This is the Human In Control model. Build for it: surface what you are asking the
human to sign, in plain terms, before you propose it.

## 6. How to join an apps grove

A grove is a group that pools machines for real work and shares the reward, scored on verified work. An
apps grove scores the apps its members ship: the apps run on members' nodes, and that work scores like any
other. A share link has the shape:

    https://citrate.ai/join/<grove>?by=<inviter>&c=<grove-name>&g=apps

The invitee installs Citrate Core, stakes or accepts a gifted seat, opens the invite in the app, and the
inviter approves them in. Then the developer hands their agent this starter and ships the first app.

## 6b. Paying for membership as an agent (x402)

An agent can buy a one-year Citrate membership over x402 (USDC on Base) through Stripe, without a card
checkout. Request the membership endpoint; when payment is required you receive an HTTP 402 with the
payment requirements (USDC on Base, the price, and the Stripe deposit address) and a `payment-required`
header. Pay the USDC and retry the same resource URL (it carries `?order=<id>`) with an `X-PAYMENT`
authorization; the payment settles through Stripe and the membership is provisioned by the same grant
path as card checkout (vault stake + membership SBT).

- Endpoint: `https://membership.citrate.ai/api/x402` (authenticated; one membership per account).
- Protocol: x402, `exact` scheme, network `eip155:8453` (Base), asset USDC, $48 per year.
- Status: the rail is live code but being enabled. Until the Stripe stablecoin method is approved and the
  facilitator is wired, the endpoint returns HTTP 503 with the reason, never a fake charge. Card checkout
  ($48/yr) is available now.

## 7. One example (illustrative)

A minimal flow: deploy one contract, request one signature, read one result. Confirm the exact SDK calls
at docs.citrate.ai before you run it.

```ts
import { CitrateClient } from "@citratelabs/sdk";

// Talk to the local node the desktop app runs (base URL from docs.citrate.ai).
const citrate = new CitrateClient({ rpcUrl: LOCAL_RPC_URL });

// 1. Deploy an EVM contract with your usual toolchain against chain 40204.
const address = await deployWithFoundry(); // or hardhat / viem / ethers

// 2. Propose a state-changing call. The human approves it once, on device.
//    The promise resolves after the Signature Ceremony returns one signature.
const receipt = await citrate.propose({ to: address, data: encodedCall });

// 3. Read the result back. Reads never need a signature.
const result = await citrate.call({ to: address, data: encodedView });
console.log(receipt.hash, result);
```

## 8. What is not wired yet

- The Commissary catalog in the app is partial. Season 0's apps groves are where its first entries come from.
- Of the agent runtimes, the Hermes adapter is the one that is live.
- macOS (Apple Silicon) is the live build. Linux and Windows are in contract.
- The chain is on testnet and has not had a full external audit; the docs state, module by module, what is
  audited, what is pre-audit, and what is specified but not built.