Compute Contracts - Pre-Alpha
- Blog
- Deck: ATproto PDX: 2026-08-04: Compute Contracts
- source
- Fancy version of this content
- Asciinema version of the following video: https://asciinema.org/a/1262425
This is a spec for ATProto accounts to request and advertise (compute) resources.
This spec is for you if you run an organization and want to leverage decentralized identity to allow access to your org's compute (and in the future more) resources to your members and their workloads/agents.
The flow is: Request For Proposal -> Bid -> Accept -> Receipt
[!CAUTION]
This is pre-alpha software and it has yet to have a thorough review!!! Multiple passes of refactors were done and while things work they are just to play with right now! The compute contract flow can be considered proven. However, there is a lot of security pieces involved here and they need to be gone through with a fine toothed comb before Alpha. Please consider re-writing everything using your favorite LLM etc. let's please have many implementations! :D
Quickstart
<!-- README.md#install -->Ephemeral Accounts with association records
A bidder gets a DID of its own and an association record that makes it an agent of your ATProto account once you sign in when prompted (scan the QR code / open the link in the logs). It bids only for requesters you vouch for.
Bid on compute contracts
<!-- README.md#run-a-bidder -->Try a local market
<!-- README.md#try-a-local-market -->BlueSky Accounts via QR Code Session Transfer
Both operators scan the QR codes from their own processes using the did-key-associator webapp at https://qr.fedfork.com.
Request Compute
<!-- README.md#request-a-vm -->Secrets
To send secrets to the VM without putting them in cloud-init (public ATproto
data), just pass a JSON file to --secrets:
For example, if you wanted to send your https://cocore.dev token to a new VM you could do it like so:
# Set ATP_HANDLE and ATP_PASSWORD for goat account login or provide like so:
goat account login -u "aliceoa.bsky.social" -p "aaaa-aaaa-aaaa-aaaa"
TOKEN=$(goat account service-auth \
--lxm dev.cocore.account.createApiKey \
--aud did:web:appview.cocore.dev)
PI_CONFIG=$(curl -sS -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
'https://appview.cocore.dev/xrpc/dev.cocore.account.createApiKey' \
-d '{"name":"my-pi"}' | jq -r '{"apiKey": .secret}')
socialweb-computer run request --name pi \
--secrets <(jq -n \
--arg pi "${PI_CONFIG}" \
--arg provider "cocore" \
--arg model "mlx-community/Ornith-1.0-9B-4bit" \
'[
{
path: "/root/.pi/agent/cocore-config.json",
value: $pi,
},
{
"path": "/root/.pi/agent/settings.json",
"value": {
"defaultProvider": $provider,
"defaultModel": $model
}
}
]') \
--atproto-oauth-qr
Here's a quick jq example of using env var names as arguments instead of
writing each one out (then you'd pass --secrets /tmp/secrets.json):
jq -n --args '[$ARGS.positional[] | {path: ("/root/secrets/" + ascii_downcase), value: env[.]}]' \
SOME_API_KEY OTHER_ENV_VAR > /tmp/secrets.json
Passing secrets this way works by leveraging Workload Identity Federation. We
thereby avoid storing anything sensitive in the public compute.vm record.
-
Each bid's config carries a
com.publicdomainrelay.temp.compute.config.wif.simpleinstance which tells the requester prior to accept what the OIDC issuer will be for the VM and how it'ssub(subject) claim will be formatted.- This means that if a contract fails, aka the VM disappears for whatever reason. We can turn around and accept a different bid from another provider! This loose coupling of Workload Identity Federation configuration information ensures we can even preemptively spin more than one instance of the compute we are requesting for resiliency. The following repo has an in-depth exploitation of how workload identity works: droplet-oidc-poc.
-
--secretsputs the bundle in the requester's own vault (OpenBao), and the requester serves it from its ingress only for the contract.-
It also adds a script to the VM's cloud-init
user_dataso that When the VM starts, it makes a request to the requester using a token retrieved via token-exchange from the bidder/compute-provider's Workload Identity issuer. -
Access to the secrets is then gated by an RBAC policy which ensures that the token the VM passes to the requester belongs to our newly spun VM per the bid config Workload Identity Federation (WIF) record.
-
The request goes over iroh, then WebRTC, then https to the requester's ingress; a sealed record only when the relay is the only channel.
-
Each
pathmust be a clean absolute path and eachmodean octal string of at most0777(default0600); one bad entry refuses the whole bundle. Only missing folders are created, and each file is written as root.
-
Protocol
sequenceDiagram
autonumber
actor Alice
actor Bob
rect rgb(240, 248, 255)
Note over Alice,Bob: Request For Proposal (RFP)
Alice->>Bob: createRecord: compute.vm<br/>(CPUs, Memory, Disk, etc.)
Alice->>Bob: createRecord: rfp<br/>(strongRef to compute.vm)
end
rect rgb(245, 245, 245)
Note over Alice,Bob: Bid
Bob->>Alice: createRecord: bids.free (or x402)<br/>(determine price)
Bob->>Alice: createRecord: bid<br/>(strongRef to RFP + payment type)
end
rect rgb(240, 248, 255)
Note over Alice,Bob: Accept
Note over Alice: Payment Settlement Flow (NOP if bids.free)
Alice->>Bob: createRecord: accept<br/>(strongRef to RFP + Bid + receipt-of-payment)
end
rect rgb(245, 245, 255)
Note over Alice,Bob: Receipt
Note over Bob: Provision Compute
Bob->>Alice: createRecord: receipt<br/>(strongRef to RFP + Bid + Accept)
Bob->>Alice: createRecord: compute.events.vm.onNetwork<br/>(address: iroh ticket)
Bob->>Alice: createRecord: market.event<br/>(strongRef to onNetwork + receipt)
end
Note over Alice: Connect to compute at/via address
- Alice, Bob, and Eve are on the network
- Alice wants to issue a Compute Contract Request For Proposal (CCRFP)
- Alice's CCRFP will state she wants an OpenCode instance
- Bob has plenty of builder machines
- Eve wants to know what Alice is doing
- Alice has vouched for Bob
- Alice has denounced Eve
- Alice creates a CCRFP manifest (the VM-specific payload: cpus, mem, disk,
cloud-init
user_data, ...) - Alice wraps her CCRFP in a top-level RFP record (
domain: "compute",payloadis 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. - Alice makes her RFP/CCRFP pair available to the network
- Bob and Eve each issue a Compute Contract Bid (CCB) against the CCRFP
- Alice's policy engine sees that she's denounced Eve and vouched for Bob
- Alice issues a Compute Contract Bid Accept (CCBA) against Bob's CCB.
- Alice issues a x402 payment to Bob per info provided in his CCB.
- Using the CCBA AT URI and CID to the CCB's stated CCR endpoint.
- Bob issues a Compute Contract Receipt (CCR) over the CCRFP, CCB, and CCBA
- The CCR references the CCRFP, the CCB, and the CCBA.
- Bob builds to the CCRFP manifest's spec
Compute Contract Flow (High level)
The compute contract flow can be executed purely over the firehose/relays.
That's what we'll cover in this section. For more details see the
open-architecture repo's COMPUTE_CONTRACT_FLOW_MAP.md.
All market.* records use https://badge.blue signatures, not shown here for
brevity.
Alice createRecord's the type of compute she wants
$type: com.publicdomainrelay.temp.compute.vm
cpus: 2
mem: 4G
disk: 40G
network: 500G
role: my-cool-role
user_data: |
#cloud-config
runcmd:
- [sh, -c, "echo hello world"]
location:
country: USA
region: west
Alice createRecord's a Request For Proposal (rfp) strongReferencing the
compute she wants.
$type: com.publicdomainrelay.temp.market.rfp
payload:
$type: com.atproto.repo.strongRef
uri: at://did:plc:alice/com.publicdomainrelay.temp.compute.vm/3mm3dolfolz2c
cid: bafyrei...vm
Bob decides what he wants Alice to pay for the compute and createRecord's the payment type for his bid.
$type: com.publicdomainrelay.temp.market.bids.free
reason: free
# Can also do x402 but haven't tested this in a while:
# $type: com.publicdomainrelay.temp.market.bids.x402
# cost: 100000 (0.10 USDC, in the currency's smallest unit)
# currency: USDC
# frequency: hourly
# prepay: true
# url: https://compute-contract.bob.example/receipt
Bob createRecord's a Bid (bid) strongReferencing the compute she
wants.
$type: com.publicdomainrelay.temp.market.bid
rfp:
$type: com.atproto.repo.strongRef
uri: at://did:plc:alice/com.publicdomainrelay.temp.market.rfp/3mm3doliee72s
cid: bafyrei...rfp
payload:
$type: com.atproto.repo.strongRef
uri: at://did:plc:bob/com.publicdomainrelay.temp.market.bids.x402/3mm4...
cid: bafyrei...x402
Alice settles the payment and gets a payment receipt according to settlement
sub-flow. If bids.free, then that's a NOP.
[!NOTE]
Settlement subflow hasn't been tested in a while for x402 and these docs will be updated in the future once we re-test and validate. We're focusing on orgs who want to distribute compute to their members in an ATProto native way for free first.
Alice then createRecord's an Accept (accept) record which wraps her
proof-of-payment receipt (only if not bids.free)
$type: com.publicdomainrelay.temp.market.accept
rfp:
$type: com.atproto.repo.strongRef
uri: at://did:plc:alice/com.publicdomainrelay.temp.market.rfp/3mm3doliee72s
cid: bafyrei...rfp
bid:
$type: com.atproto.repo.strongRef
uri: at://did:plc:bob/com.publicdomainrelay.temp.market.bid/3mm4...
cid: bafyrei...bid
Finally, Bob provisions the compute and issues a Receipt (receipt) when he sees the Accept.
$type: com.publicdomainrelay.temp.market.receipt
rfp:
$type: com.atproto.repo.strongRef
uri: at://did:plc:alice/com.publicdomainrelay.temp.market.rfp/3mm3doliee72s
cid: bafyrei...rfp
bid:
$type: com.atproto.repo.strongRef
uri: at://did:plc:bob/com.publicdomainrelay.temp.market.bid/3mm4...
cid: bafyrei...bid
accept:
$type: com.atproto.repo.strongRef
uri: at://did:plc:alice/com.publicdomainrelay.temp.market.accept/3mlagijgoeb23
cid: bafyrei...accept
cid: bafyrei...attestation
Alice then awaits the onNetwork event
$type: com.publicdomainrelay.temp.compute.events.vm.onNetwork
kind: iroh
address: <the VM's iroh ticket>
$type: com.publicdomainrelay.temp.market.event
payload:
cid: bafyreihp5j7tc6xbj4yqnzanwjsqfqasazqr6cbdthuwni3xdrgy2ymmeq
uri: at://did:plc:5svqtrhheairglgiiyvutzik/com.publicdomainrelay.temp.compute.events.vm.onNetwork/3mqqgq57oss26
$type: com.atproto.repo.strongRef
receipt:
cid: bafyreicpqkmnigboxueqaa2y6lvn7b5qjaiw46jb6mqgymlahpl3v5fal4
uri: at://did:plc:5svqtrhheairglgiiyvutzik/com.publicdomainrelay.temp.market.receipt/3mqqgpxvfls26
$type: com.atproto.repo.strongRef
Docs
<!-- README.md#docs -->The protocol, record by record: overview, one contract step by step, identity, market, policy, guest events, releases, glossary. Every record and XRPC method, generated from the lexicons: lexicon and XRPC reference.