Docs / 06

Opening a case

A case is one request to POST /api/cases with a target and a payment. The app does all of it for you; this page describes what happens underneath, so you can follow it or call it yourself.

A case, left to right. Steps 1 to 4 happen in one request; 5 in your browser; 6 at the next batch.

1. The target

Any address on Robinhood Chain: 0x followed by 40 hexadecimal characters. The server reads its bytecode and asks the Pons V2 factory whether it launched it, then files it under one of four kinds:

pons-token: a token the Pons V2 factory launched (its getLaunchedToken record exists).
token: any other contract that answers symbol().
contract: any other contract.
wallet: no code, or an EIP-7702 delegation.

2. The payment

A first request without payment returns 402 Payment Required with the x402 terms: scheme exact, network eip155:4663, asset USDG (0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals), the amount (0.25 USDG) and payTo, the case vault 0x42E3d46E08D5D2EEC80E85c6a7798dAE31Bc3C25.

Your wallet signs an EIP-3009 TransferWithAuthorization under the EIP-712 domain Global Dollar, version 1, chain 4663, verifying contract USDG. The second request carries it, base64-encoded, in the X-PAYMENT header:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:4663",
  "payload": {
    "signature": "0x…",
    "authorization": {
      "from": "0xYourWallet", "to": "0x42E3…3C25",
      "value": "250000", "validAfter": "…", "validBefore": "…",
      "nonce": "0x<32 random bytes>"
    }
  }
}

The server checks the signature, the amount, the time window, that the nonce is unused and that the wallet holds the USDG, then runs the case. The transfer is settled by the protocol's clerk (0x75342A0730180d60188F106a2b3e6b5DBdC81212) only after the file exists, so a case that fails moves no money, and the paying wallet needs no ETH for gas. The settlement transaction comes back in the X-PAYMENT-RESPONSE header.

Once $FIXMYBAGS exists, a burn replaces the USDG: send the case price in $FIXMYBAGS to 0x000000000000000000000000000000000000dEaD, then send the request with an X-BURN header carrying { "tx": "0x<burn tx>", "signature": "0x…" }, where the signature is the burning wallet's personal_sign of the message FixMyBags burn claim 0x<burn tx>. The signature stops anyone who sees your burn from claiming it first. Each burn log opens one case; see $FIXMYBAGS.

3. The detectives

The detectives that know the target's kind run one after another and add findings to a shared file. A full case on a busy Pons V2 token reads a few hundred logs and about six hundred blocks and takes around a minute. The detectives lists what each one reads.

A sealed envelope pushed through the letter slot of a front door

4. The file comes back

The response body is the case file in plain JSON, sent once over TLS:

{
  "caseId": "0x<32 bytes>",
  "file": { …the case file… },
  "fileHash": "0x<sha256 of the canonical file>",
  "sealToken": "…"
}

At that moment the server queues the file's leaf for anchoring and forgets the file. It keeps the case id and the hash, nothing else from the file.

5. The seal

Your browser makes a fresh 256-bit key, encrypts the file with AES-256-GCM and uploads only the ciphertext with PUT /api/cases/<caseId>/seal, body { "iv": "<base64>", "ct": "<base64>" }, header x-seal-token. The private link is /case/<caseId>#k=<key>: the part after # never reaches a server. The app also keeps the key in your browser's local storage under pe:files. Lose both and nobody can read the file again, us included.

6. The anchor

Every fifteen minutes the clerk gathers queued leaves, sealed and public alike, into one Merkle tree and posts its root to the CaseRegistry contract. A batch goes out as soon as a sealed leaf has waited ten minutes, and at least every three hours for the public ones. Your case page then shows the batch, the transaction and the proof. Anchoring and the registry has the details.

Reading and opening

GET /api/cases/<caseId> returns what the server holds for a case: the ciphertext, the anchor and its proof, and the plaintext only if the file was opened. To publish a sealed file, POST /api/cases/<caseId>/open with { "file": { … } }: the server recomputes the hash, checks it against the anchored leaf, puts the file on the board and the clerk records the opening on-chain.

Mandates

The detectives