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

socialweb.computer/socialweb-computer-kcp

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

1 collaborator
0
0
342 lines · 12.3 KB Raw History

Compute Contracts - Pre-Alpha

<iframe width="100%" height="auto" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/LftvIIfQPtU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

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.simple instance which tells the requester prior to accept what the OIDC issuer will be for the VM and how it's sub (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.
  • --secrets puts 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_data so 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 path must be a clean absolute path and each mode an octal string of at most 0777 (default 0600); 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", payload is 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.