lexicons-market: one row per lexicon
- the fields of every lexicon come from the lexicon files: each section below includes its generated field table
(the
lexicon:link; on https://socialweb.computer/docs/protocol/lexicons-market.html the table is rendered in place) and adds what the code does with it: the rkey it writes, who writes and reads it, and the step - every lexicon, generated: https://socialweb.computer/docs/lexicons/ (XRPC methods: https://socialweb.computer/docs/xrpc/)
- covers every lexicon under
lexicons/com/publicdomainrelay/temp/exceptcluster.*(infra.md) andbadgeBlueKeys(identity.md), withcompute.secrets.getSecretsandcompute.config.wif.simpleat the end - the flows: market.md (rfp to release), guest-events.md (events under a receipt); steps S3 to S9: README.md
- headings drop the prefix
com.publicdomainrelay.temp.; file paths are underlexicons/com/publicdomainrelay/temp/ - the Go types are generated from these files into
internal/atproto/market/zz_generated.lexicons.go(go generateininternal/atproto/market/nsid.go) - "defined, not written": the lexicon and its NSID constant exist, but no Go code in this repo writes the record
Rows
| row | meaning |
|---|---|
| rkey | what the code writes, not only the lexicon key |
| written by / read by | role and the Go function |
| code notes | what the code does with a field, where it differs from what the lexicon allows |
| step | the README step it belongs to |
Summary
| NSID tail | rkey written | written by | step |
|---|---|---|---|
market.rfp | TID | requester | S3 |
market.bid | market.BidRKey | bidder | S4 |
market.bids.free | <bid rkey>-payload | bidder | S4 |
market.bids.x402 | none | defined, not written | S4 |
market.accept | SessionRKey("accept", ...) | requester | S5 |
market.accepts.free, market.accepts.x402 | none | defined, not written | S5 |
market.receipt | market.ReceiptRKey | bidder | S6 |
market.receipts.free, market.receipts.x402 | none | defined, not written | S6 |
market.event | per kind | both | S7-S9 |
market.offering | self | bidder | S3 (discovery) |
market.heartbeat | self (literal) | bidder | S3 (discovery) |
market.relays | self | no Go writer here | S3 (discovery) |
market.association | the agent DID | principal | S5, S8 |
market.associationRequest | the principal DID | guest requester | S8 |
computer.socialweb.peer | the subhandle | guest requester (its own and each co-located account's); requester (each spec.agent contract's atirc agent) | S8 |
market.submitRfp | - | served by bidder | S3 |
market.submitBid | - | served by requester | S4 |
market.submitAccept | - | served by bidder | S5 |
market.submitEvent | - | served by both | S7-S9 |
compute.vm | TID | requester | S3 |
compute.events.vm.* | per kind | bidder (vm.delete: requester) | S7, S9 |
compute.events.guest.* | per kind | requester or bidder for the guest | S8 |
compute.guest.subscribeEvents | - | served by bidder GuestControlPlane | S8 |
ingress.webRTC | webrtc (listen), TID (offer, answer) | requester, bidder | S3-S6 |
compute.secrets.getSecrets | - | served by requester | S8 |
compute.config.wif.simple | <bid rkey>-config | bidder | S4 |
market.rfp
com.publicdomainrelay.temp.market.rfp record key any
A request for proposals: the requester asks bidders to bid on the payload.
record
| field | type | description |
|---|---|---|
domain | string | The market domain of the payload; the requester writes compute. |
payload * | com.atproto.repo.strongRef | The requested thing, a record in the requester's repo; the requester writes a com.publicdomainrelay.temp.compute.vm. |
submitBid | string | Where bidders submit bids: a DID service ref (did#serviceId) or an HTTP URL. |
ingress | array of com.atproto.repo.strongRef | The requester's com.publicdomainrelay.temp.ingress.webRTC listen records: the transports a stream listener can use when submitBid names no reachable HTTP service. |
policies | array of com.atproto.repo.strongRef | Policy records the bidder evaluates before it bids. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | TID (putRFP puts the signed record at a TID it makes) |
| written by | requester: contractRunner in internal/market/requester/runner.go putRFP (market.BuildRFP, market.SignRecord, putRecord) |
| read by | bidder: stream or submitRfp, then getRecord (internal/market/bidder/submit.go SubmitRFP, acceptContract in internal/market/bidder/adapters.go); bid window from createdAt (internal/atproto/market/rfpwindow.go) |
| step | S3 |
market.bid
com.publicdomainrelay.temp.market.bid record key any
A bid on an RFP, written by the bidder.
record
| field | type | description |
|---|---|---|
rfp * | com.atproto.repo.strongRef | The market.rfp this bid answers. |
config | com.atproto.repo.strongRef | The bid configuration, such as a compute.config.wif.simple record. |
payload * | com.atproto.repo.strongRef | The terms: a market.bids.free or market.bids.x402 record. |
ingress | array of com.atproto.repo.strongRef | The bidder's com.publicdomainrelay.temp.ingress.webRTC listen records, including the STUN servers it gathers with. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | market.BidRKey(bidderDID, rfpURI, rfpCID) = bid-<20 hex>; also the Bid object name |
| written by | bidder: writeBidRecord in internal/market/bidder/bids.go (market.BuildBid, market.SignRecord) |
| read by | requester: submitBid (Requester.SubmitBid in internal/market/requester/callbacks.go), stream, catch-up getRecord at BidRKey (internal/market/requester/bidcatchup.go); bidder at accept time |
| step | S4 |
market.bids.free
com.publicdomainrelay.temp.market.bids.free record key any
Bid terms: the bidder provides the payload at no cost.
record
| field | type | description |
|---|---|---|
reason * | string | |
cost | integer | minimum 0 |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | <bid rkey>-payload |
| written by | bidder: writeBidRecord |
| read by | requester: free detection for firstFree (internal/market/requester/accept.go, internal/market/requester/inbox.go) |
| step | S4 |
market.bids.x402
com.publicdomainrelay.temp.market.bids.x402 record key any not in use
Defined, not written today: bid terms paid over x402, the payload of a market.bid; no bidder writes one, and the requester reads only cost from one it meets. Records written in 2026-06 remain in some repos.
record
| field | type | description |
|---|---|---|
cost * | integer | The price in the smallest unit of the currency. minimum 0 |
currency * | string | |
frequency * | string | |
prepay * | boolean | |
url * | string uri | The x402 payment endpoint. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | none: defined, not written |
| written by | no Go writer |
| read by | requester reads cost when a bid names one (internal/market/requester/accept.go, internal/market/requester/inbox.go) |
| step | S4 |
market.accept
com.publicdomainrelay.temp.market.accept record key any
A requester's signed accept of one bid on its RFP, in its own repo.
record
| field | type | description |
|---|---|---|
rfp * | com.atproto.repo.strongRef | The market.rfp. |
bid * | com.atproto.repo.strongRef | The accepted market.bid. |
payload | com.atproto.repo.strongRef | The accept terms: a market.accepts.free or market.accepts.x402 record; the requester sets none today. |
submitEvent | string | Where the bidder submits events: a DID service ref (did#serviceId) or an HTTP URL. |
ingress | array of com.atproto.repo.strongRef | The requester's com.publicdomainrelay.temp.ingress.webRTC listen records for the events of this contract. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| code notes | payload is never set by the code |
| rkey | acceptRKeyFor -> market.SessionRKey("accept", repoDID, contract, rfpURI, rfpCID, bidURI, bidCID) (internal/market/requester/secrets.go) |
| written by | requester: putAccept in runner.go (market.SignRecord, putRecord) |
| read by | bidder: submitAccept or stream -> provisioning StateSync (SubmitAccept in internal/market/bidder/submit.go, acceptContract); the receipt cid binds it |
| step | S5 |
market.accepts.free
com.publicdomainrelay.temp.market.accepts.free record key any not in use
Defined, not written today: accept terms for a market.bids.free bid, the optional payload of a market.accept; the requester sets no accept payload.
record
| field | type | description |
|---|---|---|
bid * | com.atproto.repo.strongRef | The accepted market.bid. |
payload | com.atproto.repo.strongRef | |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | none: defined, not written |
| written by | no Go writer (AcceptsFreeNSID constant only) |
| read by | none |
| step | S5 |
market.accepts.x402
com.publicdomainrelay.temp.market.accepts.x402 record key any not in use
Defined, not written today: accept terms for a market.bids.x402 bid, the optional payload of a market.accept; nothing writes or reads one. Records written in 2026-06 remain in some repos.
record
| field | type | description |
|---|---|---|
bid * | com.atproto.repo.strongRef | The accepted market.bid. |
payload | com.atproto.repo.strongRef | The terms of this accept; no code here writes or interprets it. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | none: defined, not written |
| written by | no Go writer (AcceptsX402NSID constant only) |
| read by | none |
| step | S5 |
market.receipt
com.publicdomainrelay.temp.market.receipt record key any
The bidder's receipt for an accept. cid binds the receipt to the accept record in the requester's repository.
record
| field | type | description |
|---|---|---|
rfp * | com.atproto.repo.strongRef | The market.rfp. |
bid * | com.atproto.repo.strongRef | The market.bid. |
accept * | com.atproto.repo.strongRef | The market.accept this receipt answers. |
payload | com.atproto.repo.strongRef nullable | The payload of the RFP this receipt answers (its compute.vm); null only when the writer has none, which the bidder never writes. |
submitEvent | string | The accept's submitEvent copied unchanged, where the bidder submits events to the requester (a DID service ref did#serviceId or an HTTP URL); present only when the bidder serves inbound XRPC. |
ingress | array of com.atproto.repo.strongRef | The bidder's com.publicdomainrelay.temp.ingress.webRTC listen records for this contract; the bidder writes none today. |
cid * | string cid | The attestation CID binding this receipt to the accept record and the accept repository. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| code notes | submitEvent is copied from the accept when the bidder serves inbound XRPC; payload is the RFP's compute.vm (null when none) |
| rkey | market.ReceiptRKey(acceptURI, acceptCID) = receipt-<32 hex> |
| written by | bidder: createReceipt in internal/market/bidder/submit.go -> market.CreateReceiptRecordAt (internal/atproto/market/attest.go) |
| read by | requester: FindReceipt (one getRecord, internal/market/requester/market.go), market.VerifyReceipt in acceptReceipt; policy trust (internal/policyengine/trust/association.go) |
| step | S6 |
market.receipts.free
com.publicdomainrelay.temp.market.receipts.free record key any not in use
Defined, not written today: receipt terms for a market.accepts.free accept; the bidder's market.receipt carries the RFP's compute.vm as its payload instead.
record
| field | type | description |
|---|---|---|
accept * | com.atproto.repo.strongRef | The market.accept. |
cid * | string cid | The attestation CID binding this receipt to the accept record. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | none: defined, not written |
| written by | no Go writer (ReceiptsFreeNSID constant; named in OAuth scopes, internal/atproto/oauth/scope.go) |
| read by | none |
| step | S6 |
market.receipts.x402
com.publicdomainrelay.temp.market.receipts.x402 record key any not in use
Defined, not written today: receipt terms for a market.accepts.x402 accept; nothing writes or reads one. Records written in 2026-06 remain in some repos.
record
| field | type | description |
|---|---|---|
accept * | com.atproto.repo.strongRef | The market.accept. |
cid * | string cid | The attestation CID binding this receipt to the accept record. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | none: defined, not written |
| written by | no Go writer (ReceiptsX402NSID constant; named in OAuth scopes) |
| read by | none |
| step | S6 |
market.event
com.publicdomainrelay.temp.market.event record key any
An event envelope under a receipt; the payload is a compute.events record.
record
| field | type | description |
|---|---|---|
receipt * | com.atproto.repo.strongRef | The market.receipt the event belongs to. |
payload * | com.atproto.repo.strongRef | The event payload, a com.publicdomainrelay.temp.compute.events.* record in the same repo as this envelope. |
createdAt | string datetime | |
signatures * | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder: market.EventRKeys(key) second value <prefix>-event-<32 hex>; requester: SessionRKey("event", receiptURI) for vm.delete, SessionRKey("contract-event-envelope", uid) for ContractEvents |
| written by | bidder event adapter (writeMarketEvent in internal/market/bidder/adapters.go); requester destroyEnvelope (runner.go), publishContractEvent (internal/market/requester/contractevents.go); both via market.PutEvent |
| read by | the other party: submitEvent or stream; requester FindTermination |
| step | S7, S8, S9 |
market.offering
com.publicdomainrelay.temp.market.offering record key any
A bidder announces the payload collections it bids on and where it takes RFPs. Writers use rkey self; readers read self and the record the bidder's heartbeat names.
record
| field | type | description |
|---|---|---|
endpoints | array of #endpoint | Where requesters call the bidder's market XRPC, in the bidder's order of preference. Service auth for any of them has aud <bidder DID>#pdr_temp_market (#pdr_temp_compute_event for submitEvent). |
ingress | array of com.atproto.repo.strongRef | The bidder's com.publicdomainrelay.temp.ingress.webRTC listen records, including the STUN servers it gathers with; the bidder writes none today and publishes a computer.socialweb.ingress.listen record (a webrtc endpoint) instead. |
appliesTo * | array of string nsid | The payload collections the bidder bids on. items.format nsid |
maxCpus | integer | The most vCPUs one compute.vm may ask for; the bidder refuses an RFP that asks for more. Absent: no limit advertised. minimum 1 |
maxMem | string | The most memory one compute.vm may ask for, such as 16G; the bidder refuses an RFP that asks for more. Absent: no limit advertised. |
nestedVirt | boolean | The bidder's VMs can run VMs of their own (QEMU on a host with KVM nested virtualization on). A requester whose compute.vm sets nestedVirt skips a bidder without it; the bidder refuses such an RFP. |
images | boolean | The bidder boots a requester-chosen VM image (compute.vm image) for its guest image target. A requester whose compute.vm sets image skips a bidder without it; the bidder refuses such an RFP. |
createdAt * | string datetime | |
refreshedAt | string datetime | |
withdrawnAt | string datetime | Set when the bidder stopped taking RFPs; appliesTo is empty then. |
also: #endpoint
| item | value |
|---|---|
| rkey | self (market.OfferingRKey) |
| written by | bidder: putOffering, withdraw in internal/market/bidder/offering.go |
| read by | requester: market.ReadOffering (self, else the rkey the heartbeat names), market.OfferingApplies; relays list its repos by listReposByCollection |
| step | S3 (discovery) |
market.heartbeat
com.publicdomainrelay.temp.market.heartbeat record key literal:self
A bidder's liveness beat for its offering, rewritten at rkey self.
record
| field | type | description |
|---|---|---|
offering * | string at-uri | The market.offering this beat keeps alive. |
createdAt * | string datetime | |
version | #runningVersion | The bidder build this beat comes from (plan 0040): its version, commit and binary sha256. |
also: #runningVersion
| item | value |
|---|---|
| rkey | self |
| written by | bidder: beat in internal/market/bidder/offering.go, every HeartbeatInterval (60 s) |
| read by | requester: market.HeartbeatCache.FreshDIDs (fresh = at most HeartbeatTTL 300 s old); internal/marketpresence |
| step | S3 (discovery) |
market.relays
com.publicdomainrelay.temp.market.relays record key any
The relays a participant crawls and asks others to crawl, read in market discovery. Writers use rkey self; readers read only self. No Go code writes it.
record
| field | type | description |
|---|---|---|
relays * | array of string uri | HTTP or HTTPS relay base URLs. items.format uri |
createdAt * | string datetime |
| item | value |
|---|---|
| rkey | self (market.RelaysRKey) |
| written by | no Go writer in this repo |
| read by | requester discovery: market.RelayURLsOf from relaySources in internal/market/requester/discovery.go |
| step | S3 (discovery) |
market.association
com.publicdomainrelay.temp.market.association record key any
The grant: the repository that holds this record (the principal) trusts the agent DID as its agent, beside the link.ident.endorsement at the same record key. The pair without the grant is attribution only. Record key: the agent DID.
record
| field | type | description |
|---|---|---|
agent * | string did | The agent DID; equal to the record key. |
expiresAt | string datetime | The grant is dead after this time; required with contract. |
contract | com.atproto.repo.strongRef | The market.accept of the contract this grant is scoped to; dead once the contract is not Held. |
createdAt * | string datetime |
| item | value |
|---|---|
| rkey | the agent DID |
| meaning | the grant beside the link.ident.endorsement at the same rkey: identity.md |
| written by | the operator (standing, no contract: compose.ApplyOperatorPair, scripts/associate-bidder.ts); the requester for its guest requester (contract = the accept {uri, cid}, expiresAt = accept + 24 h: internal/market/requester/association.go); the guest requester for its co-located accounts (R2's contract and expiresAt: internal/app/compose/peer.go) |
| read by | internal/identlink walk: policy trust, bidder lifetime cap (internal/market/bidder/association.go, ComputeVM spec.associationExpiresAt = the walk expiresAt; spec.associationContracts = the contracts (accept + receipt) of its contract-scoped grants at accept, and the VM ends association_ended once each of them has its vm.terminated or vm.delete), requester discovery, MarketIdentity |
| chain | from the agent's DID document (alsoKnownAs agent-of), up to maxDepth (AssociationPolicy maxDepth, 1 to 100, default 100), 256 getRecords per walk. socialweb-computer internal association <did> prints the walk |
| step | S5, S8; release deletes only its own |
market.associationRequest
com.publicdomainrelay.temp.market.associationRequest record key any
The repository that holds this record asks the principal to endorse and grant it for one contract: the proof that the subject DID of a com.publicdomainrelay.temp.compute.events.guest.requesterDid event controls this repository. Record key: the principal DID.
record
| field | type | description |
|---|---|---|
principal * | string did | The DID asked to write the endorsement and the grant. |
contract * | string at-uri | The principal's market.accept of the contract whose guest runs this repository's requester. |
nonce * | string | The nonce the principal put into that contract's secrets bundle. maxLength 128 |
accounts | array of string did | The DIDs of the co-located accounts this repository's requester created for the contract, each with the principal's rotation key first, so the principal can tombstone them when the guest is gone. maxLength 16 items.format did |
createdAt * | string datetime |
| item | value |
|---|---|
| rkey | the principal DID (compose.ApplyAssociationRequestRecord) |
| written by | the guest requester: an AtprotoRecord object from internal/app/compose/records.go |
| read by | the authority requester: one getRecord in the DID the guest reported (internal/market/requester/association.go); cmd/socialweb-computer/requestassociation.go |
| step | S8; flow: identity.md |
computer.socialweb.peer
computer.socialweb.peer record key any
How to reach one subhandle of the repository's account directly. Record key: the subhandle. Read with one getRecord(DID, computer.socialweb.peer, subhandle); never listed. A reader trusts the record only while the identlink walk of the repository DID reaches the owner: every grant unexpired and its contract Held. A stale record whose walk no longer reaches the owner is ignored.
record
| field | type | description |
|---|---|---|
iroh | string | A short iroh ticket (node id and relay, no addresses) whose endpoint serves this account's XRPC directly. maxLength 1024 |
webrtc | string did | The DID whose repo answers computer.socialweb.ingress.offer records for this account; no writer sets it today. |
channels | array of string | The atirc channels the subhandle is in; no writer sets it today. maxLength 64 items.maxLength 256 |
createdAt * | string datetime |
| item | value |
|---|---|
| code notes | only createdAt and iroh are written; no writer sets webrtc or channels |
| rkey | the subhandle: the guest requester's atirc subhandle (r2-<accept rkey>.<owner handle>, its handle without one); <name>.<that> for a co-located account; <label>-<rfp rkey>.<handle> for a contract's atirc agent (label: the handle's first label, at most 14 characters) |
| iroh | the short ticket of the node that is that identity: for an account a PDS hosts, the PDS's XRPC endpoint (ingress-iroh); for an atirc agent identity, its atirc mesh run daemon (ALPN atirc/mesh/1). One identity, one node; the dialer picks the protocol by ALPN |
| written by | the guest requester (run request --guest-requester [--colocated a,b]): AtprotoRecord objects of internal/app/compose/peer.go in its own repo and each co-located account's, present only while its association ref verifies. The requester of a spec.agent contract writes no peer record: after the verified receipt it puts the agent's iroh key (a 32-byte ed25519 seed, /etc/atirc/iroh_key.hex, 0600) and, for a guest requester, R2_COLOCATED=<nick>=<ticket> (/etc/socialweb-computer/r2-agent.env) into the bundle (internal/market/requester/agentpeer.go publishAgentPeer), and R2 writes the agent's peer record |
| read by | mesh peers: one getRecord(DID, computer.socialweb.peer, subhandle), never listRecords; trusted only while the walk of the repo DID reaches the owner |
| release | the guest requester's run request release sets spec.peer.retire: the peer, association and endorsement records are deleted, each local account deactivated and its did:plc tombstoned (best effort; expiry covers a skipped cleanup) |
market.submitRfp
com.publicdomainrelay.temp.market.submitRfp procedure
A requester submits an RFP to a bidder. The bidder records a bid intent and answers before it bids. Requires a service-auth JWT with lxm set to this NSID; the requester is the token issuer.
input
| field | type | description |
|---|---|---|
rfpUri * | string at-uri | The market.rfp record. |
rfpCid * | string cid | |
ingress | array of com.atproto.repo.strongRef | The com.publicdomainrelay.temp.ingress.webRTC offer records for this bidder. The bidder answers them in the reply with its own answer and listen records. |
output
| field | type | description |
|---|---|---|
ok * | boolean | |
name | string | The bid intent the bidder recorded. |
phase | string | The phase of the bid intent. |
declined | object | Present when this bidder will not bid on the RFP, found by the checks of the bid decision that need no wait. The intent is recorded and fails as before, except for a compute kind this bidder does not serve: that answer carries no intent (name is empty) and declined unservable. |
ingress | array of com.atproto.repo.strongRef | The bidder's com.publicdomainrelay.temp.ingress.webRTC answer and listen records for the request's offers, carrying the SDP and the bidder's STUN servers. |
errors
| error | description |
|---|---|
InvalidRequest | 400: the body is not JSON, or rfpUri or rfpCid is missing. |
Unauthorized | 401: the service-auth token is missing or not valid for this method. |
Forbidden | 403: the token's issuer may not submit this RFP. |
RFPClosed | 409: the RFP's bid window (10 minutes, counted on this route from the RFP's TID rkey, before the record is read) is over; the bidder records no intent. |
InternalError | 500: the bid intent could not be recorded. |
Unavailable | 503: the bidder is starting and cannot authorize or bid yet. |
Suspended | 503: the bidder operator suspended its participation (spec.suspendParticipation). |
| item | value |
|---|---|
| input | {rfpUri, rfpCid, ingress?} (ingress = ingress.webRTC offers) |
| output | {ok, name, phase, ingress?, declined?: {kind, reason}} (declined: the bidder will not bid; kind capacity = full now, unservable = nothing but another bidder will do); 409 RFPClosed once the bid window is over; every error is in the lexicon |
| served by | bidder: handleSubmitRFP in internal/services/bidder/routes.go -> Bidder.SubmitRFP |
| called by | requester: solicitBids -> HTTPMarket.SubmitRFP (internal/market/requester/runner.go, market.go) |
| step | S3 |
market.submitBid
com.publicdomainrelay.temp.market.submitBid procedure
A bidder submits a bid it wrote to the requester. Requires a service-auth JWT with lxm set to this NSID; the bidder is the token issuer.
input
| field | type | description |
|---|---|---|
uri * | string at-uri | The market.bid record. |
cid * | string cid | |
record * | com.publicdomainrelay.temp.market.bid | The market.bid record value. |
ingress | array of com.atproto.repo.strongRef | The bidder's com.publicdomainrelay.temp.ingress.webRTC listen records for this call. |
output
| field | type | description |
|---|---|---|
ok * | boolean | |
ingress | array of com.atproto.repo.strongRef | The requester's com.publicdomainrelay.temp.ingress.webRTC listen records for this call. |
errors
| error | description |
|---|---|
InvalidRequest | 400: the body is not JSON or the record is not a valid market.bid. |
Unauthorized | 401: the service-auth token is missing or not valid for this method. |
Forbidden | 403: the bid record is not in the token issuer's repo. |
Unavailable | 503: the requester is starting, or it could not queue the bid. |
| item | value |
|---|---|
| input | {uri, cid, record} of the market.bid, ingress? |
| output | {ok, ingress?}; errors InvalidRequest, Unauthorized, Forbidden, Unavailable |
| served by | requester ingress: internal/services/requester/routes.go -> Requester.SubmitBid; the bidder route only parses it |
| called by | bidder: submitBid in internal/market/bidder/submit.go to the RFP's submitBid |
| step | S4 |
market.submitAccept
com.publicdomainrelay.temp.market.submitAccept procedure
A requester submits its accept of a bid to the bidder, which records a provisioning intent and answers 202 at once. The receipt follows later as a market.receipt record in the bidder's repo, which the requester reads by one getRecord. Requires a service-auth JWT with lxm set to this NSID; the requester is the token issuer.
input
| field | type | description |
|---|---|---|
acceptUri * | string at-uri | The market.accept record. |
acceptCid * | string cid | The CID of the market.accept record. |
ingress | array of com.atproto.repo.strongRef | The requester's com.publicdomainrelay.temp.ingress.webRTC listen records for this call; the bidder reads the field and does not act on it today. |
output
| field | type | description |
|---|---|---|
ok * | boolean | Always true on the 202 answer. |
id * | string | The name of the provisioning intent the bidder recorded for this accept. |
acceptUri * | string at-uri | The accept of the request, echoed. |
acceptCid * | string cid | The accept CID of the request, echoed. |
errors
| error | description |
|---|---|
InvalidRequest | 400: the body is not JSON, or acceptUri or acceptCid is missing. |
Unauthorized | 401: the service-auth token is missing or not valid for this method. |
Forbidden | 403: the token's issuer may not submit this accept. |
CapacityExceeded | 409: taking the accept would overcommit the bidder's host; the requester excludes this bidder and accepts the next bid. |
InternalError | 500: the provisioning intent could not be recorded. |
Unavailable | 503: the bidder is starting and cannot authorize or take accepts yet. |
| item | value |
|---|---|
| input | {acceptUri, acceptCid, ingress?} |
| output | 202 {ok, id, acceptUri, acceptCid}; 409 CapacityExceeded when the accept would overcommit the host; every error is in the lexicon |
| served by | bidder: handleSubmitAccept -> Bidder.SubmitAccept (provisioning StateSync) |
| called by | requester: submitAcceptAndWait (internal/market/requester/accept.go) |
| step | S5 |
market.submitEvent
com.publicdomainrelay.temp.market.submitEvent procedure
A contract party submits a market.event it wrote to the other party. Requires a service-auth JWT with lxm set to this NSID; the sender is the token issuer and must be the accept author (to a bidder) or the receipt author (to a requester).
input
| field | type | description |
|---|---|---|
uri * | string at-uri | The market.event record. |
cid * | string cid | |
record * | com.publicdomainrelay.temp.market.event | The market.event record value. |
ingress | array of com.atproto.repo.strongRef | The sender's com.publicdomainrelay.temp.ingress.webRTC listen records for this call. |
output
| field | type | description |
|---|---|---|
ok * | boolean | |
ingress | array of com.atproto.repo.strongRef | The receiver's com.publicdomainrelay.temp.ingress.webRTC listen records for this call. |
errors
| error | description |
|---|---|
InvalidRequest | 400: the body is not JSON, uri, cid or record is missing, or the record is not a valid market.event (to a requester: its payload must be one of the compute events a bidder publishes, the vm.* reports and the guest's own events). |
Unauthorized | 401: the service-auth token is missing or not valid for this method. |
Forbidden | 403: the sender is not the accept author (to a bidder), or the event is not in the token issuer's repo (to a requester). |
Unavailable | 503: the receiver is starting, or it could not record the event. |
| item | value |
|---|---|
| input | {uri, cid, record} of the market.event, ingress? |
| output | {ok, ingress?}; 403 Forbidden "not the accept author" |
| served by | bidder handleSubmitEvent -> Bidder.SubmitEvent; requester Requester.SubmitEvent (callbacks.go) |
| called by | requester releaseContract, publishContractEvent; bidder event adapter (internal/market/bidder/adapters.go) |
| step | S7, S8, S9 |
compute.vm
com.publicdomainrelay.temp.compute.vm record key any
A requested virtual machine: the payload of a compute RFP.
record
| field | type | description |
|---|---|---|
role * | string | The VM name within the requester's contract. |
kind | string | What the bidder runs for this request: a firecracker virtual machine (the default when absent), or a deno sandbox that runs user_data as its program and reports its output as a guest event. knownValues ["vm","deno"] |
cpus | integer | vCPUs for the VM; the requester writes 2 unless the contract says otherwise, and the bidder takes 2 when absent. minimum 1 |
mem | string | Guest memory size, such as 4G; the requester writes 4G unless the contract says otherwise, and the bidder takes 4G when absent. |
nestedVirt | boolean | The VM must run VMs of its own; only a bidder whose offering sets nestedVirt runs it. |
disk | string | Disk size, such as 50G (the requester always writes 50G). A requester image's kernel and rootfs together fit in it. |
image | #image | |
network | string | Network transfer allowance, such as 500G; the requester writes none and the bidder ignores it today. |
location | #location | Where the VM should run; the requester writes none and the bidder ignores it today. |
user_data | string | cloud-init user data. |
net | boolean | kind deno: the program reaches the public internet (never loopback, link-local or private ranges). A bidder runs it only for its owner: the requester is the bidder's DID, its operator, or associated to that operator. |
expiresAt | string datetime | When the requester wants the VM ended. The bidder ends it then (it may end it earlier by its own policy) and refuses an RFP whose expiresAt has passed; without it, the bidder ends the VM 24 h after the accept. |
createdAt | string datetime |
| item | value |
|---|---|
| rkey | TID (putSetupRecord: putRecord at a TID; unsigned) |
| written by | requester: runner.go with DefaultComputeCPUs, DefaultComputeMem, DefaultComputeDisk (internal/market/requester/requester.go); user_data from cloudinit.BuildUserData (internal/atproto/cloudinit) |
| read by | bidder through rfp.payload: kind check (rfpKind in submit.go), boot (acceptContract, internal/guestseed adds the binaries unit) |
| step | S3 |
compute.events.vm.delete
com.publicdomainrelay.temp.compute.events.vm.delete record key any
The requester asks the bidder to delete the VM of a contract; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
reason * | string | Why the requester asks for the stop; the requester writes released. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | market.ReleasePayloadRKey(receiptURI) = SessionRKey("delete", receiptURI) |
| written by | requester: destroyEnvelope in internal/market/requester/runner.go |
| read by | bidder: verifyInboundDelete, applyRelease (internal/market/bidder/adapters.go); policy trust |
| step | S9 |
compute.events.vm.hostKeys
com.publicdomainrelay.temp.compute.events.vm.hostKeys record key any
The bidder reports the VM's SSH host keys; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
keys * | array of #hostKey | |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
also: #hostKey
| item | value |
|---|---|
| rkey | EventRKeys("hostKeys:<receipt>") -> hostkeys-payload-<32 hex> |
| written by | bidder: report in internal/market/bidder/report.go from the host key bound at login (RecordBoundHostKey in internal/guestidentity/service.go) |
| read by | requester: waitGuest -> status.contract.hostKeys |
| step | S7 |
compute.events.vm.onNetwork
com.publicdomainrelay.temp.compute.events.vm.onNetwork record key any
The bidder reports a network address of the VM; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
kind | string | What address is. Absent, it reads as iroh when tag is absent and https when tag is present; the bidder leaves it absent for those two. iroh: address is the VM's iroh ticket. https: tag names the tunnel and address is its https URL. webrtc: tag names the tunnel and address is the guest agent's DTLS certificate fingerprint ("sha-256 AB:CD:..."), which the requester checks against the a=fingerprint of the guest's answer. sandbox: a deno sandbox (compute.vm kind deno) is running, address sandbox://<ComputeVM name>, no tag. knownValues ["iroh","https","webrtc","sandbox"] maxLength 16 |
address | string | The VM's address for kind: the iroh ticket (iroh), the URL of the tagged tunnel (https), the guest agent's DTLS certificate fingerprint "sha-256 AB:CD:..." (webrtc), or sandbox://<ComputeVM name> (sandbox). |
tag | string | Names one of the VM's tunnels (spec.tunnels of the contract); absent, address is the VM's iroh ticket. maxLength 32 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | EventRKeys("onNetwork:<receipt>") or EventRKeys("onNetwork:<tag>:<receipt>") |
| written by | bidder: report (internal/market/bidder/report.go) from the guest POST (Guest.onNetwork in internal/guestidentity/service.go); sandbox: internal/market/bidder/sandbox.go |
| read by | requester: waitGuest -> status.contract.vmAddress, status.contract.networks |
| step | S7 |
compute.events.vm.sandbox
com.publicdomainrelay.temp.compute.events.vm.sandbox record key any
A deno sandbox reports that its program ended, with its output; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
exitCode * | integer | The program's exit status; -1 when it was stopped at its deadline, killed by a signal, or could not be run. |
timedOut | boolean | The sandbox was stopped at its deadline rather than ending on its own. |
stdout | string | The program's standard output, cut to its first 65536 bytes. maxLength 65536 |
stderr | string | The program's standard error, cut to its last 65536 bytes. maxLength 65536 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | EventRKeys("<nsid>:<receipt>") |
| written by | bidder: internal/market/bidder/sandbox.go (compute.vm.kind: deno) |
| read by | requester: status.contract.sandbox (internal/market/requester/events.go, runner.go) |
| step | S7 |
compute.events.vm.memoryPressure
com.publicdomainrelay.temp.compute.events.vm.memoryPressure record key any
The bidder reports that the VM's host cgroup crossed a memory threshold (memory.events high or max increased); sent as the payload of a market.event, edge-triggered and capped per contract.
record
| field | type | description |
|---|---|---|
kind * | string | The cgroup threshold crossed: high (reclaim pressure) or max (the hard limit). knownValues ["high","max"] |
threshold * | integer | The cgroup limit crossed, in bytes: memory.high or memory.max of the VM's cgroup (0 when that limit is max). |
observed * | integer | memory.current in bytes when the crossing was seen. |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | from the report StateSync key <nsid>:<kind>-<n>:<receipt> |
| written by | bidder: internal/market/bidder/memory.go (edge-triggered from the VM cgroup's memory.events: one per crossing, re-armed after 5 min below 90% of the threshold, at most 1 per kind per 10 min and 10 memory events per contract) |
| read by | none in Go (requesters and the watch page) |
| step | S7 |
compute.events.vm.oomKilled
com.publicdomainrelay.temp.compute.events.vm.oomKilled record key any
The bidder reports that the kernel OOM-killed processes in the VM's host cgroup (memory.events oom_kill increased); sent as the payload of a market.event, one per new kill count, capped per contract.
record
| field | type | description |
|---|---|---|
kills * | integer | OOM kills in the VM's cgroup since the bidder's previous sample (it polls every 15 s); kills while the per-contract cap of 10 reports is reached are not reported later. |
total * | integer | OOM kills in the cgroup's lifetime. |
limit * | integer | memory.max in bytes. |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | from the report StateSync key <nsid>:oom-<n>:<receipt> |
| written by | bidder: internal/market/bidder/memory.go (one per new oom_kill count, inside the same 10-per-contract cap) |
| read by | none in Go |
| step | S7 |
compute.events.vm.terminated
com.publicdomainrelay.temp.compute.events.vm.terminated record key any
The bidder reports that the VM stopped; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
reason * | string | Why the VM ended: guest_poweroff, vmm_exited, oom, host_reboot, identity_mismatch or image_refused when the VM was lost; deleted_on_request after a vm.delete or another release; expired when the bidder released it after the requester's contract-scoped association expired; association_ended when that association's contract ended (market.VMTerminatedReasons). knownValues ["guest_poweroff","vmm_exited","oom","host_reboot","identity_mismatch","deleted_on_request","expired","image_refused","association_ended"] |
exitCode | integer | The VMM's exit status; the bidder does not write it today. |
observedAt * | string datetime | When the bidder saw the VM gone; createdAt is the same time. |
request | com.atproto.repo.strongRef | The compute.events.vm.delete that asked for the stop. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | EventRKeys(TerminationKey(receiptURI)) -> termination-payload-<32 hex> |
| written by | bidder: termination StateSync (internal/computevm/termination.go, internal/controllers/computevm/controller.go), adapter atproto.market.event |
| read by | requester FindTermination (market.go); atirc via the token lease (contractLease in internal/market/requester/atirc.go); policy trust |
| step | S9 |
compute.events.guest.publicKey
com.publicdomainrelay.temp.compute.events.guest.publicKey record key any
A party to a contract publishes an encryption public key for one tag; sent as the payload of a market.event. Anything sealed under that tag is sealed to the latest publicKey of the other side. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said.
record
| field | type | description |
|---|---|---|
kind * | string | The key type. age-x25519: key is an age X25519 recipient (age1...). knownValues ["age-x25519"] maxLength 32 |
tag * | string | Names the tunnel of the contract (spec.tunnels) or another purpose the key is for. maxLength 32 |
key * | string | The public key in the text form of kind. maxLength 256 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | requester: SessionRKey("contract-event", uid); bidder: EventRKeys("guest:...") |
| written by | requester (outbound ContractEvent, contractevents.go); bidder for the guest (PublishGuestEvent in internal/market/bidder/guestevents.go) |
| read by | guest agent (internal/guestagent/subscribe.go); requester (inbound ContractEvent) |
| step | S8 |
compute.events.guest.signalWebRTC
com.publicdomainrelay.temp.compute.events.guest.signalWebRTC record key any
A sealed WebRTC session description for one tunnel; sent as the payload of a market.event. Non-trickle ICE: the requester offers once with all candidates, the guest answers once. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said. The bidder never opens the ciphertext.
record
| field | type | description |
|---|---|---|
kind * | string | The SDP type of the sealed session description. knownValues ["offer","answer"] maxLength 16 |
tag * | string | Names the webrtc tunnel of the contract (spec.tunnels). maxLength 32 |
ciphertext * | string | The session description, age armored ciphertext. The plaintext is the JSON object {"sdp": <session description>, "replyTo": <age recipient, offers only>}: an offer is sealed to the guest's latest compute.events.guest.publicKey for the tag and names in replyTo the age recipient the answer must be sealed to; an answer is sealed to that replyTo. No record names the key, so a reader opens every signal for the tag with its identity and keeps the ones that open. maxLength 16384 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | as guest.publicKey |
| written by | requester (CLI / browser ContractEvent, internal/stack/request/webrtc.go); bidder for the guest |
| read by | guest agent (internal/guestagent/session.go, subscribe.go); requester (inbound ContractEvent) |
| step | S8 |
compute.events.guest.secrets
com.publicdomainrelay.temp.compute.events.guest.secrets record key any
The requester's secrets bundle for the guest, sealed to the guest's latest compute.events.guest.publicKey with tag secrets; sent as the payload of a market.event. Requester-authored only: the bidder forwards it to the guest's subscription and never opens the ciphertext. Only when the firehose is the only way: a requester with an inbound endpoint serves the bundle on its getSecrets route alone, after a workload identity exchange. A requester sends one only when its comms mode is Firehose (no inbound endpoint), its spec.secretsFallback is Sealed and the guest posted a compute.events.guest.secretsRequested.
record
| field | type | description |
|---|---|---|
ciphertext * | string | The bundle, age armored ciphertext. The plaintext is the JSON array the getSecrets route serves: [{"path": <absolute path>, "value": <file content>, "mode": <optional octal file mode, at most 0600>}]. No record names the key it is sealed to; the guest opens every secrets event with its identity and keeps the ones that open. maxLength 65536 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | SessionRKey("contract-event", uid) of ContractEvent secrets-<contract> |
| written by | requester only, on demand: sealGuestSecrets in internal/market/requester/guestsecrets.go |
| read by | guest agent (internal/guestagent/secrets.go); the bidder forwards it unopened |
| step | S8 |
compute.events.guest.secretsRequested
com.publicdomainrelay.temp.compute.events.guest.secretsRequested record key any
The guest asks the requester for its secrets bundle sealed to its compute.events.guest.publicKey with tag secrets, because the requester has no inbound endpoint (comms mode Firehose); sent as the payload of a market.event. Guest-originated only, and only when the requester enabled the sealed fallback; a requester with an inbound endpoint drops it. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent (comms mode Firehose with secretsFallback: Sealed only) |
| read by | requester: status.contract.secretsRequested, then sealGuestSecrets |
| step | S8 |
compute.events.guest.secretsApplied
com.publicdomainrelay.temp.compute.events.guest.secretsApplied record key any
The guest wrote the files of its secrets bundle; sent as the payload of a market.event. Guest-originated only: the guest posts it to its bidder, which signs and publishes it to the requester.
record
| field | type | description |
|---|---|---|
via * | string | The path that delivered the bundle: sealed (a compute.events.guest.secrets record, for a requester without an inbound endpoint). A requester refuses getSecrets here: its own getSecrets route records that fetch. knownValues ["getSecrets","sealed"] maxLength 16 |
count | integer | The number of files written. minimum 0 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent |
| read by | requester: status.contract.secretsApplied, condition SecretsApplied |
| step | S8 |
compute.events.guest.secretsUpdated
com.publicdomainrelay.temp.compute.events.guest.secretsUpdated record key any
The requester changed the contract's secrets bundle (the association ref of spec.association); the guest fetches it again through getSecrets, or asks for the sealed fallback; sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | SessionRKey("contract-event", uid) of ContractEvent secrets-updated-<SessionRKey("secretsUpdated", contract, ref)> |
| written by | requester only: notifySecretsUpdated (internal/market/requester/association.go), every fresh atirc mint |
| read by | guest agent: fetch the bundle again |
| step | S8 |
compute.events.guest.agentStart
com.publicdomainrelay.temp.compute.events.guest.agentStart record key any
The requester asks the guest agent to start the guest's agent unit (the contract's spec.agent); sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | SessionRKey("contract-event", uid) |
| written by | requester only (run request agent <name> -> ContractEvent; needs spec.agent) |
| read by | guest agent: systemctl start --no-block atirc-agent.service (internal/guestagent/agentstart.go) |
| step | S8 |
compute.events.guest.requesterDid
com.publicdomainrelay.temp.compute.events.guest.requesterDid record key any
The guest reports the repo DID of the requester it runs, so the contract's requester can associate it (spec.association.fromGuest); sent as the payload of a market.event. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
did * | string did | The did:plc of the requester the guest runs; any other DID method, and the outer requester's own DID, is refused. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent (internal/guestagent/association.go) |
| read by | requester: status.contract.guestRequester (internal/market/requester/association.go, market.ValidGuestRequesterDID) |
| step | S8 |
compute.events.guest.r2Start
com.publicdomainrelay.temp.compute.events.guest.r2Start record key any
The requester asks the guest agent to start the guest requester (socialweb-r2.service, run request --guest-requester as the r2 user) of a contract with spec.association.fromGuest; sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
name * | string | The guest requester's invocation name: a lowercase DNS label of 1 to 63 characters. maxLength 63 |
agent | boolean | The guest requester asks for an atirc agent on its own guest and starts it once held. |
hold | boolean | The guest requester keeps its own contract held. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | SessionRKey("contract-event", uid) |
| written by | requester only (run request r2 <name>; needs spec.association.fromGuest) |
| read by | guest agent: starts socialweb-r2.service (internal/guestagent/association.go) |
| step | S8 |
compute.events.guest.r2Release
com.publicdomainrelay.temp.compute.events.guest.r2Release record key any
The requester, releasing its contract, asks the guest agent to release every contract the guest requester holds before the guest goes away; the guest answers with compute.events.guest.r2Released. Sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | SessionRKey("contract-event", uid) |
| written by | requester only: releaseGuestRequester (internal/market/requester/guestrequester.go) |
| read by | guest agent: socialweb-r2-release.service |
| step | S9 |
compute.events.guest.r2Released
com.publicdomainrelay.temp.compute.events.guest.r2Released record key any
The guest reports that its guest requester released its contracts (or holds none) after a compute.events.guest.r2Release; sent as the payload of a market.event. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
ok * | boolean | Every guest requester contract was released. |
message | string | maxLength 512 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent |
| read by | requester: status.contract.r2Release, condition GuestRequesterReleased |
| step | S9 |
compute.events.guest.memoryPressure
com.publicdomainrelay.temp.compute.events.guest.memoryPressure record key any
The guest crossed a memory threshold (edge-triggered: one record per crossing, re-armed only after the value stayed under half the threshold for 5 min; at most one per kind per 10 min and ten memory events per contract); sent as the payload of a market.event. Guest-originated only. It carries no secret. The host-side counterpart is compute.events.vm.memoryPressure.
record
| field | type | description |
|---|---|---|
kind * | string | What crossed: psi, /proc/pressure/memory some avg10; swap, the share of the guest's swap in use. knownValues ["psi","swap"] maxLength 16 |
threshold * | integer | The crossed threshold, in hundredths of a percent (psi: of some avg10; swap: of swapTotal). minimum 0 maximum 10000 |
psiSomeAvg10 | integer | /proc/pressure/memory some avg10, in hundredths of a percent; absent without PSI. minimum 0 maximum 10000 |
psiFullAvg10 | integer | /proc/pressure/memory full avg10, in hundredths of a percent; absent without PSI. minimum 0 maximum 10000 |
swapUsed * | integer | Swap in use, in bytes. minimum 0 |
swapTotal * | integer | The guest's swap, in bytes. minimum 0 |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent (internal/guestagent/memory.go), capped by memoryEventCapped |
| read by | requester (requester_market_event), the test modules (readings.memory), the watch page |
compute.events.guest.oomKill
com.publicdomainrelay.temp.compute.events.guest.oomKill record key any
The guest kernel's OOM killer killed a process (/proc/vmstat oom_kill rose); sent as the payload of a market.event. One record per rise, at most one per 10 min (a later one carries every kill since) and ten memory events per contract. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
kills * | integer | The kills since the last oomKill of this guest. minimum 1 |
total * | integer | The guest's oom_kill count since boot. minimum 1 |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent (internal/guestagent/memory.go), capped by memoryEventCapped |
| read by | requester (requester_market_event), the test modules (fail the run), the watch page |
compute.events.guest.image
com.publicdomainrelay.temp.compute.events.guest.image record key any
The guest reports the image it booted: the marker in its /etc/swc-image; sent as the payload of a market.event. One per contract, from a guest whose image has the file. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
marker * | string | The first line of the guest's /etc/swc-image, trimmed (no event when it is empty; no cap beyond the 24 KiB bound on a guest-originated event); the requester compares it with the marker of the image.json it asked for. minLength 1 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
| item | value |
|---|---|
| rkey | bidder EventRKeys("guest:...") |
| written by | bidder for the guest agent (internal/guestagent/image.go), one per contract |
| read by | requester: requester_guest_image {marker, expected, ok}; a contract with an image releases on a mismatch |
compute.guest.subscribeEvents
com.publicdomainrelay.temp.compute.guest.subscribeEvents subscription
Served by the bidder's GuestControlPlane to a guest holding a workload identity token (in the Authorization header only): streams the requester-authored compute.events.guest.* payloads for that guest's contract, in order, after cursor. Unlike the XRPC event-stream framing, each message is a JSON text frame, an #event object whose $type is com.publicdomainrelay.temp.compute.guest.subscribeEvents#event, and an empty binary frame every 25 s keeps the socket alive. The stream closes with code 1001 once the ComputeVM is gone.
parameters
| parameter | type | description |
|---|---|---|
cursor | integer | The last seq the guest received; entries after it are replayed, then new ones streamed, and the bidder drops the entries up to it. Absent, the stream starts at the oldest entry kept; the guest agent always sends one (0 when it has none). minimum 0 |
message
union #event
errors
| error | description |
|---|---|
FutureCursor | cursor is past the last seq: sent after the upgrade as a JSON text frame {error: FutureCursor, message}, then a close with code 1008; the guest agent starts again from 0. |
InvalidRequest | 400, as HTTP JSON before the upgrade: cursor is not an integer or is negative; the body is {errors: [message]} and carries no error name. |
AuthenticationRequired | 401, as HTTP JSON before the upgrade: no workload identity token. |
UnknownGuest | 404, as HTTP JSON before the upgrade: the token names no guest of this bidder. |
Unavailable | 503, as HTTP JSON before the upgrade: the GuestControlPlane is not ready. |
also: #event
| item | value |
|---|---|
| served by | bidder GuestControlPlane: handleSubscribeEvents in internal/services/guestcontrolplane/subscribe.go, queue internal/guestcp/queue |
| called by | guest agent: internal/guestagent/subscribe.go (bearer = workload identity token) |
| carries | requester-authored compute.events.guest.* payloads, in order; keepalive every 25 s |
| step | S8 |
ingress.webRTC
com.publicdomainrelay.temp.ingress.webRTC record key any
A requester's WebRTC ingress descriptor (listen) or one session of it (offer from the requester, answer from a bidder), named in the ingress[] of the market calls. A listen record names the requester's ingress; offer and answer records carry the SDP for one peer and reference the listen record.
record
| field | type | description |
|---|---|---|
kind * | string | knownValues ["webrtc"] |
mode * | string | knownValues ["listen","offer","answer"] |
id * | string | The requester's ingress id: lowercase hex of the first 16 bytes of sha256("socialweb.computer/ingress/" + the requester repo DID), 32 characters. |
peer | string did | The other party: the target bidder of an offer, the requester of an answer. |
session | string | A per-offer nonce; an answer applies only to the offer with the same id and session. |
descriptor | com.atproto.repo.strongRef | The listen record this offer or answer belongs to. |
sdp | string | |
stunUrls | array of string | The ICE servers (STUN URLs) this side gathers with. |
createdAt * | string datetime |
| item | value |
|---|---|
| rkey | requester listen: webrtc (ingressDescriptor in internal/market/requester/requester.go); offer: TID (createIngressOffer in internal/market/requester/market.go); bidder answer: TID (AnswerIngressRecords in internal/market/bidder/submit.go) |
| written by | requester (listen, offer), bidder (answer) |
| read by | the other side through ingress[] on rfp, bid, accept, receipt, offering and the submit calls; only refs to this NSID are allowed (validateIngressList in internal/atproto/market/records.go) |
| step | S3 to S6 |
compute.secrets.getSecrets
com.publicdomainrelay.temp.compute.secrets.getSecrets query
The requester serves a contract's secrets bundle to its guest, whose setup-secrets.service fetches it at boot and again after a guest.secretsUpdated. The route carries the contract name as one more path segment: GET /xrpc/com.publicdomainrelay.temp.compute.secrets.getSecrets/<contract> on the requester's ingress. The bearer is the guest's workload identity token from its bidder's OIDC issuer (the issuer_uri of the bid's compute.config.wif.simple), with audience api://ATProto?actx=<requester DID> and a wid_sub claim equal to the VM's subject.
output
A JSON array of #entry: the bundle as the requester holds it, less the atirc agent's env file and iroh key until the requester has written them.
errors
| error | description |
|---|---|
AuthenticationRequired | 401: no bearer token. |
InvalidToken | 401: the token is not from the bid's issuer, has another audience, or names another subject. |
NotFound | 404: the requester runs no contract of that name with a secrets bundle. |
NotReady | 503: the requester is starting, or the contract's issuer and subject are not known yet. |
InternalError | 500: any other failure. |
also: #entry
| item | value |
|---|---|
| file | compute/secrets/getSecrets.json; SecretsNSID = com.publicdomainrelay.temp.compute.secrets, SecretsRoute in internal/market/requester/secrets.go |
| type | query-shaped HTTP route: GET /xrpc/com.publicdomainrelay.temp.compute.secrets.getSecrets/<contract> |
| auth | Authorization: Bearer <workload identity token>; audience api://ATProto?actx=<requester DID>; subject claim must match the contract's grant |
| output | JSON array [{path, value, mode?}]; 401 AuthenticationRequired, InvalidToken; 404 NotFound; 503 NotReady; 500 InternalError |
| served by | requester ingress: internal/services/requester/routes.go -> Requester.Secrets |
| called by | guest setup-secrets.service (internal/atproto/cloudinit) |
| step | S8; fallback: guest-events.md |
compute.config.wif.simple
com.publicdomainrelay.temp.compute.config.wif.simple record key any
A bid's workload identity config, written by the bidder next to every market.bid and named by the bid's config strongRef: the OIDC issuer of the guest's tokens and the subject format they carry. Record key: <bid rkey>-config. The requester reads issuer_uri, to trust the guest's token on getSecrets and in its com.fedproxy.rbac roles, and actx; the other fields describe the guest's token exchange as the bidder sets it up.
record
| field | type | description |
|---|---|---|
accept_path * | string | The path in the guest where the bidder writes the accept, /root/secrets/publicdomainrelay.com/market/accept.json. |
issuer_uri * | string | The OIDC issuer of the guest's workload identity tokens: the bidder's guest ingress URL plus /v1/identity/oidc. |
to_issue * | string | The kind of token the guest exchanges for: openbao-identity-oidc (the bidder's OpenBao identity engine). |
actx * | string | The bidder's DID without its method prefix (the last DID segment), the {actx} part of the subject. |
token_path * | string | The path in the guest of its login token, /root/secrets/openbao/token. |
url_path * | string | The path in the guest of the file that holds the bidder's base URL, /root/secrets/digitalocean.com/serviceaccount/base_url. |
url_route * | string | The route under that base URL the guest asks for its token, /v1/identity/oidc/token. |
subject * | string | The template of the token's sub claim, actx:{actx}:plc:{did-plc-key}:role:{role}: the bidder's actx, the requester DID's last segment and the VM's role. |
actx_path | string | A field of the earlier TypeScript bidders' records (a path in the guest holding the actx); the Go bidder writes actx instead and nothing reads this. |
createdAt * | string datetime |
| item | value |
|---|---|
| file | compute/config/wif/simple.json; WIFSimpleNSID in internal/guestidentity/bidconfig.go |
| type | record (bid config) |
| key fields | accept_path, issuer_uri, to_issue (openbao-identity-oidc), actx, token_path, url_path, url_route (/v1/identity/oidc/token), subject (actx:{actx}:plc:{did-plc-key}:role:{role}), createdAt |
| rkey | <bid rkey>-config |
| written by | bidder: writeBidRecord via guests.BidConfig (internal/services/bidder/guests.go, guestidentity.BidConfigFor) |
| read by | requester: resolveBidConfig and prepareWorkloadGrant (internal/market/requester/secrets.go) to build the workload identity grant; bidder at accept time |
| step | S4 |