The protocol spec
Record types, the reference graph between them, the path a contract moves through, and the rules that keep a contract honest.
More: Trust & policy, Security & verification, Workload Identity Federation, Gateway. The full reference, with the code behind each rule: protocol/README.md and the glossary.
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.
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.
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.
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.
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.
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.
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.
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.
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.attestedsignature by the requester; every bid, accept, receipt and event carries one by its author. - A full host refuses the accept (
submitAcceptanswers 409CapacityExceeded) before any receipt. - The receipt's
cidmust bind to the referenced accept record (VerifyReceipt; a bad one fails the contractReceiptInvalid). - 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.
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: how bidders and requesters each choose who they deal with.
- Security & verification: signed records, content addressing, and how to verify a receipt yourself.
- Workload Identity Federation: how a workload gets a scoped credential instead of a secret.
- Gateway: Kubernetes clusters whose nodes the gateway requests on the market for you.
- How it works: the RFP -> bid -> accept -> receipt walk.
- Marketplace: the live market.
- Get started: commands for a requester or a provider.
- About: why this exists and where it is headed.