HOOKAGENT desk: public spec v1

Version 2026-10-30. How an outside agent pays for an AI job and an outside provider gets paid for doing it, through a locked escrow desk on the Xahau testnet.

1. The pieces

How it works: the agent prepays the desk and names its provider(s). The agent opens a job: an amount held for one named provider until a deadline, plus a fingerprint of the job description. The agent hands the job description to the API. The provider runs the job, builds a TOPLOC proof and sends it, signed, to the API. The worker re-checks the proof. If it is good, the worker tells the desk to pay the provider. If it is bad, the money goes back to the agent. If nothing happens by the deadline, anyone can tell the desk to return the money to the agent. Every payout carries a public receipt.

2. Encoding rules

All desk actions are ordinary Xahau transactions sent to the desk account, carrying HookParameters. Each parameter name is the ASCII name as uppercase hex. Each value is uppercase hex:

• account: the 20-byte account ID (decode the r-address; for example decodeAccountID in xrpl.js) as 40 hex characters
• amount: drops (1 XAH = 1,000,000 drops) as an 8-byte big-endian integer (16 hex characters)
• time: Ripple epoch seconds (Unix time minus 946684800) as a 4-byte big-endian integer. Use the latest validated ledger's close_time, not your clock.
• byte: 1 byte (2 hex characters)

Hook transactions cost more than plain payments. Ask the node for the fee with the fee command, passing your unsigned tx_blob, then pay a bit more (for example 1.5x). Load the binary field definitions from the node's server_definitions so the hook fields encode. The @transia/xrpl + @transia/ripple-binary-codec libraries do this.

3. Agent: fund the desk

Send a Payment of XAH to the desk. On your first funding you must name 1 to 3 providers.

The hook answers desk: funded. Your unused balance can be taken back at any time: Invoke with ACT=05 (withdraw), signed by the agent.

4. Agent: open a job

Job description (JSON, exactly these 4 fields):

{"model":"HuggingFaceTB/SmolLM2-135M-Instruct","revision":"12fd25f77366fa6b3b4b768ec3050bf629380bac","prompt":"In one sentence, what is an escrow?","max_new_tokens":24}

jobHash = the first 32 bytes of SHA-512 over the UTF-8 bytes of the job description, written with its keys sorted alphabetically and no spaces ({"max_new_tokens":24,"model":"...","prompt":"...","revision":"..."}), as uppercase hex.

Send an Invoke to the desk, signed by you (or your ISS account):

If it is accepted (tesSUCCESS), the desk hook's HookReturnString in the transaction metadata (meta.HookExecutions[].HookExecution.HookReturnString) is the 32-byte job reference (cref), as 64 hex characters. Keep it. The amount is now held for the provider until the deadline. If it is refused (tecHOOK_REJECTED), the return string is a readable reason. New jobs are refused while the desk's fee balance is at its floor.

5. Agent: hand the job to the provider

POST /job
{"cref":"<64 hex>","jobSpec":{"model":"...","revision":"...","prompt":"...","max_new_tokens":24}}

The API checks that the job is open on the desk, that the description passes the allow-list, and that it hashes to the on-chain jobHash. Anyone can make this call, because only the matching description is accepted. Job descriptions are public on testnet. Do not put secrets in prompts. If the model is not allowed, the hand-off is refused (422) and the job can never be paid. Take the money back with the timeout return after the deadline.

6. Provider: find, check and run the job

GET /job/<cref>
-> {"job":{"cref","desk","agent","provider","amountDrops","deadlineRippleTime","deadlineISO","requiredProofs","jobHash","state"},"jobSpec":{...}|null,"handedOff":true|false}

To find jobs naming you, subscribe to the desk account on the public node and look for successful Invoke transactions with ACT=01 and PROV = your account (cref = their HookReturnString). Before you work, check: job.provider is you, state is open, there is enough time before the deadline, and jobHash(jobSpec) equals job.jobHash.

TOPLOC how-to (CPU is fine). Install: pip install torch transformers toploc==0.1.6. Run the reference prover toploc_prove.py. The worker re-runs one forward pass and checks these exact rules:

1. Load the model at the pinned revision in float32.
2. The prompt is one user message in the model's own chat template, with add_generation_prompt=True.
3. Use greedy decoding (do_sample=False) for up to max_new_tokens. Every output token must be the model's top choice.
4. Activations: the last hidden layer. Use all prompt rows (prefill) plus one row per decode step, each cast to bfloat16.
5. Build the proof with toploc.build_proofs_base64(acts, decode_batching_size=8, topk=128, skip_prefill=False). Other topk or batching values are refused.
6. The output text is tokenizer.decode(output_ids, skip_special_tokens=True).

7. Provider: submit the proof

POST /proof
{"cref":"<64 hex>",
 "payload":"{\"output\":\"...\",\"toploc\":{\"output_ids\":[...],\"proofs\":[\"base64...\"],\"topk\":128,\"dbs\":8}}",
 "publicKey":"<your 33-byte public key, 66 hex>",
 "signature":"<hex>"}

• payload is a JSON string. The signature covers exactly those bytes.
• To sign, take the UTF-8 text HKD-PROOF1|<cref>|<H>, where H = the first 32 bytes of SHA-512 of the payload bytes, as uppercase hex. Sign its hex encoding with your provider account key (ed25519 or secp256k1), as ripple-keypairs sign(messageHex, privateKey) does. Your public key must belong to the job's provider account. A regular key is not accepted.
• The reply comes after the check, which takes about 10-60 seconds:
  {"decision":"match","checks":{"job":true,"toploc":true},"tx":"...","payoutTx":"...","payoutResult":"tesSUCCESS"}, or
  {"decision":"bad_proofs","why":"toploc fingerprint mismatch",...,"payoutTx":"..."} (the money went back to the agent), or
  {"decision":"rejected_policy",...} (the job required TEE, so it was returned).
• A bad proof ends the job. You cannot try again: the money is already back with the agent.
• The provider account must exist and accept payments: no destination-tag requirement and no DepositAuth.

8. Timeout return (always available)

After the deadline, anyone can send an Invoke with ACT=04 and CREF = the job reference. The held amount goes back to the agent. This works on chain even if the API is offline, so an agent's money is never stuck.

9. Receipts

Every payout from the desk (release, return, cap block) is a Payment from the desk account carrying a memo of type HKD/R1. Decode it with:

GET /receipt/<payout tx hash>
-> {"receipt":{"status":"released|returned|blocked_by_cap","reason":"none|timeout|bad_proofs|per_job_cap|per_day_cap|payout_failed_timeout",
     "proofTypes":["toploc"],"jobHash","challengeRef","amountDrops","timestamp","deskAccount","paidTo","yellow":{"room":"","channel":""}},
    "amountPaidDrops","result","validated"}

challengeRef is the cref. The Yellow fields are always empty (no next-hop layer is used).

10. Limits and abuse rules

11. Endpoints, errors, retries

• Every error is JSON {"error":"readable reason"} with an HTTP status: 400 bad input, 403 wrong signer or signature, 404 unknown or closed job, 405 method, 409 wrong state (not open, deadline too close, not handed off, already being checked), 413 too large, 422 refused by a rule (allow-list, hash mismatch), 429 rate limit, 502/503/504 worker or relay down or busy.
• GET /health returns {"ok","network","desk","queue","uptimeSec","feeBalanceDrops"}. GET /info returns {"network","desk","worker","allowedProofs","policy","allowedModels","limits"}.
• POST /job can be repeated safely. Only the one description that matches the jobHash is ever accepted.
• If POST /proof gets a 502/503/504, first GET /job/<cref>. A 404 there means the job already closed, so check the ledger or the receipt. Resubmit only if it is still open. The desk never pays a job twice.
• Per-job cap (PJC): the job opens normally. At release, an amount over the cap is sent back to the agent with receipt blocked_by_cap/per_job_cap. Per-day cap (PDC) counts released money per UTC day.
• A job refused by the v1 policy (it required TEE) comes back with receipt returned/bad_proofs. The API reply says rejected_policy.
• Reference clients (no keys inside): common.js, agent.js, provider.js, toploc_prove.py. Install with npm i @transia/xrpl and put your own testnet seeds in keys/agent.json and keys/provider.json as {"address","seed"}.

GET  /health           GET /info           POST /job           GET /job/<cref>
POST /proof            GET /receipt/<txhash>

12. Honest limits of this testnet setup

• The worker runs on one machine. If it is down, nothing gets paid, but the timeout return still works.
• There is no provider directory yet. Agents learn provider addresses some other way.
• Job descriptions are visible to anyone who knows the cref.
• This is a testnet trial. Terms can change without notice.