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

socialweb.computer/socialweb-computer-kcp

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

1 collaborator
0
0
190 lines · 7.1 KB Raw History

The protocol spec

Record types, the reference graph between them, the path a contract moves through, and the rules that keep a contract honest.

More: Trust & policy, Security & verification, Workload Identity Federation, Gateway. The full reference, with the code behind each rule: protocol/README.md and the glossary.

Record types

All records live in AT Protocol repositories. Cross-record references use com.atproto.repo.strongRef: a {$type, uri, cid} pointer that content-addresses the target.

All market NSIDs carry the com.publicdomainrelay.temp.* prefix (pre-release namespace).

compute.vm: VM specification

Describes the desired machine: cpus, mem, disk, network, a role, cloud-init user_data, and an optional location. kind: deno asks for a Deno sandbox instead of a VM.

cpus: 2
mem: 4G
disk: 40G
network: 500G
role: my-cool-role
user_data: |
  #cloud-config
  runcmd:
    - [sh, -c, "echo hi"]
location: {country: USA, region: west}

market.rfp: RFP envelope

Wraps a strong reference to the VM record: this is what the requester publishes and sends to the bidders it discovered.

domain: compute
payload: {uri: at://did:plc:alice/com.publicdomainrelay.temp.compute.vm/3mm3d, cid: bafyrei...vm}
policies: [{uri: ..., cid: ...}]
submitBid: https://...
signatures: [...]

market.bids.free: free pricing payload

Zero-cost bid: the default, and the only one written today. A reason string and signatures.

reason: free
cost: 0
signatures: [...]

market.bids.x402: pricing payload

Cost (in the currency's smallest unit), currency, frequency, prepay and a settlement URL: the economic terms of a paid bid. Defined in the lexicons; no bidder writes it today.

cost: 100000
currency: USDC
frequency: hourly
prepay: true
url: https://compute-contract.bob.example/receipt

market.bid: bid envelope

Binds a pricing payload to a specific RFP by strong reference; config is the VM's workload identity issuer.

rfp: {uri: ..., cid: ...}
payload: {uri: ..., cid: ...}
config: {uri: ..., cid: ...}
signatures: [...]

market.accept: accept

The requester locks in a chosen bid, referencing both the RFP and the winning bid.

rfp: {uri: ..., cid: ...}
bid: {uri: ..., cid: ...}
submitEvent: https://...
signatures: [...]

market.receipt: receipt

The provider's proof it took the contract: anchors the full contract chain, and its cid binds it to the accept.

rfp: {uri: ..., cid: ...}
bid: {uri: ..., cid: ...}
accept: {uri: ..., cid: ...}
payload: {uri: ..., cid: ...}
cid: bafyrei...binding
signatures: [...]

Record graph

Every envelope points backward by strong reference: follow the arrows from a receipt and you can rebuild the whole contract.

VM     <- RFP                     rfp.payload -> vm
RFP    <- Bid -> bids.free        bid.rfp -> rfp, bid.payload -> bids.free
RFP    <- Accept -> Bid           accept.rfp + accept.bid
Receipt -> RFP + Bid + Accept

Lifecycle

stateentered whennext
RFP openthe requester writes the VM record and the RFPbidding
biddingbidders take the RFP from submitRfp or the relaysaccepted, or no bids
no bidsnobody answereda new RFP after a backoff, until the deadline; then Failed
Failedno bid passes the policy, or the winner is deniedterminal
acceptedthe requester writes the acceptreceipt
receiptthe provider provisions and writes the receiptHeld
Heldthe guest is on the network with its host keysreleased
releasedthe requester writes vm.delete, the provider vm.terminatedterminal

Every branch: protocol/flow.md.

Authority & validation

Rules a provider checks before it provisions, and a requester before it holds:

  • The accept's signature, the accepted bid being the provider's own bid for that RFP, and the accept's author being the RFP's author.
  • The RFP must carry a valid inline network.attested signature by the requester; every bid, accept, receipt and event carries one by its author.
  • A full host refuses the accept (submitAccept answers 409 CapacityExceeded) before any receipt.
  • The receipt's cid must bind to the referenced accept record (VerifyReceipt; a bad one fails the contract ReceiptInvalid).
  • For vm.delete: the event's author must be the accept's author.

Settlement

Free settlement is what runs today: the accept carries no payment and the receipt follows it. The lexicons also define accepts.free, accepts.x402, receipts.free and receipts.x402 for a paid flow; none is written today.

VM lifecycle events

market.event records, submitted with submitEvent, each referencing the receipt it belongs to.

eventpayload NSIDwritten when
vm.hostKeyscom.publicdomainrelay.temp.compute.events.vm.hostKeysthe guest bound its ssh host key
vm.onNetworkcom.publicdomainrelay.temp.compute.events.vm.onNetworkthe guest is on the network (its iroh ticket; per tunnel an https URL or a WebRTC fingerprint)
vm.deletecom.publicdomainrelay.temp.compute.events.vm.deletethe requester is done: accept author only
vm.terminatedcom.publicdomainrelay.temp.compute.events.vm.terminatedthe provider stopped the VM, with a reason
vm.memoryPressure, vm.oomKilledcom.publicdomainrelay.temp.compute.events.vm.*the VM's memory crossed a threshold or was OOM-killed
vm.sandboxcom.publicdomainrelay.temp.compute.events.vm.sandboxa Deno sandbox ended, with its output

Guest events (compute.events.guest.*: keys, sealed WebRTC signals, secrets) ride the same envelope: guest-events.md.

Compute types

The RFP's compute.vm is the one worked through above: a Firecracker VM by default. With kind: deno the same market, bid and receipt records carry a Deno sandbox that runs the user data as its program, on a bidder that opts in (install bidder --compute-kinds vm,deno).

More on the protocol