flow: one compute contract, end to end
- the flow is: Request For Proposal -> Bid -> Accept -> Receipt, then the guest's events, then the release
- the compute contract flow can run purely over the firehose and relays (comms mode
Firehose: no inbound endpoint); themarket.submit*calls are the fast path - every record lives in its author's own repo; the other side reads it with one
getRecord(from a firehose or Jetstream commit, or from themarket.submit*call that names it) - every
market.*record and every event payload carries badge.blue signatures (network.attested.signature: identity.md); they are left out of the records below - the records below are one real contract, from prod: the requester
aliceoa.bsky.socialrequested a 4 vCPU VM from one ofbobvmbuilder.bsky.social's bidders on 2026-11-15 (trimmed;did:plc:lpfuqerea3deuoyrn7ojser4is alice,did:plc:2l2wdry77c7jtucbslstagkjthe bidder) - field by field: market.md, guest-events.md; who is who: identity.md; every NSID: glossary.md
- this page: one real contract with its records; compute-contract-flow-map.md: the owner's end-to-end map of every layer and the flow
The Story
- Alice, Bob and Eve are on the network. Bob runs bidders: hosts with VMs to provide, each its own DID, an agent of Bob's account
- Alice has vouched for Bob and Bob for Alice (
sh.tangled.graph.vouch); Alice has denounced Eve (a vouch record withkind: denounce, which no policy counts) - Alice writes her Compute Contract Request For Proposal (CCRFP: the
compute.vmrecord, the VM-specific payload: cpus, mem, disk, cloud-inituser_data, ...) and wraps it in a top-level RFP record (domain: compute,payloada strongRef to the CCRFP). The RFP is the domain-tagged envelope bidders and indexers route on; the CCRFP is the inner VM-specific record - Bob's and Eve's bidders each issue a Compute Contract Bid (CCB:
market.bid). Alice's policy engine (requester-tangled-vouch) sees she vouched for Bob (his bidder's walk reaches him) and denounced Eve: it allows Bob's bid and denies Eve's - Alice issues a Compute Contract Bid Accept (CCBA:
market.accept) against Bob's CCB. Withbids.x402she would first pay per the CCB's terms; no x402 flow is exercised today (accepts.*andreceipts.*are defined, not written) - Bob's bidder checks its capacity and issues a Compute Contract Receipt (CCR:
market.receipt) over the CCRFP, the CCB and the CCBA; it builds to the CCRFP's spec (boots the VM from itsuser_data) and reports the guest's address - Alice reaches the guest, works, and releases it; both sides record the end
The Steps
| step | who writes | where | what the other side verifies |
|---|---|---|---|
| S0 sign in | each party | its OpenBao | - |
| S1 trust | operators, users | their repos | vouches and associations, at every policy run |
| S2 declare (optional) | the owner's kcp | owner repo | - |
| S3 policy, vm, rfp; discovery; submitRfp | requester | requester repo | RFP signature, RFP author = token issuer, bid window, policies |
| S4 bid | bidder | bidder repo | bid author = token issuer, scope policy on each bid |
| S5 accept; submitAccept | requester | requester repo | accept signature, accept author = RFP author, policies again, capacity |
| S6 receipt | bidder | bidder repo | receipt signature, cid binds the accept |
| S7 boot, vm events | bidder (for the guest) | bidder repo | event author = receipt author, both signatures |
| S8 guest events, secrets, Held | both | each its own | event author, kind allowed for that side |
| S9 release, cleanup | both | each its own | delete author = accept author |
S0: sign in
- a party is a MarketIdentity: a repo DID and how the app reaches it (
localRepo,pdsAccount,oauthQr,oauthBrowser,oauthDelegated,oauthSessionProxy): identity.md socialweb-computer run request --name vm1 --atproto-oauth-qr --exec -- idsigns in with a QR code; the session stays in the requester's own OpenBao
S1: trust
- vouches: a person vouches another at
sh.tangled.graph.vouch/<subject DID>in their own repo; both directions are needed for a deal (policy.md) - associations: a bidder is an agent of its operator by the ident.link pair (its DID document's
agent-of, the operator'slink.ident.endorsementandmarket.associationat rkey = the agent DID); trust walks agent -> principal up to 100 levels (identity.md) - the policy modes in code:
tangled-vouch(the default on both sides),only-me,mutuals,open(only when named, never prod), and the work policiesbid-payload,under-4-cpus(policy.md)
S2: declare (optional)
- an Infra or EphemeralInfra kcp object of the owner mirrors to
computer.socialweb.infra/ephemeralInfrain the owner's repo; each of its contracts is a ComputeContract that runs S3 to S9 (infra.md).run requestmakes the ComputeContract directly
S3: policy, vm, rfp
The requester (internal/market/requester/runner.go requestOnce) checks the size, the token paths and the contract deadline (the vm-expires-at label: a deadline in the past sends no RFP), then writes, each with putRecord at a TID:
# the policy record: the workflow the requester runs, so the bidder can run it too
uri: at://aliceoa.bsky.social/computer.socialweb.temp.policy.ghalite/3n2de4u2n2c2i
$type: computer.socialweb.temp.policy.ghalite
name: requester-tangled-vouch
perspective: requester
requester: did:plc:lpfuqerea3deuoyrn7ojser4
workflow: "<the bundled workflow, 2448 chars>"
---
# the VM asked for (unsigned; reused by every RFP round of the contract)
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t
$type: com.publicdomainrelay.temp.compute.vm
kind: vm
role: stg-gateway
cpus: 4
mem: 8G
disk: 50G
expiresAt: "2026-11-15T11:00:45.000Z"
user_data: "<cloud-init, 5399 bytes: cloudinit.BuildUserData, with the iroh module>"
---
# the RFP (signed)
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a
$type: com.publicdomainrelay.temp.market.rfp
domain: compute
payload: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t, cid: bafyreiejybdf2t77...}
policies:
- {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/computer.socialweb.temp.policy.ghalite/3n2de4u2n2c2i, cid: bafyreick65zxk47w...}
submitBid: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:10:46.139Z"
submitBid here is the requester's did:key ingress (it has no public host: identity.md).
Then discovery (market.md): every repo with a market.offering that the relays list, plus the DIDs its operators vouch for and the agents they endorse; candidates without a fresh heartbeat (300 s) or lacking a capability (maxCpus, nestedVirt, images) are dropped. Never a pinned list.
The requester sends market.submitRfp {rfpUri, rfpCid} to each candidate's first endpoint (iroh, webrtc, https), service auth aud <bidder DID>#pdr_temp_market, lxm the NSID.
The bidder (internal/market/bidder/submit.go SubmitRFP) checks the token issuer is the RFP's author and the bid window (10 min from the RFP's TID), answers 200 {name, phase: Deciding} or declined {kind: capacity|unservable, reason}, or 409 RFPClosed. The RFP also reaches it on the relay and Jetstream streams; one sink drops duplicates.
S4: bid
The bidder (bids.go decideBid): the window, the RFP's signature, the requester's DID resolves, the payload, guest tools and net, the scope policy, then the full policy (its own workflow and every attached one: all must allow). Then three records at the bid's deterministic rkey (BidRKey: one bid per RFP):
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bids.free/bid-596cc856db4e8aaf1080-payload
$type: com.publicdomainrelay.temp.market.bids.free
reason: free
cost: 0
# Can also be x402 (not exercised today):
# $type: com.publicdomainrelay.temp.market.bids.x402
# cost: 100000
# currency: USDC
# frequency: hourly
# prepay: true
# url: https://compute-contract.bob.example/receipt
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080
$type: com.publicdomainrelay.temp.market.bid
rfp: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
payload: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bids.free/bid-596cc856db4e8aaf1080-payload, cid: bafyreidtjdg5zrwd...}
config: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.config.wif.simple/bid-596cc856db4e8aaf1080-config, cid: bafyreig7dqqmi2ky...}
createdAt: "2026-11-15T06:10:53Z"
The config is the VM's workload identity issuer and subject format (guest-events.md). The bidder sends market.submitBid to the RFP's submitBid.
The requester takes bids from submitBid, the streams, and one getRecord per bidder at BidRKey a few seconds after submitRfp. Each is read from the repo of the bid URI's authority (for a submitBid, the service-auth issuer): of a submitBid only uri and cid are used, the bid is read by them and its bytes must hash to cid; the submitRfp answer is never read for a bid. Before a bid is queued its signature must verify with a key of the bidder's DID document or a key its badgeBlueKeys record binds, read with com.atproto.sync.getRecord and its signed commit checked (identity.md); a refused bid is answered 403. The winner's config must be in the same repo. Whether the bidder was one the RFP went to is not checked. Its window (bidWindowSeconds, 30 s) ends at the first free bid its scope policy allows; else it takes the lowest-cost allowed bid after the window. It runs the full policy on the winner (a deny fails the contract: policy_rejected).
S5: accept
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.market.accept/ro7pddf4ecfze
$type: com.publicdomainrelay.temp.market.accept
rfp: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
bid: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080, cid: bafyreidpljip3s4e...}
submitEvent: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:11:00.665Z"
- rkey
SessionRKey("accept", repo, contract, rfp, bid): a restarted requester finds and reuses it - no payload record today: with x402 the accept would wrap the proof of payment
market.submitAccept {acceptUri, acceptCid}(accept.gosubmitAcceptAndWait): re-sent every 0.5 s doubling to 2 s until the receipt is found orreceiptTimeoutSeconds(5 min) pass- the bidder (
SubmitAccept,vmsize.go) checks capacity at once: a guest counts its vCPUs and its memory plus the VM overhead; an accept reserves its size for 10 min (per RFP; cut to 1 min once placed and dropped when its ComputeVM exists); a full host answers 409CapacityExceededbefore any receipt, else 202{id} - then, asynchronously (
adapters.goacceptContract): the accept's signature, the scope policy, the bid is its own for that RFP, the accept's author is the RFP's, not expired, the RFP's signature, the full policies again, capacity again
S6: receipt
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.receipt/receipt-fa04c66e2d8effc84a2f6a869217fa11
$type: com.publicdomainrelay.temp.market.receipt
rfp: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
bid: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080, cid: bafyreidpljip3s4e...}
accept: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.accept/ro7pddf4ecfze, cid: bafyreickrv6epucq...}
payload: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t, cid: bafyreiejybdf2t77...}
cid: bafyreihoa6m57iajl63umctjn4mke2l4ezbzmbxhclfj5ghrx2uaxklrla
submitEvent: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:11:07.641Z"
- rkey
receipt-+ 32 hex of sha256(accept uri LF accept cid) (market.ReceiptRKey): the requester finds it with one getRecord in the bidder's repo cidis the attestation CID of the accept record in the requester's repo; the requester checks the receipt's signature and that binding (market.VerifyReceipt); a bad one fails the contractreceipt_invalid- no atirc token and no association exist before a verified receipt
S7: boot and vm events
- placement (
provision.goplaceAccepted): a ComputeVM owned by the Bid, then a FirecrackerVM; the VM boots the requester'suser_datawith the bidder's additions (the accept bundle, the network, workload login,guest-onnetwork.service, the guest agent andsetup-guest-binaries.service:internal/guestseed) - the fence is loaded before the tap exists: the guest reaches the internet; TCP to the bidder's host only to the guest control plane at
http://192.0.2.1:<port>(itsspec.hostPorts), never TCP to the LAN; DNS; UDP to the LAN for WebRTC by default (../SYSTEM.md) - downloads: the guest image is the bidder's, pinned by sha256 in
internal/versions/versions.json(guest-images/<target>/<image.json sha256>in the bucket); a requester image (compute.vm.image {url, sha256}) is fetched and verified by the bidder; guest binaries (opentunnel, wootty, atirc, the guest agent) come fromGET /v1/downloads/<sha256>/<name>of the guest control plane and are checked against that sha256. One exception in code: when the image's baked dumbpipe is not the pinned version, the iroh module fetches dumbpipe from GitHub with no sha256 check (internal/atproto/cloudinit/modules.go,setup-iroh.sh) - the guest logs in with its ssh host key (
sshsig), which binds the host key to the ComputeVM;iroh-listener.shrunsdumbpipe listen-tcp 127.0.0.1:22andsend-onnetwork.shPOSTsvm.onNetworkwith the iroh ticket toPOST /v1/events - the bidder writes each as a payload +
market.eventin its repo atEventRKeys(<kind>:<receipt>)and sendsmarket.submitEventto the receipt'ssubmitEvent:
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.hostKeys/hostkeys-payload-2aac09c4d09c6fa506757931c42eb7f1
$type: com.publicdomainrelay.temp.compute.events.vm.hostKeys
keys: [{type: ssh-ed25519, publicKey: AAAAC3NzaC1lZDI1NTE5AAAAIAnyKwEO5wzWGBi44fIk0IINLHqK21fd1/Q0CVUssM1u, fingerprint: "SHA256:HLs4eIe9xpZuDqOzbJ4V0PMGYUAT0MykBqMj5YdG4UQ"}]
observedAt: "2026-11-15T06:11:17Z"
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.onNetwork/onnetwork-payload-ffcde96d9e9d32d1fc7a38f6a2c46ad5
$type: com.publicdomainrelay.temp.compute.events.vm.onNetwork
address: iroh://endpointaakwnx5yuadc7qofuw3rdurziaeaghixq...
createdAt: "2026-11-15T06:11:19Z"
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.event/onnetwork-event-63e463b75b052b3a570a6956e00d9a4d
$type: com.publicdomainrelay.temp.market.event
payload: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.onNetwork/onnetwork-payload-ffcde96d9e9d32d1fc7a38f6a2c46ad5, cid: bafyreicronh3k2gu...}
receipt: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.receipt/receipt-fa04c66e2d8effc84a2f6a869217fa11, cid: bafyreihpm5lvqqro...}
createdAt: "2026-11-15T06:11:19Z"
S8: guest events, secrets, Held
- guest -> requester: the guest POSTs
{acceptUri, acceptCid, record}to its bidder (POST /v1/events, bearer the workload token); the bidder signs and publishes it (publicKey,signalWebRTC,secretsRequested,secretsApplied,requesterDid,r2Released,memoryPressure,oomKill,image) - requester -> guest: the requester writes the event in its repo and sends submitEvent to the bidder, which checks the author is the accept's and queues it for the guest's
compute.guest.subscribeEventsWebSocket (publicKey,signalWebRTC,secrets,agentStart,secretsUpdated,r2Start,r2Release) - secrets: the guest fetches the requester's bundle with
getSecretsand its workload identity token, over iroh, then WebRTC (the guest agent'srequester.sock), then https; sealed into a record only when the requester has no inbound endpoint (comms mode Firehose), enables it and the guest asks (guest-events.md) - Held (
runGuestAndHold): the iroh address and the host keys, plus the image marker for an image contract and the secrets fetch when the contract has secrets and the requester an inbound endpoint - transports, three and no other: iroh (every guest; ssh over
dumbpipe,run request ssh), opentunnel https (per tag), webrtc (per tag; sealed signaling through the bidder) (../SYSTEM.md). The ssh gateway (ssh <handle>@socialweb.computer) runs the same flow as the user and hops over iroh (../SYSTEM.md) - atirc: for
spec.agentthe requester mints a token leased to the receipt and the bidder'svm.terminatedafter the receipt is verified (outside.md) - a guest requester (R2) in the VM is associated here: identity.md
S9: release and cleanup
- a release request (
spec.releaseRequestedAt): the guest requester's contracts first (guest.r2Release, wait forguest.r2Released), then leased atirc tokens are revoked while the lease is alive - the requester writes
compute.events.vm.delete {reason: released}+market.eventand sends submitEvent, retried until the bidder'svm.terminatedappears or the release deadline - the bidder checks the delete's author is the accept's and the receipt is its own, deletes the ComputeVM, and writes
vm.terminated:
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.terminated/termination-payload-2da9e2aef573b37793d5c43f443186a1
$type: com.publicdomainrelay.temp.compute.events.vm.terminated
reason: deleted_on_request
observedAt: "2026-11-15T06:18:58Z"
- the requester reads it at
EventRKeys(TerminationKey(receipt))(up to 2 min) and is Released - cleanup: the requester deletes the records it wrote for the contract (the rbac grant, the association and endorsement, its delete records, the accept, the RFP, the
compute.vm, the policy record, its ContractEvents); a guest requester's DIDs are tombstoned (by the guest, else by the requester's rotation key). The bidder keeps its bid, receipt and events - reasons a VM ends without a release:
guest_poweroff,vmm_exited,oom,host_reboot,identity_mismatch,image_refused,expired(past its association'sexpiresAt),association_ended(market.md)
The records of this contract are still in alice's repo, and its vm.terminated has no request: its requester did not run step 5. Why is not visible in the records.
When It Does Not Go That Way
- the requester keeps a declined accept (a bidder that already acted on it may still need it; the bidder gives up on its own:
bidder_accept_abandoned) - a failure before a receipt deletes the RFP, the
compute.vmand the policy record, and keeps the accept - sources:
runner.goRun,replaceDeclined,reRFPAfterRefusals,waitForCapacity,unservableBy;accept.goacceptDeclined;image.go
A Real Run
The requester's contract lines of one request on a local market (run request --network):
06:02:32 Requesting requested step preparing
06:02:32 Requesting rfp_submitted step creatingRfp
06:02:32 Requesting rfp_submitted the RFP is submitted; collecting bids
06:02:32 Requesting rfp_submitted ... requester_no_bidders: no bidder with a market endpoint among 1 candidates
06:03:02 Requesting rfp_submitted waiting for a default-size slot: round 1, a new RFP in 30s
06:03:32 Requesting rfp_submitted step creatingRfp
06:03:35 Requesting winner_selected the winner is selected; accepting
06:03:35 Requesting accepted the accept is submitted; waiting for the receipt
06:03:39 Requesting receipt the receipt is verified; waiting for the guest
06:03:51 Requesting receipt the guest reported hostKeys
06:03:54 Requesting network the guest reported onNetwork
06:03:54 Held network held: the guest is on the network
06:03:55 Releasing network the destroy is delivered; waiting for the bidder's vm.terminated
06:04:00 Released released the bidder ended the contract: deleted_on_request
The first round found the network's bidder before its offering named an endpoint; the requester waited for capacity and the second round got the VM.
See Also
- README.md (the index and the sequence), market.md, guest-events.md, identity.md, policy.md, release.md, glossary.md
- the acceptance runbooks:
docs/acceptance/