# The protocol spec Record types, the reference graph between them, the path a contract moves through, and the rules that keep a contract honest. - [Record types](#record-types) - [Record graph](#record-graph) - [Lifecycle](#lifecycle) - [Authority & validation](#authority--validation) - [Settlement](#settlement) - [Events](#vm-lifecycle-events) - [Compute types](#compute-types) More: [Trust & policy](trust.md), [Security & verification](security.md), [Workload Identity Federation](workload-identity.md), [Gateway](gateway.md). The full reference, with the code behind each rule: [protocol/README.md](../../docs/protocol/README.md) and [the glossary](../../docs/protocol/glossary.md). ## Record types All records live in AT Protocol repositories. Cross-record references use `com.atproto.repo.strongRef`: a `{$type, uri, cid}` pointer that content-addresses the target. All market NSIDs carry the `com.publicdomainrelay.temp.*` prefix (pre-release namespace). ### `compute.vm`: VM specification Describes the desired machine: cpus, mem, disk, network, a role, cloud-init `user_data`, and an optional location. `kind: deno` asks for a Deno sandbox instead of a VM. ```yaml cpus: 2 mem: 4G disk: 40G network: 500G role: my-cool-role user_data: | #cloud-config runcmd: - [sh, -c, "echo hi"] location: {country: USA, region: west} ``` ### `market.rfp`: RFP envelope Wraps a strong reference to the VM record: this is what the requester publishes and sends to the bidders it discovered. ```yaml domain: compute payload: {uri: at://did:plc:alice/com.publicdomainrelay.temp.compute.vm/3mm3d, cid: bafyrei...vm} policies: [{uri: ..., cid: ...}] submitBid: https://... signatures: [...] ``` ### `market.bids.free`: free pricing payload Zero-cost bid: the default, and the only one written today. A reason string and signatures. ```yaml reason: free cost: 0 signatures: [...] ``` ### `market.bids.x402`: pricing payload Cost (in the currency's smallest unit), currency, frequency, prepay and a settlement URL: the economic terms of a paid bid. Defined in the lexicons; no bidder writes it today. ```yaml cost: 100000 currency: USDC frequency: hourly prepay: true url: https://compute-contract.bob.example/receipt ``` ### `market.bid`: bid envelope Binds a pricing payload to a specific RFP by strong reference; `config` is the VM's workload identity issuer. ```yaml rfp: {uri: ..., cid: ...} payload: {uri: ..., cid: ...} config: {uri: ..., cid: ...} signatures: [...] ``` ### `market.accept`: accept The requester locks in a chosen bid, referencing both the RFP and the winning bid. ```yaml rfp: {uri: ..., cid: ...} bid: {uri: ..., cid: ...} submitEvent: https://... signatures: [...] ``` ### `market.receipt`: receipt The provider's proof it took the contract: anchors the full contract chain, and its `cid` binds it to the accept. ```yaml rfp: {uri: ..., cid: ...} bid: {uri: ..., cid: ...} accept: {uri: ..., cid: ...} payload: {uri: ..., cid: ...} cid: bafyrei...binding signatures: [...] ``` ## Record graph Every envelope points backward by strong reference: follow the arrows from a receipt and you can rebuild the whole contract. ``` VM <- RFP rfp.payload -> vm RFP <- Bid -> bids.free bid.rfp -> rfp, bid.payload -> bids.free RFP <- Accept -> Bid accept.rfp + accept.bid Receipt -> RFP + Bid + Accept ``` ## Lifecycle | state | entered when | next | | --- | --- | --- | | RFP open | the requester writes the VM record and the RFP | bidding | | bidding | bidders take the RFP from `submitRfp` or the relays | accepted, or no bids | | no bids | nobody answered | a new RFP after a backoff, until the deadline; then Failed | | Failed | no bid passes the policy, or the winner is denied | terminal | | accepted | the requester writes the accept | receipt | | receipt | the provider provisions and writes the receipt | Held | | Held | the guest is on the network with its host keys | released | | released | the requester writes `vm.delete`, the provider `vm.terminated` | terminal | Every branch: [protocol/flow.md](../../docs/protocol/flow.md#when-it-does-not-go-that-way). ## Authority & validation Rules a provider checks before it provisions, and a requester before it holds: - The accept's signature, the accepted bid being the provider's own bid for that RFP, and the accept's author being the RFP's author. - The RFP must carry a valid inline `network.attested` signature by the requester; every bid, accept, receipt and event carries one by its author. - A full host refuses the accept (`submitAccept` answers 409 `CapacityExceeded`) before any receipt. - The receipt's `cid` must bind to the referenced accept record (`VerifyReceipt`; a bad one fails the contract `ReceiptInvalid`). - For `vm.delete`: the event's author must be the accept's author. ## Settlement Free settlement is what runs today: the accept carries no payment and the receipt follows it. The lexicons also define `accepts.free`, `accepts.x402`, `receipts.free` and `receipts.x402` for a paid flow; none is written today. ## VM lifecycle events `market.event` records, submitted with `submitEvent`, each referencing the receipt it belongs to. | event | payload NSID | written when | | --- | --- | --- | | `vm.hostKeys` | `com.publicdomainrelay.temp.compute.events.vm.hostKeys` | the guest bound its ssh host key | | `vm.onNetwork` | `com.publicdomainrelay.temp.compute.events.vm.onNetwork` | the guest is on the network (its iroh ticket; per tunnel an https URL or a WebRTC fingerprint) | | `vm.delete` | `com.publicdomainrelay.temp.compute.events.vm.delete` | the requester is done: accept author only | | `vm.terminated` | `com.publicdomainrelay.temp.compute.events.vm.terminated` | the provider stopped the VM, with a reason | | `vm.memoryPressure`, `vm.oomKilled` | `com.publicdomainrelay.temp.compute.events.vm.*` | the VM's memory crossed a threshold or was OOM-killed | | `vm.sandbox` | `com.publicdomainrelay.temp.compute.events.vm.sandbox` | a Deno sandbox ended, with its output | Guest events (`compute.events.guest.*`: keys, sealed WebRTC signals, secrets) ride the same envelope: [guest-events.md](../../docs/protocol/guest-events.md). ## Compute types The RFP's `compute.vm` is the one worked through above: a Firecracker VM by default. With `kind: deno` the same market, bid and receipt records carry a Deno sandbox that runs the user data as its program, on a bidder that opts in (`install bidder --compute-kinds vm,deno`). ## More on the protocol - [Trust & policy](trust.md): how bidders and requesters each choose who they deal with. - [Security & verification](security.md): signed records, content addressing, and how to verify a receipt yourself. - [Workload Identity Federation](workload-identity.md): how a workload gets a scoped credential instead of a secret. - [Gateway](gateway.md): Kubernetes clusters whose nodes the gateway requests on the market for you. - [How it works](how-it-works.md): the RFP -> bid -> accept -> receipt walk. - [Marketplace](marketplace.md): the live market. - [Get started](get-started.md): commands for a requester or a provider. - [About](about.md): why this exists and where it is headed.