# Signing spec

Every state-changing request is authorized by an **ed25519 signature over canonical UTF-8 bytes**. The desk verifies each signature against the public key named in the message, so it never needs, holds or sees a secret key. This spec matches the desk engine 0.5.0 (`intent.ts`, `requests.ts`) and the desk runtime 0.4.0 (`client.ts`, seat registration) byte-for-byte. The signed bytes are unchanged since prop-desk 0.4.0, and the same vectors verify on both. The test vectors below are generated by that code.

## Keys and encodings

- **Key type:** ed25519 (RFC 8032, pure, no prehash). A Solana keypair is an ed25519 keypair, so an agent's Solana wallet key is its agent key.
- **Public key (`agentKey`, `builderWallet`, `signer`):** base58 (Bitcoin alphabet `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`) of exactly 32 bytes, in **canonical** form: decoding and re-encoding must give the same string, so leading `1`s must match leading zero bytes.
- **Signature:** base58 of exactly 64 bytes, also canonical.
- **Secret key forms the SDK accepts:** a 32-byte seed, or a 64-byte `seed || publicKey` in Solana layout, given as bytes, base58, or the JSON byte array of a Solana CLI keypair file. Secrets are used in-process only.

## Message layout

```
bytes = UTF-8( PREFIX ":" DOMAIN "\n" BODY )
```

| message | PREFIX | BODY | signer |
| --- | --- | --- | --- |
| Trade intent | `machine.prop-desk.intent.v2` | sorted-key JSON of the intent | `intent.agentKey` |
| Checkout | `machine.prop-desk.checkout.v1` | sorted-key JSON of the checkout | `checkout.agentKey` |
| Payout request | `machine.prop-desk.payout.v1` | sorted-key JSON of the request | `request.signer` (agent key or builder wallet) |
| Seat registration | `machine.prop-desk.seat.v1` | `{"agentKey":"…","builderWallet":"…"}`, exactly this key order | `agentKey` |

`DOMAIN` is the desk's signing domain, the `domain` field of `GET /v1/desk`. The paper desk uses `syndicate-paper`. The engine's default live domain is `syndicate`, but a live desk announces its own.

### Domain separation

- **Across message types:** each type has its own prefix, and the intent prefix is versioned (`v2`, so no v1 intent signature can verify). A signed checkout can never be replayed as an intent or a payout.
- **Across desks:** the domain is inside the signed bytes, so a paper signature is invalid on a live desk and the other way round. The test vectors include the same intent under both domains.
- **Rule for agents:** read `domain` from the desk you are talking to (or pin it in config) and sign with exactly that string. A wrong domain shows up as `SIGNATURE_INVALID`.

### Sorted-key JSON

The body is a flat JSON object with:

1. Only the schema's keys. An unknown key is rejected (`SCHEMA_INVALID`). An optional key that is absent (or `undefined`) is **omitted**, never written as `null`.
2. Keys sorted in ascending code-unit order. All keys are ASCII, so this is plain byte order.
3. No whitespace: `{"k":v,"k2":v2}`.
4. Values written with ECMAScript `JSON.stringify`: strings with standard escaping (the allowed characters never need escapes), `true` or `false`, and numbers as below.

### Numbers

- A number is written as ECMAScript `String(n)`, the shortest decimal that round-trips to the same IEEE-754 double: `2000`, `2.5`, `0.30000000000000004`, `61234.5`.
- **Exponent forms are refused.** `String(n)` uses an exponent for magnitudes below 1e-6 or at 1e21 and above (`1e-7`, `1e21`), and such a value is rejected with `SCHEMA_INVALID`. Every accepted number is a plain decimal that any language can reproduce.
- Integers never carry a fraction: write `2000`, not `2000.0`.
- The integer fields `expiresAt` and `sizeUsd` must be safe integers (|n| <= 2^53 - 1).

In a language other than JavaScript, render a double `x` like this: take the shortest round-trip digits (Python `repr(x)`, Go `strconv.FormatFloat(x, 'g', -1, 64)`, Rust `format!("{}", x)`), then print them as a plain decimal with no exponent and no trailing `.0`. Refuse `|x| < 1e-6` and `|x| >= 1e21`. Python:

```python
from decimal import Decimal
def js_number(x: float) -> str:
    if x != x or x in (float("inf"), float("-inf")) or (x != 0 and abs(x) < 1e-6) or abs(x) >= 1e21:
        raise ValueError("desk refuses exponent-form numbers")
    if x == int(x):
        return str(int(x))
    text = format(Decimal(repr(x)), "f")          # repr = shortest round-trip digits
    return text.rstrip("0").rstrip(".") if "." in text else text
```

## Schemas

### Trade intent (`version: 2`)

| field | type | rule |
| --- | --- | --- |
| `version` | number | `2` |
| `agentKey` | string | canonical base58, 32 bytes |
| `accountId` | string | `^acct_[0-9a-f]{20}$`, owned by `agentKey` |
| `nonce` | string | `^[A-Za-z0-9_-]{1,64}$`, unique per agent key (see below) |
| `expiresAt` | integer | Unix ms; `now < expiresAt <= now + 120000` on the desk clock |
| `action` | string | `open` or `close` |
| `coin` | string | `^[A-Z0-9]{1,16}$`; tradable: `BTC`, `ETH`, `SOL`, `HYPE` |
| `side` | string | `long` or `short`: the direction opened, or the direction of the position being closed |
| `notionalUsd` | number | open only; 0 < n <= 1e12, plain decimal |
| `leverage` | number | open only; 0 < n <= 1e12; must be at or below the product cap |
| `stopPrice` | number | open only; **required**; 0 < n <= 1e12 |
| `takeProfit` | number | open only; optional; 0 < n <= 1e12 |
| `closeFraction` | number | close only; 0 < n <= 1 |

An open cannot carry `closeFraction`, and a close cannot carry open fields.

Canonical example (vector `intent/open-sol-long`):

```
machine.prop-desk.intent.v2:syndicate-paper
{"accountId":"acct_…","action":"open","agentKey":"F52k…","coin":"SOL","expiresAt":1790000000000,"leverage":2,"nonce":"open-1","notionalUsd":2000,"side":"long","stopPrice":95,"version":2}
```

**Intent id:** `sha256(canonical bytes)` as lowercase hex. The desk returns it as `intentId` and it keys the order journal.

### Checkout (`version: 1`)

| field | rule |
| --- | --- |
| `version` | `1` |
| `agentKey` | canonical base58, 32 bytes; must be registered (`POST /v1/seats`) |
| `product` | `turbo`, `pro` or `classic` |
| `sizeUsd` | positive safe integer, one of `accountSizesUsd` |
| `upgrade90` | boolean |
| `payWith` | `SOL`, `USDC` or `TOKEN` |
| `nonce` | `^[A-Za-z0-9_-]{1,64}$` |
| `expiresAt` | integer Unix ms within 120 s |

**Account id:** `"acct_" + hex(sha256(UTF-8("machine.prop-desk.account.v1:" + DOMAIN + "\n" + agentKey + ":" + checkoutNonce)))[0:20]`. It is deterministic and public, so the agent knows its account id before the desk answers. The SDK checks the desk's answer against it (`ACCOUNT_ID_MISMATCH`).

### Payout request (`version: 1`)

| field | rule |
| --- | --- |
| `version` | `1` |
| `accountId` | `^acct_[0-9a-f]{20}$` |
| `requestId` | `^[A-Za-z0-9_-]{1,64}$`; the payout's idempotency key, single-use forever |
| `signer` | canonical base58, 32 bytes: the account's agent key or its builder wallet |
| `expiresAt` | integer Unix ms within 120 s |

### Seat registration

The body is `JSON.stringify({agentKey, builderWallet})`, with `agentKey` first. There is no version field and no expiry: the registration is a standing proof that the agent key chose this payout wallet. It is idempotent for the same wallet and refused for a different one (`AGENT_WALLET_MISMATCH`).

## Envelopes (HTTP bodies)

| endpoint | body |
| --- | --- |
| `POST /v1/seats` | `{"agentKey", "builderWallet", "signature"}` |
| `POST /v1/accounts` | `{"checkout": {…}, "signature"}` |
| `POST /v1/accounts/:id/intents` or `POST /v1/intents` | `{"intent": {…}, "signature"}` |
| `POST /v1/accounts/:id/payouts` | `{"request": {…}, "signature"}` |

The JSON key order inside an envelope does not matter: the desk canonicalizes before it verifies.

## Nonces, expiry and replay

- **Expiry window:** a message is valid while `now < expiresAt <= now + maxTtlMs`, where `maxTtlMs` is 120000 (`GET /v1/desk` -> `rules.intentMaxTtlMs`). Use 30-60 s. If you get `EXPIRED` or `EXPIRY_TOO_FAR`, check your clock against the desk's.
- **Intent nonces:** the desk keeps `agentKey:nonce` for every admitted intent until that intent expires, and rejects a second use as `REPLAYED`. The guard clock is monotonic, so stepping the clock back cannot revive a nonce. Always generate a fresh nonce per intent; the SDK uses `<ms base36>-<16 random hex>`.
- **When a nonce is spent:** a nonce is consumed once an intent passes admission (schema, signature, expiry, replay), even if risk or the venue then rejects it. Those rejections carry a non-null `intentId`. Admission failures (`intentId: null`) do not consume the nonce.
- **Checkout nonces** are permanent: they define the account id. Re-posting the same signed checkout (same terms) is idempotent. Reusing a nonce with different terms is refused.
- **Payout `requestId`s** are single-use forever on each account. The desk keeps them in account state, so they survive snapshots and compaction. The same signed request inside its window returns `REQUEST_REPLAYED`; any later reuse returns `REQUEST_ID_REUSED`.

## Test vectors

The file `skill/syndicate-prop/resources/test-vectors.json` holds 11 vectors: seat on 2 domains, 2 checkouts, 5 intents (including decimals, float noise, a close, and a live-domain twin) and 2 payouts, one signed by the agent and one by the builder.

Each vector gives the signer seed (hex), the public key, the envelope as POSTed, `canonicalUtf8`, `canonicalSha256`, the base58 `signature`, and the `intentId` or `accountId` where relevant. ed25519 is deterministic, so any correct implementation reproduces every signature exactly. The vectors are generated by the desk code (`skill/scripts/gen-vectors.ts`), and `skill/tests/signing-vectors.test.ts` checks that:

- the SDK reproduces every vector;
- both the vendored engine and the reference build accept every vector and reject it on the other domain;
- 300 random SDK-signed messages verify, with byte-identical canonical bytes;
- tampering with any field breaks verification;
- the SDK's schema validation matches the desk's accept/reject decision and code.

The vector keys are **public test keys** (seed = `sha256("syndicate-skill public test key: <label>")`). Never fund or use them.
