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).
the bidder's event idempotency keys (internal/market/bidder/syncs.go): onNetwork:<receipt>, onNetwork:<tag>:<receipt>, hostKeys:<receipt>, terminated:<receipt>, guest:<nsid>:<tag>:<kind>:<n>:<receipt> (n = 0, 1, ... per VM, nsid, tag and kind: a guest's n-th event of that stream), else <nsid>:<receipt>
so a requester reads a guest's events send/recv style, one getRecord each: n = 0, 1, ... until one is not found (never listRecords)
so anyone can find the bidder's vm.terminated of a receipt with one getRecord: market.EventRKeys(market.TerminationKey(receiptURI)) (FindTermination in internal/market/requester/market.go; the atirc lease in internal/market/requester/atirc.gocontractLease)
the requester finds a receipt with one getRecord at ReceiptRKey(acceptURI, acceptCID) (FindReceipt) and a missed bid at BidRKey (catchUpBids in internal/market/requester/bidcatchup.go)
inline signature: market.SignInline hashes the record + metadata {$type, key, issuer} + the repo DID into an attestation CID and signs its bytes (internal/atproto/market/attest.go)
receipt binding: CreateReceiptRecordAt sets receipt.cid = attestation CID of the accept record, the receipt metadata and the accept repo DID. the requester checks it with market.VerifyReceipt; a bad one fails the contract ReceiptInvalid (acceptReceipt in internal/market/requester/runner.go)
the bidder checks the RFP signature before it provisions (acceptContract), and the event + payload signatures of every requester event (applyGuestEvent)
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)
fresh 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
candidate bidders (candidateSources in internal/market/requester/discovery.go, HTTPMarket.discover in market.go), in order:
the requester's own spec.bidderDIDs (named: no heartbeat needed)
every DID com.atproto.sync.listReposByCollection?collection=market.offering lists on each relay: the network relay, else spec.comms.relayUrls, else relay1.us-east.bsky.network and our relay; plus market.relays/self of self and spec.operatorDID
the DIDs its operators vouch for (operators = self, spec.operatorDID, the roots of its identlink walk; at most 64)
the agents those operators endorse (link.ident.endorsement) whose walk reaches the operator (one level down)
discovery is not a trust filter: the relay lists every bidder; the policy decides who is served (policy.md)
a contract's spec.bidderDids narrows that set (it adds no DID); spec.denyBidderDids and the bidders that declined this contract are removed (Discovery.Without)
unnamed candidates without a fresh heartbeat are dropped (dropNoHeartbeat); then Bidder.Lacks: maxCpus below the VM's cpus, no nestedVirt, no images for an image contract (maxMem is not read)
every candidate dropped for good (a capability or a size): the contract fails at once; none at all with bidderDids set: no bids
discovery results are cached 20 s (only when a bidder was found)
a bidder's endpoint: the first of iroh (only with dumbpipe on PATH), webrtc, https in its offering (DefaultEndpointKinds; SOCIALWEB_REQUESTER_BIDDER_ENDPOINTS replaces the order); service auth aud <bidder DID>#pdr_temp_market
A real offering and heartbeat (one of bobvmbuilder.bsky.social's prod bidders, addresses trimmed):
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.
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.
payload records (bids.free, compute.events.*, ...) are never stream input. the reader fetches them through the strongRef
one sink per role (internal/eventstream/market.go) drops a uri|cid seen in the last 15 s (market_event_duplicate_dropped)
addressee index (internal/atproto/market/addressee.go, internal/eventstream/addressees.go): the requester keeps a bid whose rfp is one of its RFPs, a receipt whose accept is one of its accepts, an event whose receipt is one of its receipts. the bidder keeps every RFP, an accept whose bid is in its repo, an event whose receipt is in its repo. the rest: market_foreign_dropped
the bidder's requester streams (internal/app/compose/requesterstreams.go): only while it has live ComputeVMs, filtered to those requester DIDs, spec.resume: Recent
200 {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 read
internal/services/requester/routes.go, Requester.SubmitBid in internal/market/requester/callbacks.go
{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 record
200 {ok}; 403 Forbidden when the sender is not the accept author (to a bidder) or the receipt author (to a requester)
handleSubmitEvent, Requester.SubmitEvent
auth: a service-auth JWT with lxm = the NSID; the token issuer is the caller (AuthorizeCallback in internal/market/requester/callbacks.go, participant.Authorizer)
market.AuthorizeRecord(issuer, uri): the submitted record must be in the issuer's repo
the requester takes no bid from an answer or a body: submitRfp's answer is never read for one, and of a submitBid it
takes only uri and cid, reads the bid from the issuer's repo and uses those bytes (record is ignored); the
winning bid's config must be in the same repo
a record read by strongRef (or any read with a known content id) hashes the record value as dag-cbor (CIDv1, sha2-256,
internal/atproto/recordcid) and fails hard when it is not the id asked for; a read by URI alone has nothing to check
the bidder answers submitBid too (it only parses the bid); the bidder routes exist only with inbound XRPC (inboundXRPC)
the requester's submitEvent takes only event kinds a requester consumes (isGuestEventNSID in internal/market/requester/events.go)
submitBid in the RFP, submitEvent in the accept and receipt: a DID service ref (did#serviceId, default ids pdr_temp_market, pdr_temp_compute_event) or an HTTP URL
calls to a bidder go to its offering endpoints[] with service auth aud <bidder DID>#pdr_temp_market (hostname-free; the bidder also takes #pdr_temp_compute_event)
a webrtc endpoint's address is base64url JSON {did, listen}: the bidder's computer.socialweb.ingress.listen/<listen> holds
{key (age), fingerprint (DTLS)}; an offerer writes computer.socialweb.ingress.offer/<bidder DID>.<tid> (age-sealed {sdp, replyTo})
in its own repo, the bidder (offers reach it on its Jetstream and relay streams, collection filter) answers once at
computer.socialweb.ingress.answer/<offerer DID>.<tid> (sealed {sdp}, deleted after 5 min) and serves HTTP/1.1 on each
datachannel (keep-alive) to its market XRPC; offers older than 2 min are ignored
the Go requester (run request, pkg/embedded) takes a bidder's first endpoint in the order iroh (only with a dumbpipe
on PATH), webrtc, https; SOCIALWEB_REQUESTER_BIDDER_ENDPOINTS (comma list, passed through devsup) replaces the order.
Over webrtc it keeps one PeerConnection per bidder: a createRecord of the offer {ciphertext, subhandle: requester, to: <listen>}, getRecord of the answer every 1 s for up to 45 s, the answer's a=fingerprint checked against the listen
record, the offer deleted once answered (needs the optional scope
repo:computer.socialweb.ingress.offer?action=create&action=delete), then one datachannel labelled market per HTTP/1.1
connection; a PeerConnection with no open datachannel for 5 min is closed (the next dial signals again)
ingress[] on the records and calls: ingress.webRTC listen/offer/answer records for a party whose HTTP endpoint is not reachable (lexicons-market.md)
an OAuth requester writes its ingress.webRTC listen and offer records (createRecord only) with the optional scope
repo:com.publicdomainrelay.temp.ingress.webRTC?action=create (RequesterOptionalScopes); a session granted without it
writes neither (requester_webrtc_ingress_skipped), posts the RFP with no ingress and is reached over its HTTP callbacks,
and its MarketIdentity stays Ready with pendingAction {kind: signInAgain, reason: ScopeUpgrade} until it signs in again
an OAuth bidder writes its ingress.webRTC answer with the same optional scope (BidderOAuthScope); a session granted
without it answers no offer (bidder_webrtc_answer_skipped), so the requester reaches it over HTTP, and its
MarketIdentity stays Ready with the same ScopeUpgrade prompt
bidder side window: market.RFPBidWindow = 10 min from the RFP createdAt, else from its TID rkey (internal/atproto/market/rfpwindow.go). the lexicon has no expiry
a closed RFP: submitRfp answers 409 RFPClosed, the stream sink drops it (market_rfp_closed_dropped), a Deciding Bid fails BidWindowOver (bidder_rfp_closed)
one bid per RFP: the Bid object is named market.BidRKey; after its TTL (24 h, BidTTLSeconds) the bidder's own market.bid at that rkey is the fact (bidder_rfp_already_bid, enqueueBid in internal/market/bidder/submit.go)
requester side window: RequesterSpec.bidWindowSeconds (default 30 s); the first free bid the scope policy allows ends it, else the lowest-cost allowed bid after the window (collectBids, bestBid in internal/market/requester/runner.go)
the requester also reads each discovered bidder's bid at BidRKey once, min(5 s, window/2) after submitRfp (catchUpBids, at most 32 DIDs)
every bid it considers was read from the bidder's own repo (submitBid by uri and cid, the streams by the op's cid, the catch-up at BidRKey) and signed by a key of the bidder's DID document or one its verified badgeBlueKeys record binds (identity.md); the submitRfp answer carries no bid; whether the RFP went to that bidder is not checked
status.chosen.reason: firstFree or policy (the enum also has bestWithinWindow and resumed; no code path leaves them written); status.bids keeps at most 20 (MaxRecordBids)
no bids: outcome no_bids (then the capacity wait below); all denied: bids_denied; winner denied by the full policy: policy_rejected (no fallback to the next bid)
waits (internal/market/requester/requester.go): receipt DefaultReceiptTimeout 5 min (submitAccept re-sent every 0.5 s doubling to 2 s until then, accept.go), iroh address DefaultVMReadyTimeout 120 s (an image contract: + RequestedFetchTimeout 30 min), host keys DefaultHostKeysTimeout 120 s, guest.image 120 s after on network (image contracts), getSecrets fetch 120 s after waitGuest returns (address, host keys, image marker)
Held needs the iroh address and the host keys, plus the image marker for an image contract and the getSecrets fetch when spec.secretsRef is set and the requester has an inbound endpoint (comms mode XRPC or Both) (waitGuest, runGuestAndHold in runner.go); a sandbox (compute.vm.kind: deno) needs its vm.sandbox result instead
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
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.gofinishRelease)
requester: after a 2xx it reads the bidder's vm.terminated (awaitTermination, FindTermination) for up to DefaultReleaseTerminationWait (2 min), then Released either way
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
a guest that stops for any other reason gets vm.terminated with request unset and a reason from market.VMTerminatedReasons (internal/atproto/market/nsid.go): a lost VM's guest_poweroff, vmm_exited, oom, host_reboot, identity_mismatch, image_refused (computevm.GoneReason), or the bidder's own end of it:
expired (the association's expiresAt passed), association_ended (the contract that scoped the requester's association is over: its vm.terminated or vm.delete is present)
deleted_on_request is also written for a direct ComputeVM delete on the bidder (no request)
A real vm.terminated (bidder did:plc:2l2wdry77c7jtucbslstagkj, the release of the contract in flow.md):
a VM the bidder ends at its spec.associationExpiresAt (+ grace) gets vm.terminated{reason: expired}, request unset (computevm.ReleaseReason: a release without a vm.delete, requested at or after that time)
a release whose destroy record or submitEvent keeps failing settles Released once the bidder's vm.terminated for that receipt appears
a bidder also releases a VM whose contract-scoped association expired 10 min ago (ComputeVM spec.associationExpiresAt, identity.md)
no atirc token before a verified receipt (contractLease: "no atirc token is minted before it")
each token is leased to the receipt and the bidder's vm.terminated at-uri, so atirc can kill it when the VM ends even if the requester is gone
on release: guest requester contracts first, then the leased tokens (while the lease is alive), then vm.delete. a 401 saying the lease is not alive counts as revoked
the rest of the revokes run in the background from a release marker in the bundle secret, capped at 24 h (guest-events.md)
user records are never deleted. no sweep, retention or GC of repo records
the requester deletes only the records it wrote for that contract (release step 9), never a record of another contract; the bidder keeps its bids, receipts and events (it deletes only an outbox event it retracts and its webrtc answers)
one getRecord at a deterministic rkey; listRecords only as a legacy fallback