socialweb.computer

Request and provide VMs on an atproto compute market.

market: the RFP flow

Parties And Repos

partyrepo it writeswhat it writes there
requesterits own (the MarketIdentity DID)compute.vm, policy record, market.rfp, market.accept, market.event + its payloads (compute.events.vm.delete, requester compute.events.guest.*), ingress.webRTC listen + offer, contract-scoped market.association
bidderits ownmarket.offering, market.heartbeat, market.bid + market.bids.free + compute.config.wif.simple, market.receipt, market.event + its payloads (compute.events.vm.*, guest-originated compute.events.guest.*), ingress.webRTC answer
guestnone. the guest holds no repo keyPOSTs its events to the bidder, which signs and writes them (guest-events.md)

Records Of One Contract

steprecordreporkeystrongRefs it holds
S3compute.vmrequesterTID (putSetupRecord: putRecord at a TID; unsigned; one per contract, reused by every RFP round)none. user_data = cloud-init from cloudinit.BuildUserData
S3policy record computer.socialweb.temp.policy.ghaliterequesterTID (putRecord; unsigned)none (policy.md)
S3market.rfprequesterTID (putRFP: BuildRFP, SignRecord, putRecord)payload -> compute.vm, policies[] -> policy record, ingress[] -> ingress.webRTC listen
S4compute.config.wif.simplebidder<bid rkey>-confignone
S4market.bids.freebidder<bid rkey>-payloadnone
S4market.bidbiddermarket.BidRKeyrfp -> rfp, config -> wif config, payload -> bids.free
S5market.acceptrequesterSessionRKey("accept", ...)rfp, bid, ingress[]. no payload (the code passes none)
S6market.receiptbiddermarket.ReceiptRKeyrfp, bid, accept, payload -> the RFP's compute.vm; cid = attestation CID over the accept
S7-S9market.event + payloadsenderper kind (below)receipt -> receipt, payload -> the compute.events.* record

Rkeys

Stable rkeys make every write idempotent and every read one getRecord. A restarted runner reads the record at its rkey before it writes (existingSignedRecord, participant.EnsureRecordAt).

recordrkeyfunctionfile
market.bidbid- + first 20 hex of sha256(bidderDID NUL rfpURI # rfpCID)market.BidRKeyinternal/atproto/market/records.go
market.bids.free, compute.config.wif.simple<bid rkey>-payload, <bid rkey>-configwriteBidRecordinternal/market/bidder/bids.go
market.accept13 chars of sha256("accept", repoDID, contract, rfpURI, rfpCID, bidURI, bidCID) over 234567a-zacceptRKeyFor -> market.SessionRKeyinternal/market/requester/secrets.go
market.receiptreceipt- + first 32 hex of sha256(acceptURI LF acceptCID)market.ReceiptRKeyinternal/atproto/market/attest.go
compute.events.vm.deleteSessionRKey("delete", receiptURI)market.ReleasePayloadRKeyinternal/atproto/market/records.go
requester market.event of vm.deleteSessionRKey("event", receiptURI)destroyEnvelopeinternal/market/requester/runner.go
bidder event payload + market.event<prefix>-payload-<32 hex>, <prefix>-event-<32 hex> of an idempotency keymarket.EventRKeysinternal/atproto/market/records.go
vm.terminated payload + eventkey terminated:<receiptURI>, prefix terminationmarket.TerminationKeyinternal/computevm/termination.go
requester ContractEvent payload + eventSessionRKey("contract-event", uid), SessionRKey("contract-event-envelope", uid)publishContractEventinternal/market/requester/contractevents.go
market.offering, market.heartbeat, market.relaysselfOfferingRKey, HeartbeatRKey, RelaysRKeyinternal/atproto/market/nsid.go
requester ingress.webRTC listenwebrtcingressDescriptorinternal/market/requester/requester.go
contract-scoped market.association (and its link.ident.endorsement)the agent DID (the guest requester's); one grant per agent, refused when it is bound to another contractassociate (rkey := subject)internal/market/requester/association.go
market.associationRequestthe principal DID (the requester's)ApplyAssociationRequestRecordinternal/app/compose/records.go
com.fedproxy.rbacnode.<accept rkey>market.RBACRKeyinternal/atproto/market/records.go

strongRef Graph

diagram

payload

policies

rfp

config

payload

rfp

bid

rfp

bid

accept

payload

receipt

payload

compute.vm (requester)

policy record (requester)

market.rfp (requester)

compute.config.wif.simple (bidder)

market.bids.free (bidder)

market.bid (bidder)

market.accept (requester)

market.receipt (bidder)

market.event (sender)

compute.events.* (sender)

Signatures

Discovery

recordwriterreaderrule
market.offering at selfbidder (internal/market/bidder/offering.go)requester (market.ReadOffering)appliesTo must hold compute.vm (market.OfferingApplies); endpoints[] = where the market XRPC goes ({kind, address}: iroh a short ticket, node id and relay, no IPs; webrtc base64url JSON {did, listen}; https an origin); maxCpus (the host's cores), maxMem (its RAM), nestedVirt, images; withdrawnAt + empty appliesTo = withdrawn (a guest image that does not verify withdraws it)
market.heartbeat at selfbidder, every spec.heartbeatIntervalSeconds (default 60 s)requester (market.HeartbeatCache), internal/marketpresencefresh while createdAt is at most HeartbeatTTL (300 s) old and not more than 60 s ahead; offering names the offering (a legacy non-self rkey is read through it); version {version, commit, sha256} of the running binary
market.relays at selfno Go writer hererequester (market.RelayURLsOf)extra relays to ask listReposByCollection

A real offering and heartbeat (one of bobvmbuilder.bsky.social's prod bidders, addresses trimmed):

{"uri": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.offering/self",
 "value": {"$type": "com.publicdomainrelay.temp.market.offering",
   "appliesTo": ["com.publicdomainrelay.temp.compute.vm"],
   "endpoints": [{"kind": "iroh", "address": "endpointadsmudoo..."},
                 {"kind": "webrtc", "address": "eyJkaWQiOiJkaWQ6cGxjOjJsMndkcnk3N2M3anR1Y2JzbHN0YWdraiIsImxpc3RlbiI6Im1hcmtldCJ9"}],
   "maxCpus": 16, "maxMem": "47253M", "nestedVirt": true, "images": true,
   "createdAt": "2026-10-31T06:08:35Z", "refreshedAt": "2026-11-18T16:04:01Z"}}
{"uri": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.heartbeat/self",
 "value": {"$type": "com.publicdomainrelay.temp.market.heartbeat",
   "offering": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.offering/3myowdvhzjy22",
   "version": {"version": "v0.0.0-rc99.0.20261119030632-688c2105f879", "commit": "688c2105f879...", "sha256": "d4933943..."},
   "createdAt": "2026-11-19T08:12:43Z"}}

The webrtc address decodes to {"did":"did:plc:2l2wdry77c7jtucbslstagkj","listen":"market"}. This heartbeat's offering still names a legacy TID rkey; the reader falls back to it only when self is missing.

Delivery: XRPC Callbacks And Streams

Every record also reaches the other side two ways. The XRPC call is the fast path; the stream is the fallback and the only path with no inbound endpoint.

Comms modes

spec.comms.moderequester ingress (submitBid, submitEvent)streams
XRPCyesnone
Firehosenonerelay + Jetstream
Both (requester default)yesrelay + Jetstream

XRPC procedures

NSIDserved bycallerbodyanswerfile
market.submitRfpbidder ingressrequester{rfpUri, rfpCid, ingress?}200 {ok, name, phase: Deciding, ingress?, declined?: {kind: capacity|unservable, reason}}; 409 RFPClosed after the bid window (by the RFP's TID rkey); 400, 401/403, 500, 503 Suspended/Unavailableinternal/services/bidder/routes.go handleSubmitRFP
market.submitBidrequester ingressbidder{uri, cid, record} of the market.bid200 {ok}; 403 when the record is not the issuer's or its signature is refused; 400 when the bid read from the issuer's repo does not hash to cid; 503 while it or its key binding cannot be readinternal/services/requester/routes.go, Requester.SubmitBid in internal/market/requester/callbacks.go
market.submitAcceptbidder ingressrequester{acceptUri, acceptCid, ingress?} (ingress is parsed, not used)202 {ok, id, acceptUri, acceptCid} (id = the provision StateSync accept-<16 hex>); 409 CapacityExceeded before any receipt; the receipt follows as a recordhandleSubmitAccept
market.submitEventboth ingressesthe contract party that wrote the event{uri, cid, record} of the market.event200 {ok}; 403 Forbidden when the sender is not the accept author (to a bidder) or the receipt author (to a requester)handleSubmitEvent, Requester.SubmitEvent

Bid Window And Selection

Policies Attached

Sequence: RFP To Held

diagram
guest VMbidder repoBidderrelay / Jetstreamrequester repoRequesterguest VMbidder repoBidderrelay / Jetstreamrequester repoRequesterS3 compute.vm (TID), policy record, market.rfp (TID, signed)1getRecord offering + heartbeat at self of each candidate2submitRfp rfpUri rfpCid3200 name phase Deciding4commit market.rfp5market.rfp (fallback, deduplicated)6getRecord rfp, compute.vm, policies7bidder policy + every attached policy8S4 wif config, bids.free, market.bid at BidRKey9submitBid10commit market.bid11market.bid (fallback)12getRecord bid at BidRKey (catch-up)13window, firstFree, attached policy on winner14S5 market.accept at SessionRKey accept15submitAccept acceptUri acceptCid16202 provisioning intent17getRecord accept, rfp, verify signatures, policies again18S6 market.receipt at ReceiptRKey, cid binds the accept19commit market.receipt20getRecord receipt at ReceiptRKey21VerifyReceipt, mint atirc token if spec.agent22ComputeVM, boot user_data23POST /v1/events vm.onNetwork iroh ticket24S7 vm.onNetwork, vm.hostKeys + market.event25submitEvent26VMAddress + HostKeys set, secrets fetched, ComputeContract Held27

Release And Termination

  1. a release request stamps spec.releaseRequestedAt; the runner enters releaseContract (runner.go)
  2. guest requester first: releaseGuestRequester publishes guest.r2Release and waits for guest.r2Released (only with spec.association.fromGuest)
  3. atirc tokens: revokeBeforeDestroy (internal/market/requester/atirc.go) revokes a leased token while its lease is alive
  4. destroyEnvelope: compute.events.vm.delete at ReleasePayloadRKey(receipt) + market.event at SessionRKey("event", receipt), both signed
  5. submitEvent to the bidder; retried 5 s doubling to 5 min (DefaultReleaseRetryFirst, DefaultReleaseRetryMax) until the release deadline (the contract's creation plus ttlSecondsAfterFinished, default 8 days; DefaultReleaseBound 24 h when that is 0), checking for the bidder's vm.terminated after each wait. no endpoint: the stream carries it
  6. bidder: applyRelease -> verifyInboundDelete (event author = accept author, receipt is its own, both signatures), markReleaseRequested records the release request on the Bid and ComputeVM, and the ComputeVM is deleted (internal/market/bidder/adapters.go, internal/market/bidder/bids.go finishRelease)
  7. bidder: termination StateSync (internal/computevm/termination.go, adapter atproto.market.event) writes compute.events.vm.terminated {reason: deleted_on_request, request?} + market.event at EventRKeys(TerminationKey(receipt))
  8. requester: after a 2xx it reads the bidder's vm.terminated (awaitTermination, FindTermination) for up to DefaultReleaseTerminationWait (2 min), then Released either way
  9. requester deletes the records it wrote for this contract (deleteContractRecords in internal/market/requester/association.go): the com.fedproxy.rbac grant, the contract association and its endorsement (then, for a guest requester, the tombstone fallback: identity.md), its vm.delete and release market.event, the accept (only once a receipt exists), the RFP, the compute.vm, the policy record, and every outbound ContractEvent's payload and envelope (requester_contract_records_deleted)
diagram
guest VMbidder repoBidderatircrequester repoRequesterguest VMbidder repoBidderatircrequester repoRequesterspec.releaseRequestedAt, phase Releasing1submitEvent guest.r2Release (fromGuest only)2submitEvent guest.r2Released3chat.atirc.revoke leased tokens (lease alive)4S9 vm.delete at ReleasePayloadRKey + market.event5submitEvent vm.delete6verifyInboundDelete7stop, delete ComputeVM8vm.terminated deleted_on_request + market.event at TerminationKey rkeys9submitEvent vm.terminated10getRecord vm.terminated (FindTermination), up to 2 min11delete own contract records: rbac, association, vm.delete + event, accept, rfp, compute.vm, policy, ContractEvents12ComputeContract Released13

A real vm.terminated (bidder did:plc:2l2wdry77c7jtucbslstagkj, the release of the contract in flow.md):

{"uri": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.terminated/termination-payload-2da9e2aef573b37793d5c43f443186a1",
 "value": {"$type": "com.publicdomainrelay.temp.compute.events.vm.terminated", "reason": "deleted_on_request",
   "observedAt": "2026-11-15T06:18:58Z", "createdAt": "2026-11-15T06:18:58Z", "signatures": ["..."]}}

Revocation Ordering

Records Policy

See Also