~ knotless Search/
↑↓ move↵ open⇧↵ all results

socialweb.computer/socialweb-computer-kcp

socialweb.computer: a compute market on atproto (kcp)

1 collaborator
0
0
320 lines · 24.9 KB Raw History
# flow: one compute contract, end to end

- the flow is: Request For Proposal -> Bid -> Accept -> Receipt, then the guest's events, then the release
- the compute contract flow can run purely over the firehose and relays (comms mode `Firehose`: no inbound endpoint); the `market.submit*` calls are the fast path
- every record lives in its author's own repo; the other side reads it with one `getRecord` (from a firehose or Jetstream commit, or from the `market.submit*` call that names it)
- every `market.*` record and every event payload carries badge.blue signatures (`network.attested.signature`: [identity.md](identity.md#networkattested)); they are left out of the records below
- the records below are one real contract, from prod: the requester `aliceoa.bsky.social` requested a 4 vCPU VM from one of `bobvmbuilder.bsky.social`'s bidders on 2026-11-15 (trimmed; `did:plc:lpfuqerea3deuoyrn7ojser4` is alice, `did:plc:2l2wdry77c7jtucbslstagkj` the bidder)
- field by field: [market.md](market.md), [guest-events.md](guest-events.md); who is who: [identity.md](identity.md#actors); every NSID: [glossary.md](glossary.md)
- this page: one real contract with its records; [compute-contract-flow-map.md](compute-contract-flow-map.md): the owner's end-to-end map of every layer and the flow

## The Story

```mermaid
sequenceDiagram
    autonumber
    actor Alice as Alice (requester)
    actor Bob as Bob's bidder (an agent of Bob)

    rect rgb(240, 248, 255)
        Note over Alice,Bob: Request For Proposal (RFP)
        Alice->>Alice: createRecord: policy record (the workflow she runs)
        Alice->>Alice: createRecord: compute.vm<br/>(CPUs, Memory, Disk, cloud-init user_data, ...)
        Alice->>Alice: createRecord: rfp<br/>(strongRef to compute.vm + policy, signed)
        Alice->>Bob: discover (offering + heartbeat), submitRfp
    end

    rect rgb(245, 245, 245)
        Note over Alice,Bob: Bid
        Note over Bob: policy: Bob's workflow + Alice's attached one
        Bob->>Bob: createRecord: compute.config.wif.simple, bids.free (or x402)
        Bob->>Bob: createRecord: bid<br/>(strongRef to RFP + payment terms + config)
        Bob->>Alice: submitBid
    end

    rect rgb(240, 248, 255)
        Note over Alice,Bob: Accept
        Note over Alice: policy on the winner<br/>Payment Settlement Flow (NOP if bids.free)
        Alice->>Alice: createRecord: accept<br/>(strongRef to RFP + Bid)
        Alice->>Bob: submitAccept (re-sent until the receipt)
    end

    rect rgb(245, 245, 255)
        Note over Alice,Bob: Receipt
        Note over Bob: capacity check + reservation, Provision Compute
        Bob->>Bob: createRecord: receipt<br/>(strongRef to RFP + Bid + Accept + compute.vm, cid binds the accept)
        Bob->>Bob: createRecord: compute.events.vm.hostKeys, vm.onNetwork<br/>(address: the guest's iroh ticket)
        Bob->>Bob: createRecord: market.event<br/>(strongRef to the payload + receipt)
        Bob->>Alice: submitEvent
    end

    Note over Alice: Held: connect to the guest over iroh (ssh), webrtc or an https tunnel

    rect rgb(245, 245, 245)
        Note over Alice,Bob: Release
        Alice->>Alice: createRecord: compute.events.vm.delete + market.event
        Alice->>Bob: submitEvent
        Bob->>Bob: createRecord: compute.events.vm.terminated + market.event
        Alice->>Alice: delete her contract records
    end
```

- Alice, Bob and Eve are on the network. Bob runs bidders: hosts with VMs to provide, each its own DID, an agent of Bob's account
- Alice has vouched for Bob and Bob for Alice (`sh.tangled.graph.vouch`); Alice has denounced Eve (a vouch record with `kind: denounce`, which no policy counts)
- Alice writes her Compute Contract Request For Proposal (CCRFP: the `compute.vm` record, the VM-specific payload: cpus, mem, disk, cloud-init `user_data`, ...) and wraps it in a top-level RFP record (`domain: compute`, `payload` a strongRef to the CCRFP). The RFP is the domain-tagged envelope bidders and indexers route on; the CCRFP is the inner VM-specific record
- Bob's and Eve's bidders each issue a Compute Contract Bid (CCB: `market.bid`). Alice's policy engine (`requester-tangled-vouch`) sees she vouched for Bob (his bidder's walk reaches him) and denounced Eve: it allows Bob's bid and denies Eve's
- Alice issues a Compute Contract Bid Accept (CCBA: `market.accept`) against Bob's CCB. With `bids.x402` she would first pay per the CCB's terms; no x402 flow is exercised today (`accepts.*` and `receipts.*` are defined, not written)
- Bob's bidder checks its capacity and issues a Compute Contract Receipt (CCR: `market.receipt`) over the CCRFP, the CCB and the CCBA; it builds to the CCRFP's spec (boots the VM from its `user_data`) and reports the guest's address
- Alice reaches the guest, works, and releases it; both sides record the end

## The Steps

| step | who writes | where | what the other side verifies |
|---|---|---|---|
| [S0](#s0-sign-in) sign in | each party | its OpenBao | - |
| [S1](#s1-trust) trust | operators, users | their repos | vouches and associations, at every policy run |
| [S2](#s2-declare-optional) declare (optional) | the owner's kcp | owner repo | - |
| [S3](#s3-policy-vm-rfp) policy, vm, rfp; discovery; submitRfp | requester | requester repo | RFP signature, RFP author = token issuer, bid window, policies |
| [S4](#s4-bid) bid | bidder | bidder repo | bid author = token issuer, scope policy on each bid |
| [S5](#s5-accept) accept; submitAccept | requester | requester repo | accept signature, accept author = RFP author, policies again, capacity |
| [S6](#s6-receipt) receipt | bidder | bidder repo | receipt signature, `cid` binds the accept |
| [S7](#s7-boot-and-vm-events) boot, vm events | bidder (for the guest) | bidder repo | event author = receipt author, both signatures |
| [S8](#s8-guest-events-secrets-held) guest events, secrets, Held | both | each its own | event author, kind allowed for that side |
| [S9](#s9-release-and-cleanup) release, cleanup | both | each its own | delete author = accept author |

## S0: sign in

- a party is a MarketIdentity: a repo DID and how the app reaches it (`localRepo`, `pdsAccount`, `oauthQr`, `oauthBrowser`, `oauthDelegated`, `oauthSessionProxy`): [identity.md](identity.md#sign-in)
- `socialweb-computer run request --name vm1 --atproto-oauth-qr --exec -- id` signs in with a QR code; the session stays in the requester's own OpenBao

## S1: trust

- vouches: a person vouches another at `sh.tangled.graph.vouch/<subject DID>` in their own repo; both directions are needed for a deal ([policy.md](policy.md#tangled-vouch))
- associations: a bidder is an agent of its operator by the ident.link pair (its DID document's `agent-of`, the operator's `link.ident.endorsement` and `market.association` at rkey = the agent DID); trust walks agent -> principal up to 100 levels ([identity.md](identity.md#associations-identlink))
- the policy modes in code: `tangled-vouch` (the default on both sides), `only-me`, `mutuals`, `open` (only when named, never prod), and the work policies `bid-payload`, `under-4-cpus` ([policy.md](policy.md#bundled-workflows))

## S2: declare (optional)

- an Infra or EphemeralInfra kcp object of the owner mirrors to `computer.socialweb.infra` / `ephemeralInfra` in the owner's repo; each of its contracts is a ComputeContract that runs S3 to S9 ([infra.md](infra.md)). `run request` makes the ComputeContract directly

## S3: policy, vm, rfp

The requester (`internal/market/requester/runner.go` `requestOnce`) checks the size, the token paths and the contract deadline (the `vm-expires-at` label: a deadline in the past sends no RFP), then writes, each with putRecord at a TID:

```yaml
# the policy record: the workflow the requester runs, so the bidder can run it too
uri: at://aliceoa.bsky.social/computer.socialweb.temp.policy.ghalite/3n2de4u2n2c2i
$type: computer.socialweb.temp.policy.ghalite
name: requester-tangled-vouch
perspective: requester
requester: did:plc:lpfuqerea3deuoyrn7ojser4
workflow: "<the bundled workflow, 2448 chars>"
---
# the VM asked for (unsigned; reused by every RFP round of the contract)
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t
$type: com.publicdomainrelay.temp.compute.vm
kind: vm
role: stg-gateway
cpus: 4
mem: 8G
disk: 50G
expiresAt: "2026-11-15T11:00:45.000Z"
user_data: "<cloud-init, 5399 bytes: cloudinit.BuildUserData, with the iroh module>"
---
# the RFP (signed)
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a
$type: com.publicdomainrelay.temp.market.rfp
domain: compute
payload: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t, cid: bafyreiejybdf2t77...}
policies:
  - {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/computer.socialweb.temp.policy.ghalite/3n2de4u2n2c2i, cid: bafyreick65zxk47w...}
submitBid: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:10:46.139Z"
```

`submitBid` here is the requester's did:key ingress (it has no public host: [identity.md](identity.md#didkey-ingress)).

Then discovery ([market.md](market.md#discovery)): every repo with a `market.offering` that the relays list, plus the DIDs its operators vouch for and the agents they endorse; candidates without a fresh heartbeat (300 s) or lacking a capability (`maxCpus`, `nestedVirt`, `images`) are dropped. Never a pinned list.

The requester sends `market.submitRfp {rfpUri, rfpCid}` to each candidate's first endpoint (iroh, webrtc, https), service auth aud `<bidder DID>#pdr_temp_market`, lxm the NSID.

The bidder (`internal/market/bidder/submit.go` `SubmitRFP`) checks the token issuer is the RFP's author and the bid window (10 min from the RFP's TID), answers 200 `{name, phase: Deciding}` or `declined {kind: capacity|unservable, reason}`, or 409 `RFPClosed`. The RFP also reaches it on the relay and Jetstream streams; one sink drops duplicates.

## S4: bid

The bidder (`bids.go` `decideBid`): the window, the RFP's signature, the requester's DID resolves, the payload, guest tools and net, the scope policy, then the full policy (its own workflow and every attached one: all must allow). Then three records at the bid's deterministic rkey (`BidRKey`: one bid per RFP):

```yaml
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bids.free/bid-596cc856db4e8aaf1080-payload
$type: com.publicdomainrelay.temp.market.bids.free
reason: free
cost: 0
# Can also be x402 (not exercised today):
# $type: com.publicdomainrelay.temp.market.bids.x402
# cost: 100000
# currency: USDC
# frequency: hourly
# prepay: true
# url: https://compute-contract.bob.example/receipt
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080
$type: com.publicdomainrelay.temp.market.bid
rfp:     {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
payload: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bids.free/bid-596cc856db4e8aaf1080-payload, cid: bafyreidtjdg5zrwd...}
config:  {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.config.wif.simple/bid-596cc856db4e8aaf1080-config, cid: bafyreig7dqqmi2ky...}
createdAt: "2026-11-15T06:10:53Z"
```

The `config` is the VM's workload identity issuer and subject format ([guest-events.md](guest-events.md#secrets-getsecrets-or-sealed-fallback)). The bidder sends `market.submitBid` to the RFP's `submitBid`.

The requester takes bids from submitBid, the streams, and one getRecord per bidder at `BidRKey` a few seconds after submitRfp. Each is read from the repo of the bid URI's authority (for a submitBid, the service-auth issuer): of a submitBid only `uri` and `cid` are used, the bid is read by them and its bytes must hash to `cid`; the submitRfp answer is never read for a bid. Before a bid is queued its signature must verify with a key of the bidder's DID document or a key its `badgeBlueKeys` record binds, read with `com.atproto.sync.getRecord` and its signed commit checked ([identity.md](identity.md#verifying)); a refused bid is answered 403. The winner's `config` must be in the same repo. Whether the bidder was one the RFP went to is not checked. Its window (`bidWindowSeconds`, 30 s) ends at the first free bid its scope policy allows; else it takes the lowest-cost allowed bid after the window. It runs the full policy on the winner (a deny fails the contract: `policy_rejected`).

## S5: accept

```yaml
uri: at://aliceoa.bsky.social/com.publicdomainrelay.temp.market.accept/ro7pddf4ecfze
$type: com.publicdomainrelay.temp.market.accept
rfp: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
bid: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080, cid: bafyreidpljip3s4e...}
submitEvent: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:11:00.665Z"
```

- rkey `SessionRKey("accept", repo, contract, rfp, bid)`: a restarted requester finds and reuses it
- no payload record today: with x402 the accept would wrap the proof of payment
- `market.submitAccept {acceptUri, acceptCid}` (`accept.go` `submitAcceptAndWait`): re-sent every 0.5 s doubling to 2 s until the receipt is found or `receiptTimeoutSeconds` (5 min) pass
- the bidder (`SubmitAccept`, `vmsize.go`) checks capacity at once: a guest counts its vCPUs and its memory plus the VM overhead; an accept reserves its size for 10 min (per RFP; cut to 1 min once placed and dropped when its ComputeVM exists); a full host answers 409 `CapacityExceeded` before any receipt, else 202 `{id}`
- then, asynchronously (`adapters.go` `acceptContract`): the accept's signature, the scope policy, the bid is its own for that RFP, the accept's author is the RFP's, not expired, the RFP's signature, the full policies again, capacity again

## S6: receipt

```yaml
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.receipt/receipt-fa04c66e2d8effc84a2f6a869217fa11
$type: com.publicdomainrelay.temp.market.receipt
rfp:     {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.rfp/3n2de4uaqaj2a, cid: bafyreiewnv734zjy...}
bid:     {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.bid/bid-596cc856db4e8aaf1080, cid: bafyreidpljip3s4e...}
accept:  {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.market.accept/ro7pddf4ecfze, cid: bafyreickrv6epucq...}
payload: {uri: at://did:plc:lpfuqerea3deuoyrn7ojser4/com.publicdomainrelay.temp.compute.vm/3n2de4twuxb2t, cid: bafyreiejybdf2t77...}
cid: bafyreihoa6m57iajl63umctjn4mke2l4ezbzmbxhclfj5ghrx2uaxklrla
submitEvent: https://did-key-zq3shrcc7qedh4rhor1nwahzrt2anfc9iaxeqfcsrztsl8ype.xrpc.fedproxy.com
createdAt: "2026-11-15T06:11:07.641Z"
```

- rkey `receipt-` + 32 hex of sha256(accept uri LF accept cid) (`market.ReceiptRKey`): the requester finds it with one getRecord in the bidder's repo
- `cid` is the attestation CID of the accept record in the requester's repo; the requester checks the receipt's signature and that binding (`market.VerifyReceipt`); a bad one fails the contract `receipt_invalid`
- no atirc token and no association exist before a verified receipt

## S7: boot and vm events

- placement (`provision.go` `placeAccepted`): a ComputeVM owned by the Bid, then a FirecrackerVM; the VM boots the requester's `user_data` with the bidder's additions (the accept bundle, the network, workload login, `guest-onnetwork.service`, the guest agent and `setup-guest-binaries.service`: `internal/guestseed`)
- the fence is loaded before the tap exists: the guest reaches the internet; TCP to the bidder's host only to the guest control plane at `http://192.0.2.1:<port>` (its `spec.hostPorts`), never TCP to the LAN; DNS; UDP to the LAN for WebRTC by default ([../SYSTEM.md](../SYSTEM.md#fence))
- downloads: the guest image is the bidder's, pinned by sha256 in `internal/versions/versions.json` (`guest-images/<target>/<image.json sha256>` in the bucket); a requester image (`compute.vm.image {url, sha256}`) is fetched and verified by the bidder; guest binaries (opentunnel, wootty, atirc, the guest agent) come from `GET /v1/downloads/<sha256>/<name>` of the guest control plane and are checked against that sha256. One exception in code: when the image's baked dumbpipe is not the pinned version, the iroh module fetches dumbpipe from GitHub with no sha256 check (`internal/atproto/cloudinit/modules.go`, `setup-iroh.sh`)
- the guest logs in with its ssh host key (`sshsig`), which binds the host key to the ComputeVM; `iroh-listener.sh` runs `dumbpipe listen-tcp 127.0.0.1:22` and `send-onnetwork.sh` POSTs `vm.onNetwork` with the iroh ticket to `POST /v1/events`
- the bidder writes each as a payload + `market.event` in its repo at `EventRKeys(<kind>:<receipt>)` and sends `market.submitEvent` to the receipt's `submitEvent`:

```yaml
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.hostKeys/hostkeys-payload-2aac09c4d09c6fa506757931c42eb7f1
$type: com.publicdomainrelay.temp.compute.events.vm.hostKeys
keys: [{type: ssh-ed25519, publicKey: AAAAC3NzaC1lZDI1NTE5AAAAIAnyKwEO5wzWGBi44fIk0IINLHqK21fd1/Q0CVUssM1u, fingerprint: "SHA256:HLs4eIe9xpZuDqOzbJ4V0PMGYUAT0MykBqMj5YdG4UQ"}]
observedAt: "2026-11-15T06:11:17Z"
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.onNetwork/onnetwork-payload-ffcde96d9e9d32d1fc7a38f6a2c46ad5
$type: com.publicdomainrelay.temp.compute.events.vm.onNetwork
address: iroh://endpointaakwnx5yuadc7qofuw3rdurziaeaghixq...
createdAt: "2026-11-15T06:11:19Z"
---
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.event/onnetwork-event-63e463b75b052b3a570a6956e00d9a4d
$type: com.publicdomainrelay.temp.market.event
payload: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.onNetwork/onnetwork-payload-ffcde96d9e9d32d1fc7a38f6a2c46ad5, cid: bafyreicronh3k2gu...}
receipt: {uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.market.receipt/receipt-fa04c66e2d8effc84a2f6a869217fa11, cid: bafyreihpm5lvqqro...}
createdAt: "2026-11-15T06:11:19Z"
```

## S8: guest events, secrets, Held

- guest -> requester: the guest POSTs `{acceptUri, acceptCid, record}` to its bidder (`POST /v1/events`, bearer the workload token); the bidder signs and publishes it (`publicKey`, `signalWebRTC`, `secretsRequested`, `secretsApplied`, `requesterDid`, `r2Released`, `memoryPressure`, `oomKill`, `image`)
- requester -> guest: the requester writes the event in its repo and sends submitEvent to the bidder, which checks the author is the accept's and queues it for the guest's `compute.guest.subscribeEvents` WebSocket (`publicKey`, `signalWebRTC`, `secrets`, `agentStart`, `secretsUpdated`, `r2Start`, `r2Release`)
- secrets: the guest fetches the requester's bundle with `getSecrets` and its workload identity token, over iroh, then WebRTC (the guest agent's `requester.sock`), then https; sealed into a record only when the requester has no inbound endpoint (comms mode Firehose), enables it and the guest asks ([guest-events.md](guest-events.md#secrets-getsecrets-or-sealed-fallback))
- Held (`runGuestAndHold`): the iroh address and the host keys, plus the image marker for an image contract and the secrets fetch when the contract has secrets and the requester an inbound endpoint
- transports, three and no other: iroh (every guest; ssh over `dumbpipe`, `run request ssh`), opentunnel https (per tag), webrtc (per tag; sealed signaling through the bidder) ([../SYSTEM.md](../SYSTEM.md#transports-three-never-add-one)). The ssh gateway (`ssh <handle>@socialweb.computer`) runs the same flow as the user and hops over iroh ([../SYSTEM.md](../SYSTEM.md#ssh-gateway))
- atirc: for `spec.agent` the requester mints a token leased to the receipt and the bidder's `vm.terminated` after the receipt is verified ([outside.md](outside.md#chatatirc))
- a guest requester (R2) in the VM is associated here: [identity.md](identity.md#guest-requester-r2)

## S9: release and cleanup

1. a release request (`spec.releaseRequestedAt`): the guest requester's contracts first (`guest.r2Release`, wait for `guest.r2Released`), then leased atirc tokens are revoked while the lease is alive
2. the requester writes `compute.events.vm.delete {reason: released}` + `market.event` and sends submitEvent, retried until the bidder's `vm.terminated` appears or the release deadline
3. the bidder checks the delete's author is the accept's and the receipt is its own, deletes the ComputeVM, and writes `vm.terminated`:

```yaml
uri: at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.events.vm.terminated/termination-payload-2da9e2aef573b37793d5c43f443186a1
$type: com.publicdomainrelay.temp.compute.events.vm.terminated
reason: deleted_on_request
observedAt: "2026-11-15T06:18:58Z"
```

4. the requester reads it at `EventRKeys(TerminationKey(receipt))` (up to 2 min) and is Released
5. cleanup: the requester deletes the records it wrote for the contract (the rbac grant, the association and endorsement, its delete records, the accept, the RFP, the `compute.vm`, the policy record, its ContractEvents); a guest requester's DIDs are tombstoned (by the guest, else by the requester's rotation key). The bidder keeps its bid, receipt and events
6. reasons a VM ends without a release: `guest_poweroff`, `vmm_exited`, `oom`, `host_reboot`, `identity_mismatch`, `image_refused`, `expired` (past its association's `expiresAt`), `association_ended` ([market.md](market.md#release-and-termination))

The records of this contract are still in alice's repo, and its `vm.terminated` has no `request`: its requester did not run step 5. Why is not visible in the records.

## When It Does Not Go That Way

```mermaid
flowchart TD
  RFP["RFP written, submitRfp to the discovered bidders"] --> D{"bids?"}
  D -->|"every bidder declined unservable, or every candidate lacks a capability"| F1["Failed: no bidder can serve this request"]
  D -->|"none (full, silent, capacity declines)"| W["wait for capacity: delete the RFP, back off 30 s, 1 min, then 2 min"]
  W -->|"before the deadline (vm-expires-at, else 30 min)"| RFP
  W -->|"deadline passed"| F2["Failed: no bids, gave up after N rounds"]
  D -->|"all denied by policy"| F3["Failed: bids_denied"]
  D -->|"a winner"| P{"full policy on the winner"}
  P -->|"deny"| F4["Failed: policy_rejected"]
  P -->|"allow"| A["accept, submitAccept"]
  A -->|"declined (409 CapacityExceeded, any 4xx but 408/425/429)"| X{"replacements left? (3, shared)"}
  X -->|"yes, bids of this RFP left"| RFP2["same RFP: submitRfp again without the refusers"]
  RFP2 --> D
  X -->|"yes, no bids left"| NEW["delete the RFP, a new RFP without the refusers"]
  NEW --> D
  X -->|"no"| F5["Failed"]
  A -->|"no receipt in 5 min"| F6["Failed: no receipt"]
  A -->|"receipt"| V{"VerifyReceipt"}
  V -->|"bad"| F7["Failed: receipt_invalid"]
  V -->|"ok"| G{"guest on network + host keys in 120 s"}
  G -->|"no"| F8["Failed: network_timeout"]
  G -->|"wrong image marker or image_refused"| R["release it, accept another bid (shares the 3)"]
  G -->|"yes"| H["Held"]
```

- the requester keeps a declined accept (a bidder that already acted on it may still need it; the bidder gives up on its own: `bidder_accept_abandoned`)
- a failure before a receipt deletes the RFP, the `compute.vm` and the policy record, and keeps the accept
- sources: `runner.go` `Run`, `replaceDeclined`, `reRFPAfterRefusals`, `waitForCapacity`, `unservableBy`; `accept.go` `acceptDeclined`; `image.go`

## A Real Run

The requester's `contract` lines of one request on a local market (`run request --network`):

```
06:02:32 Requesting requested      step preparing
06:02:32 Requesting rfp_submitted  step creatingRfp
06:02:32 Requesting rfp_submitted  the RFP is submitted; collecting bids
06:02:32 Requesting rfp_submitted  ... requester_no_bidders: no bidder with a market endpoint among 1 candidates
06:03:02 Requesting rfp_submitted  waiting for a default-size slot: round 1, a new RFP in 30s
06:03:32 Requesting rfp_submitted  step creatingRfp
06:03:35 Requesting winner_selected the winner is selected; accepting
06:03:35 Requesting accepted       the accept is submitted; waiting for the receipt
06:03:39 Requesting receipt        the receipt is verified; waiting for the guest
06:03:51 Requesting receipt        the guest reported hostKeys
06:03:54 Requesting network        the guest reported onNetwork
06:03:54 Held       network        held: the guest is on the network
06:03:55 Releasing  network        the destroy is delivered; waiting for the bidder's vm.terminated
06:04:00 Released   released       the bidder ended the contract: deleted_on_request
```

The first round found the network's bidder before its offering named an endpoint; the requester waited for capacity and the second round got the VM.

## See Also

- [README.md](README.md) (the index and the sequence), [market.md](market.md), [guest-events.md](guest-events.md), [identity.md](identity.md), [policy.md](policy.md), [release.md](release.md), [glossary.md](glossary.md)
- the acceptance runbooks: `docs/acceptance/`