# market: the RFP flow - how a requester requests a guest from a bidder over atproto records: rfp, bid, accept, receipt, event - index of this tree: [README.md](README.md) (steps S0 to S9); one row per lexicon: [lexicons-market.md](lexicons-market.md); the events under a receipt: [guest-events.md](guest-events.md) - NSID prefix of every record here: `com.publicdomainrelay.temp.`; names below drop it (`market.rfp` = `com.publicdomainrelay.temp.market.rfp`) - constants: `internal/atproto/market/nsid.go`; record builders: `internal/atproto/market/records.go`, `internal/atproto/market/attest.go` - requester side: `internal/market/requester` (component `internal/services/requester`); bidder side: `internal/market/bidder` (component `internal/services/bidder`) - applications talk ONLY over these records and XRPC calls. a shared kcp is never a data channel ([../KCP.md](../KCP.md)) ## Parties And Repos | party | repo it writes | what it writes there | |---|---|---| | requester | its 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` | | bidder | its own | `market.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 | | guest | none. the guest holds no repo key | POSTs its events to the bidder, which signs and writes them ([guest-events.md](guest-events.md)) | - every record lives in the repo of its author. no party writes into another party's repo - a party reads the other side's records by `getRecord` through a strongRef or a stable rkey, never by `listRecords` scans ## Records Of One Contract | step | record | repo | rkey | strongRefs it holds | |---|---|---|---|---| | [S3](README.md#step-s3) | `compute.vm` | requester | TID (`putSetupRecord`: putRecord at a TID; unsigned; one per contract, reused by every RFP round) | none. `user_data` = cloud-init from `cloudinit.BuildUserData` | | [S3](README.md#step-s3) | policy record `computer.socialweb.temp.policy.ghalite` | requester | TID (putRecord; unsigned) | none ([policy.md](policy.md)) | | [S3](README.md#step-s3) | `market.rfp` | requester | TID (`putRFP`: `BuildRFP`, `SignRecord`, putRecord) | `payload` -> `compute.vm`, `policies[]` -> policy record, `ingress[]` -> `ingress.webRTC` listen | | [S4](README.md#step-s4) | `compute.config.wif.simple` | bidder | `-config` | none | | [S4](README.md#step-s4) | `market.bids.free` | bidder | `-payload` | none | | [S4](README.md#step-s4) | `market.bid` | bidder | `market.BidRKey` | `rfp` -> rfp, `config` -> wif config, `payload` -> bids.free | | [S5](README.md#step-s5) | `market.accept` | requester | `SessionRKey("accept", ...)` | `rfp`, `bid`, `ingress[]`. no `payload` (the code passes none) | | [S6](README.md#step-s6) | `market.receipt` | bidder | `market.ReceiptRKey` | `rfp`, `bid`, `accept`, `payload` -> the RFP's `compute.vm`; `cid` = attestation CID over the accept | | [S7](README.md#step-s7)-[S9](README.md#step-s9) | `market.event` + payload | sender | per kind (below) | `receipt` -> receipt, `payload` -> the `compute.events.*` record | - sources: `internal/market/requester/runner.go` (compute.vm, policy, rfp, accept, release), `internal/market/bidder/bids.go` `writeBidRecord`, `internal/market/bidder/adapters.go` `acceptContract`, `internal/market/bidder/submit.go` `createReceipt` - `market.accepts.*` and `market.receipts.*` are defined lexicons that no Go code writes ([lexicons-market.md](lexicons-market.md#marketacceptsfree)) ## 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`). | record | rkey | function | file | |---|---|---|---| | `market.bid` | `bid-` + first 20 hex of sha256(bidderDID NUL rfpURI `#` rfpCID) | `market.BidRKey` | `internal/atproto/market/records.go` | | `market.bids.free`, `compute.config.wif.simple` | `-payload`, `-config` | `writeBidRecord` | `internal/market/bidder/bids.go` | | `market.accept` | 13 chars of sha256("accept", repoDID, contract, rfpURI, rfpCID, bidURI, bidCID) over `234567a-z` | `acceptRKeyFor` -> `market.SessionRKey` | `internal/market/requester/secrets.go` | | `market.receipt` | `receipt-` + first 32 hex of sha256(acceptURI LF acceptCID) | `market.ReceiptRKey` | `internal/atproto/market/attest.go` | | `compute.events.vm.delete` | `SessionRKey("delete", receiptURI)` | `market.ReleasePayloadRKey` | `internal/atproto/market/records.go` | | requester `market.event` of vm.delete | `SessionRKey("event", receiptURI)` | `destroyEnvelope` | `internal/market/requester/runner.go` | | bidder event payload + `market.event` | `-payload-<32 hex>`, `-event-<32 hex>` of an idempotency key | `market.EventRKeys` | `internal/atproto/market/records.go` | | `vm.terminated` payload + event | key `terminated:`, prefix `termination` | `market.TerminationKey` | `internal/computevm/termination.go` | | requester ContractEvent payload + event | `SessionRKey("contract-event", uid)`, `SessionRKey("contract-event-envelope", uid)` | `publishContractEvent` | `internal/market/requester/contractevents.go` | | `market.offering`, `market.heartbeat`, `market.relays` | `self` | `OfferingRKey`, `HeartbeatRKey`, `RelaysRKey` | `internal/atproto/market/nsid.go` | | requester `ingress.webRTC` listen | `webrtc` | `ingressDescriptor` | `internal/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 contract | `associate` (`rkey := subject`) | `internal/market/requester/association.go` | | `market.associationRequest` | the principal DID (the requester's) | `ApplyAssociationRequestRecord` | `internal/app/compose/records.go` | | `com.fedproxy.rbac` | `node.` | `market.RBACRKey` | `internal/atproto/market/records.go` | - the bidder's event idempotency keys (`internal/market/bidder/syncs.go`): `onNetwork:`, `onNetwork::`, `hostKeys:`, `terminated:`, `guest:::::` (n = 0, 1, ... per VM, nsid, tag and kind: a guest's n-th event of that stream), else `:` - 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.go` `contractLease`) - 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`) ## strongRef Graph ```mermaid flowchart LR VM["compute.vm (requester)"] POL["policy record (requester)"] RFP["market.rfp (requester)"] CFG["compute.config.wif.simple (bidder)"] BF["market.bids.free (bidder)"] BID["market.bid (bidder)"] ACC["market.accept (requester)"] REC["market.receipt (bidder)"] EV["market.event (sender)"] PAY["compute.events.* (sender)"] RFP -->|payload| VM RFP -->|policies| POL BID -->|rfp| RFP BID -->|config| CFG BID -->|payload| BF ACC -->|rfp| RFP ACC -->|bid| BID REC -->|rfp| RFP REC -->|bid| BID REC -->|accept| ACC REC -->|payload| VM EV -->|receipt| REC EV -->|payload| PAY ``` - strongRef = `{uri, cid}` (`com.atproto.repo.strongRef`); a reader checks the CID it resolves equals the CID in the ref (`RepoStore.Resolve`) - `market.event.payload` must be in the repo of the event author (`applyGuestEvent` in `internal/market/bidder/guestevents.go`) ## Signatures - `market.rfp`, `market.bid`, `market.bids.*`, `market.accept`, `market.receipt`, `market.event` and every event payload carry `signatures` (`network.attested.signature`, [identity.md](identity.md#networkattested)) - 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`) ## Discovery | record | writer | reader | rule | |---|---|---|---| | `market.offering` at `self` | bidder (`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 `self` | bidder, every `spec.heartbeatIntervalSeconds` (default 60 s) | requester (`market.HeartbeatCache`), `internal/marketpresence` | 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 | | `market.relays` at `self` | no Go writer here | requester (`market.RelayURLsOf`) | extra relays to ask `listReposByCollection` | - 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](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 `#pdr_temp_market` A real offering and heartbeat (one of `bobvmbuilder.bsky.social`'s prod bidders, addresses trimmed): ```json {"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.mode` | requester ingress (submitBid, submitEvent) | streams | |---|---|---| | `XRPC` | yes | none | | `Firehose` | none | relay + Jetstream | | `Both` (requester default) | yes | relay + Jetstream | - stream composer: `internal/app/compose/streams.go`; collections per role: `compose.MarketStreamCollections` - requester streams carry only `market.bid`, `market.receipt`, `market.event`; bidder streams only `market.rfp`, `market.accept`, `market.event` - 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` ### XRPC procedures | NSID | served by | caller | body | answer | file | |---|---|---|---|---|---| | `market.submitRfp` | bidder ingress | requester | `{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`/`Unavailable` | `internal/services/bidder/routes.go` `handleSubmitRFP` | | `market.submitBid` | requester ingress | bidder | `{uri, cid, record}` of the `market.bid` | 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` | | `market.submitAccept` | bidder ingress | requester | `{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 | `handleSubmitAccept` | | `market.submitEvent` | both ingresses | the contract party that wrote the event | `{uri, cid, record}` of the `market.event` | 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 `#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/` holds `{key (age), fingerprint (DTLS)}`; an offerer writes `computer.socialweb.ingress.offer/.` (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/.` (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: }`, 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](lexicons-market.md#ingresswebrtc)) - 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 ## Bid Window And Selection - 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](identity.md#verifying)); 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) ## Policies Attached - the requester writes its policy record first and puts its strongRef in `market.rfp.policies` ([policy.md](policy.md#rfp-policy-strongrefs)) - the bidder runs its own workflow and then every attached policy, before it bids and again on the accept (`b.policy.EvaluatePolicies` in `acceptContract`) - the requester runs the attached policy on the winner before it writes the accept (`q.policy.Evaluate` in `runner.go`) - a market policy always runs, both sides, every decision. no verdict skips a run ([../SYSTEM.md](../SYSTEM.md#policies)) ## Sequence: RFP To Held ```mermaid sequenceDiagram autonumber participant R as Requester participant RP as requester repo participant S as relay / Jetstream participant B as Bidder participant BP as bidder repo participant G as guest VM R->>RP: S3 compute.vm (TID), policy record, market.rfp (TID, signed) R->>BP: getRecord offering + heartbeat at self of each candidate R->>B: submitRfp rfpUri rfpCid B-->>R: 200 name phase Deciding RP-->>S: commit market.rfp S-->>B: market.rfp (fallback, deduplicated) B->>RP: getRecord rfp, compute.vm, policies B->>B: bidder policy + every attached policy B->>BP: S4 wif config, bids.free, market.bid at BidRKey B->>R: submitBid BP-->>S: commit market.bid S-->>R: market.bid (fallback) R->>BP: getRecord bid at BidRKey (catch-up) R->>R: window, firstFree, attached policy on winner R->>RP: S5 market.accept at SessionRKey accept R->>B: submitAccept acceptUri acceptCid B-->>R: 202 provisioning intent B->>RP: getRecord accept, rfp, verify signatures, policies again B->>BP: S6 market.receipt at ReceiptRKey, cid binds the accept BP-->>S: commit market.receipt R->>BP: getRecord receipt at ReceiptRKey R->>R: VerifyReceipt, mint atirc token if spec.agent B->>G: ComputeVM, boot user_data G->>B: POST /v1/events vm.onNetwork iroh ticket B->>BP: S7 vm.onNetwork, vm.hostKeys + market.event B->>R: submitEvent R->>R: VMAddress + HostKeys set, secrets fetched, ComputeContract Held ``` - 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 - the guest side of S7 and S8: [guest-events.md](guest-events.md) ## 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](identity.md#guest-requester-r2)), 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`) ```mermaid sequenceDiagram autonumber participant R as Requester participant RP as requester repo participant A as atirc participant B as Bidder participant BP as bidder repo participant G as guest VM R->>R: spec.releaseRequestedAt, phase Releasing R->>B: submitEvent guest.r2Release (fromGuest only) B-->>R: submitEvent guest.r2Released R->>A: chat.atirc.revoke leased tokens (lease alive) R->>RP: S9 vm.delete at ReleasePayloadRKey + market.event R->>B: submitEvent vm.delete B->>B: verifyInboundDelete B->>G: stop, delete ComputeVM B->>BP: vm.terminated deleted_on_request + market.event at TerminationKey rkeys B->>R: submitEvent vm.terminated R->>BP: getRecord vm.terminated (FindTermination), up to 2 min R->>RP: delete own contract records: rbac, association, vm.delete + event, accept, rfp, compute.vm, policy, ContractEvents R->>R: ComputeContract Released ``` - 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](flow.md)): ```json {"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": ["..."]}} ``` - 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](identity.md#contract-scoped-association)) ## Revocation Ordering - 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](guest-events.md#agent-start-and-atirc-mint)) ## Records Policy - 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 ## See Also - [../SYSTEM.md](../SYSTEM.md#market-protocol): the market in one page; [../KCP.md](../KCP.md): the ComputeContract, Bid, ComputeVM and StateSync objects behind each record - [guest-events.md](guest-events.md), [lexicons-market.md](lexicons-market.md), [policy.md](policy.md), [identity.md](identity.md), [outside.md](outside.md) - `docs/ARCHITECTURE.md` section 15 for the decisions (stable rkeys, bid window, comms modes)