@1money/protocol-ts-sdk 2.1.0 → 2.1.1

package/skills/1money-protocol-sdk/references/api-reference.md

@@ -0,0 +1,188 @@
+# API reference — read endpoints & response shapes
+
+Every method below returns the SDK promise wrapper (see
+`client-and-errors.md`). The value handed to `.success(cb)` / resolved by
+`await` is the **decoded response body directly** — the shapes shown here are
+exactly what you get.
+
+All addresses, hashes, and large numbers are hex/decimal **strings**. `U256`
+amounts are decimal strings (base units); `B256`/address values are `0x…` hex.
+
+## Table of contents
+- [Client construction](#client-construction)
+- [chain](#chain)
+- [accounts](#accounts)
+- [tokens (read)](#tokens-read)
+- [transactions (read)](#transactions-read)
+- [checkpoints](#checkpoints)
+- [Write endpoints (index)](#write-endpoints-index)
+- [Constants](#constants)
+
+## Client construction
+
+```typescript
+import { api } from '@1money/protocol-ts-sdk';
+
+const client = api(options?: {
+  network?: 'testnet' | 'mainnet' | 'local'; // default 'mainnet'
+  timeout?: number;                           // ms, default 10000
+});
+// → { accounts, checkpoints, tokens, transactions, chain }
+```
+
+Base URLs by network: mainnet `https://api.1money.network`, testnet
+`https://api.testnet.1money.network`, local `http://localhost:18555`.
+
+## chain
+
+```typescript
+client.chain.getChainId() // → { chain_id: number }
+```
+
+## accounts
+
+```typescript
+client.accounts.getNonce(address: string)
+// → { nonce: number }                  next nonce to use for this sender
+
+client.accounts.getBbNonce(address: string)
+// → { bbnonce: number }
+
+client.accounts.getTokenAccount(address: string, token: string)
+// → { balance: string /* U256 base units */, nonce: number }
+```
+
+`getTokenAccount` is how you read a wallet's balance of a specific token. To
+compute the associated token-account address offline, use `deriveTokenAddress`
+(see `client-and-errors.md` → Utilities).
+
+## tokens (read)
+
+```typescript
+client.tokens.getTokenMetadata(token: string) // → MintInfo
+```
+
+`MintInfo` (token-wide config and authorities):
+
+```typescript
+interface MintInfo {
+  symbol: string;
+  master_authority: string;
+  master_mint_burn_authority: string;
+  mint_burn_authorities: { minter: string; allowance: string }[];
+  pause_authorities: string[];
+  list_authorities: string[];
+  black_list: string[];
+  white_list: string[];
+  metadata_update_authorities: string[];
+  bridge_mint_authorities: string[];
+  supply: string;          // U256 base units
+  decimals: number;
+  is_paused: boolean;
+  is_private: boolean;
+  clawback_enabled: boolean;
+  meta: {
+    name: string;
+    uri: string;
+    additional_metadata: { key: string; value: string }[];
+  };
+}
+```
+
+## transactions (read)
+
+```typescript
+client.transactions.getByHash(hash: string)          // → Transaction
+client.transactions.getReceiptByHash(hash: string)   // → TransactionReceipt
+client.transactions.getFinalizedByHash(hash: string) // → FinalizedTransactionReceipt
+client.transactions.estimateFee(from, to, value, token) // → { fee: string }
+```
+
+`estimateFee(from: string, to: string, value: string, token: string)` — note the
+argument order is **from, to, value, token** (value before to in the URL, but the
+function signature is from/to/value/token).
+
+`TransactionReceipt`:
+
+```typescript
+interface TransactionReceipt {
+  success: boolean;            // did the tx succeed on-chain
+  transaction_hash: string;
+  fee_used: number;
+  from: string;
+  checkpoint_hash?: string;
+  checkpoint_number?: number;
+  to?: string;
+  token_address?: string;
+}
+// FinalizedTransactionReceipt extends it with:
+//   epoch: number; counter_signatures: { r; s; v }[]
+```
+
+`Transaction` is a **discriminated union** keyed by `transaction_type`
+(`'TokenCreate' | 'TokenTransfer' | 'TokenMint' | 'TokenGrantAuthority' |
+'TokenRevokeAuthority' | 'TokenBlacklistAccount' | 'TokenWhitelistAccount' |
+'TokenBridgeAndMint' | 'TokenBurn' | 'TokenBurnAndBridge' | 'TokenClawback' |
+'TokenCloseAccount' | 'TokenPause' | 'TokenUnpause' | 'TokenUpdateMetadata' |
+'Raw'`). All variants share `hash`, `chain_id`, `from`, `nonce`, `signature`,
+plus optional `checkpoint_*`/`transaction_index` and an optional `memo` (present
+only for V2/memo-bearing txs); each carries a `data` object specific to its type.
+Narrow on `transaction_type` before reading `data`.
+
+## checkpoints
+
+(1Money's term for blocks.)
+
+```typescript
+client.checkpoints.getNumber()                    // → { number: number }
+client.checkpoints.getByHash(hash, full = false)  // → Checkpoint
+client.checkpoints.getByNumber(number, full = false) // number: number | string → Checkpoint
+client.checkpoints.getReceiptsByNumber(number: number | string) // → TransactionReceipt[]
+```
+
+`full` controls whether `transactions` comes back as full `Transaction[]`
+(`true`) or just an array of hashes (`false`, default).
+
+```typescript
+interface Checkpoint {
+  hash: string; parent_hash: string;
+  state_root: string; transactions_root: string; receipts_root: string;
+  number: number; timestamp: number;
+  size?: number;
+  transactions: Transaction[] | string[]; // hashes unless full=true
+}
+```
+
+## Write endpoints (index)
+
+These take a **signed payload** built via `TransactionBuilder` — see
+`transactions.md`. Listed here only so you pick the right one.
+
+```typescript
+client.transactions.payment(payload)        // → { hash }
+client.tokens.issueToken(payload)           // → { hash, token }
+client.tokens.mintToken(payload)            // → { hash }
+client.tokens.burnToken(payload)            // → { hash }
+client.tokens.grantAuthority(payload)       // → { hash }
+client.tokens.manageBlacklist(payload)      // → { hash }
+client.tokens.manageWhitelist(payload)      // → { hash }
+client.tokens.pauseToken(payload)           // → { hash }
+client.tokens.updateMetadata(payload)       // → { hash }
+client.tokens.bridgeAndMint(payload)        // → { hash }
+client.tokens.burnAndBridge(payload)        // → { hash }
+client.tokens.clawbackToken(payload)        // → { hash }
+```
+
+## Constants
+
+The chain ids are defined internally as `CHAIN_IDS` (mainnet `21210`, testnet
+`1212101`, local `1212101`) but are **not re-exported** from any public entry
+point (`.`, `/api`, `/client`, `/utils`). Don't try to import them — fetch the
+live value at runtime:
+
+```typescript
+const { chain_id } = await client.chain.getChainId();
+```
+
+If you genuinely need a hardcoded id for an offline/test path, define your own
+constant rather than relying on an unexported one.

package/skills/1money-protocol-sdk/references/client-and-errors.md

@@ -0,0 +1,176 @@
+# Client, error handling, config & utilities
+
+## The promise wrapper in depth
+
+Every API method returns an object that is **both** a `Promise` and a builder of
+handler chains. You consume it one of two ways.
+
+### Await style
+
+```typescript
+try {
+  const res = await client.accounts.getNonce(addr); // resolves with the body
+  console.log(res.nonce);
+} catch (err) {
+  // err is a ParsedError (see below) — thrown only when NO error handler chained
+}
+```
+
+### Chain style
+
+```typescript
+client.accounts.getNonce(addr)
+  .success(res => res.nonce)   // res is the decoded body, not wrapped
+  .timeout(err => { /* fired specifically on configured timeout */ })
+  .error(err => { /* any other error */ });
+```
+
+Handlers and what they fire on:
+
+| Handler | Fires when |
+| --- | --- |
+| `.success(cb)` | request succeeded (HTTP 200 by `api()`'s rule) |
+| `.failure(cb)` | a 2xx response that fails the success rule (rare — see note) |
+| `.error(cb)` | network error, non-2xx HTTP status, or a throw in another handler |
+| `.timeout(cb)` | the configured `timeout` elapsed (request is aborted) |
+| `.login(cb)` | auth-required responses (HTTP 401 / `code === 401`) |
+| `.rest(cb, scope?)` | catch-all for whichever cases you didn't handle |
+
+> `api()` sets the success rule to `status === 200`. Since axios rejects non-2xx
+> responses by default, most server-side failures (4xx/5xx) arrive at `.error`,
+> not `.failure`. `.failure` only fires for a resolved response that isn't 200
+> and isn't a login — uncommon in practice. For consumer code, handling
+> `.success` + `.error` (or `try/catch`) covers the real cases.
+
+Important behavioral notes:
+
+- **Return value of the chain.** Awaiting with no handlers returns the raw body
+  (e.g. `await client.chain.getChainId()` → `{ chain_id }`) — this is the cleanest
+  idiom for the common case. Attaching `.success(cb)` instead makes the awaited
+  value equal to `cb`'s return, which is useful when you want to transform or map
+  the body inline.
+- **Errors resolve vs. throw.** If you attach `.error()` (or `.rest()` covering
+  errors), the awaited chain **resolves** with the handler's return instead of
+  throwing. With no error handler, `await` **throws**. Don't half-mix: either
+  handle errors in the chain, or `try/catch` the await — not an awkward both.
+- **`.rest(cb, scope)`** lets you target a subset, e.g. handle only timeout +
+  error with one callback: `.rest(cb, ['timeout', 'error'])`. An empty scope, or
+  a scope whose cases were all already handled, warns and never fires.
+
+### ParsedError shape
+
+```typescript
+interface ParsedError<T extends string = string> {
+  name: T;          // underlying error name (see timeout caveat below)
+  message: string;
+  stack: string;
+  status: number;   // HTTP status, or 500 if none
+  data?: any;       // server error body when present
+}
+```
+
+> **Timeout discriminator caveat.** A timeout is typed `ParsedError<'timeout'>`,
+> but that `'timeout'` is only the *type-level* tag — at runtime the object is a
+> plain `Error('timeout')`, so `name === 'Error'` and **`message === 'timeout'`**.
+> To detect a timeout in a `catch`, check `err.message === 'timeout'` (or just use
+> the `.timeout()` handler), **not** `err.name === 'timeout'`.
+
+## Configuration & custom headers
+
+`api()` sets base URL, timeout, and the success rule globally. To add headers
+(auth tokens, API keys) or override the base URL, use `setInitConfig` — headers
+merge with the SDK's defaults rather than replacing them:
+
+```typescript
+// Import from the /client subpath — setInitConfig is NOT a named export of the
+// package root (the README's root import is inaccurate). The default `client`
+// object from the root also carries it as `client.setInitConfig(...)`.
+import { setInitConfig } from '@1money/protocol-ts-sdk/client';
+
+setInitConfig({
+  headers: { Authorization: 'Bearer <token>', 'X-API-Key': '<key>' },
+  // optional:
+  baseURL: 'https://api.custom-domain.com',
+  timeout: 10000,
+});
+```
+
+> Config is **global/singleton** — it applies to all module references obtained
+> from `api()`. Call `setInitConfig` once at startup (after `api()`), not
+> per-request. There is no per-call header argument in the public methods.
+
+## Timeouts & cancellation
+
+Default timeout is 10s; override per client via `api({ timeout })` or globally
+via `setInitConfig({ timeout })`. On timeout the request is **aborted** (via
+`AbortController`) and `.timeout()` fires (or the awaited call throws a
+`ParsedError<'timeout'>` if unhandled — runtime `message === 'timeout'`, see the
+caveat under ParsedError shape).
+
+The high-level module methods (`accounts.getNonce`, `transactions.payment`, …)
+do **not** accept a per-call options/`signal` argument — they use fixed request
+options internally. Caller-supplied cancellation is only available through the
+low-level `get`/`post` exports from `@1money/protocol-ts-sdk/client`, which do
+accept an options object with a `signal`; that signal is merged with the SDK's
+internal timeout abort signal.
+
+## Utilities
+
+Imported from the package root (`@1money/protocol-ts-sdk`).
+
+### deriveTokenAddress(walletAddress, mintAddress)
+Compute a wallet's associated token-account address offline (keccak-based
+derivation) — no network call.
+
+```typescript
+import { deriveTokenAddress } from '@1money/protocol-ts-sdk';
+const tokenAccount = deriveTokenAddress(
+  '0xA634dfba8c7550550817898bC4820cD10888Aac5', // wallet
+  '0x8E9d1b45293e30EF38564582979195DD16A16E13', // mint
+); // → '0x…'
+```
+
+### toHex(value)
+Convert booleans, numbers/bigints, integer strings, byte arrays, or arbitrary
+values to a `0x…` hex string.
+
+```typescript
+import { toHex } from '@1money/protocol-ts-sdk';
+toHex(true);  // '0x1'  (minimal hex, not zero-padded — README's '0x01' is wrong)
+toHex(123);   // '0x7b'
+toHex('hello'); // '0x68656c6c6f'
+```
+
+### calcTxHash(payload, signature)
+Compute a transaction hash from a raw payload array + `{ r, s, v }`. Rarely
+needed directly — prefer `SignedTx.txHash` from the builder flow, which is
+computed for you. Use `calcTxHash` only for low-level/verification work.
+
+### validateMemo / MemoValidationError / Memo
+For attaching a memo to a transaction (see `transactions.md` → Memo). `Memo` is
+`{ type?, format?, data? }`. The builders call `validateMemo` for you when a memo
+is present; call it yourself to pre-validate user input. It throws
+`MemoValidationError` (with a `.code`) on oversize or illegal-character subfields.
+
+```typescript
+import { validateMemo, MemoValidationError } from '@1money/protocol-ts-sdk';
+try {
+  validateMemo({ type: 'invoice', data: userInput });
+} catch (e) {
+  if (e instanceof MemoValidationError) console.error(e.code, e.message);
+}
+```
+
+### Deprecated: signMessage / encodePayload
+`signMessage(payload, privateKey)` and `encodePayload(payload)` are legacy
+`@deprecated` helpers retained for backward compatibility. **Do not use them for
+new code** — `TransactionBuilder` + `createPrivateKeySigner` (see
+`transactions.md`) is the supported, validated, malleability-safe path.
+
+## Security checklist
+
+- Load private keys from environment/secret managers; never hardcode or commit
+  them. Example value strings in docs are placeholders.
+- Use `testnet` (or `local`) while developing; switch the network deliberately.
+- Keep peer deps (`axios`, `viem`, `@ethereumjs/rlp`) within the package's
+  declared ranges; mismatches can break signing/encoding subtly.

package/skills/1money-protocol-sdk/references/transactions.md

@@ -0,0 +1,325 @@
+# Building, signing & submitting transactions
+
+Every write follows the same pipeline. Internalize this shape; the rest is just
+filling in builder-specific fields.
+
+```typescript
+import { api, TransactionBuilder, createPrivateKeySigner } from '@1money/protocol-ts-sdk';
+
+const client = api({ network: 'testnet' });
+
+// 1. Inputs every tx needs. Awaiting directly returns the body; it throws on
+//    error (or attach .success/.error handlers — see client-and-errors.md).
+const { chain_id } = await client.chain.getChainId();
+const { nonce } = await client.accounts.getNonce(sender);
+
+// 2. Build (validates fields, RLP-encodes, prepares the digest).
+const prepared = TransactionBuilder.<type>({ chain_id, nonce, /* ...fields */ });
+
+// 3. Sign → request body → submit to the matching endpoint.
+const signed = await prepared.sign(createPrivateKeySigner(privateKey));
+const res = await client.<module>.<method>(signed.toRequest());
+```
+
+## What the objects give you
+
+`TransactionBuilder.<type>(...)` returns a **PreparedTx**:
+- `prepared.signatureHash` — the 32-byte digest a signer must sign.
+- `prepared.rlpBytes`, `prepared.unsigned`, `prepared.kind`.
+- `await prepared.sign(signer)` → **SignedTx**.
+- `prepared.attachSignature(signature)` → **SignedTx** (when you signed the
+  `signatureHash` elsewhere and just want to attach r/s/v).
+
+`SignedTx`:
+- `signed.toRequest()` — the request body (unsigned fields + `signature`) you
+  pass to the submit method.
+- `signed.txHash` — the on-chain transaction hash (available before submit).
+- `signed.signature` (`{ r, s, v }`), `signed.signatureHash`, `signed.unsigned`.
+
+`createPrivateKeySigner(privateKey: \`0x${string}\`)` produces a `SignerAdapter`
+that signs with low-S (required — high-S signatures are rejected on attach).
+
+## Builder ↔ endpoint map
+
+| `TransactionBuilder.…` | Submit `client.…` | Returns |
+| --- | --- | --- |
+| `payment` | `transactions.payment` | `{ hash }` |
+| `tokenIssue` | `tokens.issueToken` | `{ hash, token }` |
+| `tokenMint` | `tokens.mintToken` | `{ hash }` |
+| `tokenBurn` | `tokens.burnToken` | `{ hash }` |
+| `tokenAuthority` | `tokens.grantAuthority` | `{ hash }` |
+| `tokenManageList` | `tokens.manageBlacklist` / `tokens.manageWhitelist` | `{ hash }` |
+| `tokenPause` | `tokens.pauseToken` | `{ hash }` |
+| `tokenMetadata` | `tokens.updateMetadata` | `{ hash }` |
+| `tokenBridgeAndMint` | `tokens.bridgeAndMint` | `{ hash }` |
+| `tokenBurnAndBridge` | `tokens.burnAndBridge` | `{ hash }` |
+| `tokenClawback` | `tokens.clawbackToken` | `{ hash }` |
+
+## Builder fields
+
+All builders take `chain_id: number` and `nonce: number`. Fields below are the
+*additional* ones. `value`/amount fields are **decimal strings in base units**.
+Addresses are EIP-55 `0x…` strings.
+
+**Every builder also accepts an optional `memo?: Memo`** (see [Memo](#memo-optional--v1-vs-v2-envelope) below). Omit it for the common case; the fields listed per builder are the required ones.
+
+### payment → transactions.payment
+```typescript
+{ recipient: string; value: string; token: string }
+```
+
+### tokenIssue → tokens.issueToken
+```typescript
+{
+  symbol: string;
+  name: string;
+  decimals: number;
+  master_authority: string;
+  is_private: boolean;
+  clawback_enabled?: boolean; // default true
+}
+// response includes the new token's address: { hash, token }
+```
+
+### tokenMint → tokens.mintToken
+```typescript
+{ recipient: string; value: string; token: string }
+```
+
+### tokenBurn → tokens.burnToken
+```typescript
+{ value: string; token: string }
+```
+
+### tokenAuthority → tokens.grantAuthority
+```typescript
+import { AuthorityAction, AuthorityType } from '@1money/protocol-ts-sdk/api';
+{
+  action: AuthorityAction;        // Grant | Revoke
+  authority_type: AuthorityType;  // see enum below
+  authority_address: string;
+  token: string;
+  value?: string;                 // e.g. mint/burn allowance
+}
+```
+
+### tokenManageList → tokens.manageBlacklist / tokens.manageWhitelist
+```typescript
+import { ManageListAction } from '@1money/protocol-ts-sdk/api';
+{ action: ManageListAction; address: string; token: string } // Add | Remove
+```
+Build once, then submit to `manageBlacklist` *or* `manageWhitelist` — the payload
+shape is identical; the endpoint decides which list.
+
+### tokenPause → tokens.pauseToken
+```typescript
+import { PauseAction } from '@1money/protocol-ts-sdk/api';
+{ action: PauseAction; token: string } // Pause | Unpause
+```
+
+### tokenMetadata → tokens.updateMetadata
+```typescript
+{
+  name: string;
+  uri: string;
+  token: string;
+  additional_metadata: { key: string; value: string }[];
+}
+```
+
+### tokenBridgeAndMint → tokens.bridgeAndMint
+```typescript
+{
+  recipient: string;
+  value: string;
+  token: string;
+  source_chain_id: number;
+  source_tx_hash: string;
+  bridge_metadata: string;
+}
+```
+
+### tokenBurnAndBridge → tokens.burnAndBridge
+```typescript
+{
+  sender: string;
+  value: string;
+  token: string;
+  destination_chain_id: number;
+  destination_address: string;
+  escrow_fee: string;
+  bridge_metadata: string;
+  bridge_param: string; // bytes as 0x… hex ('0x' for empty)
+}
+```
+
+### tokenClawback → tokens.clawbackToken
+```typescript
+{ token: string; from: string; recipient: string; value: string }
+```
+
+## Memo (optional — V1 vs V2 envelope)
+
+Any builder accepts an optional `memo` to attach a structured note. `Memo` is
+imported from the package root (or `/utils`); all three subfields are optional:
+
+```typescript
+import type { Memo } from '@1money/protocol-ts-sdk';
+
+const prepared = TransactionBuilder.payment({
+  chain_id, nonce, recipient, value, token,
+  memo: { type: 'invoice', format: 'text', data: 'order-12345' }, // all subfields optional
+});
+```
+
+What it changes — this is **not cosmetic**:
+
+- **Absent memo (`undefined`/`null`) → V1 path.** RLP bytes are byte-identical to
+  the pre-memo SDK; `prepared.kind` is e.g. `'payment'`.
+- **Present memo (even `{}` with empty subfields) → V2 envelope.** The builder
+  RLP-encodes `[innerList, [type, format, data]]`, `prepared.kind` becomes
+  `'<kind>_v2'`, and the **signature hash and tx hash live in a different domain**
+  — a V1 and a V2 tx with otherwise identical fields produce different hashes.
+  So passing `memo: {}` is a meaningful choice, not a no-op.
+
+Validation runs at build time (mirrors the server's Rust rules) and throws
+`MemoValidationError` (carries a `.code`) on violation:
+
+| Field | Cap | Allowed chars |
+| --- | --- | --- |
+| `type` | 128 bytes (UTF-8) | URL-safe (RFC 3986 unreserved + gen/sub-delims + `%`) |
+| `format` | 64 bytes (UTF-8) | URL-safe (same set) |
+| `data` | 256 bytes (UTF-8) | any non-control: rejects NUL, C0/C1 controls, surrogates |
+
+Error codes: `MEMO_TYPE_TOO_LONG`, `MEMO_TYPE_INVALID_CHARS`,
+`MEMO_FORMAT_TOO_LONG`, `MEMO_FORMAT_INVALID_CHARS`, `MEMO_DATA_TOO_LONG`,
+`MEMO_DATA_CONTROL_CHARS`, `MEMO_TOO_LARGE`. On the read side, the `Transaction`
+union carries `memo?` back (populated only for V2 transactions); the receipt
+types do not include it.
+
+## Enums (import from `@1money/protocol-ts-sdk/api`)
+
+```typescript
+enum AuthorityType {
+  MasterMint     = 'MasterMintBurn',
+  MintBurnTokens = 'MintBurnTokens',
+  Pause          = 'Pause',
+  ManageList     = 'ManageList',
+  UpdateMetadata = 'UpdateMetadata',
+  Bridge         = 'Bridge',
+  Clawback       = 'Clawback',
+}
+enum AuthorityAction  { Grant = 'Grant', Revoke = 'Revoke' }
+enum ManageListAction { Add = 'Add', Remove = 'Remove' }
+enum PauseAction      { Pause = 'Pause', Unpause = 'Unpause' }
+```
+
+## Worked example: issue a token, then read its address
+
+```typescript
+import { api, TransactionBuilder, createPrivateKeySigner } from '@1money/protocol-ts-sdk';
+
+const client = api({ network: 'testnet' });
+const master = '0x9E1E9688A44D058fF181Ed64ddFAFbBE5CC74ff3';
+const privateKey = process.env.ONE_MONEY_PRIVATE_KEY as `0x${string}`;
+
+const { chain_id } = await client.chain.getChainId();
+const { nonce } = await client.accounts.getNonce(master);
+
+const prepared = TransactionBuilder.tokenIssue({
+  chain_id, nonce,
+  symbol: 'MTK', name: 'My Token', decimals: 18,
+  master_authority: master,
+  is_private: true,
+  clawback_enabled: true,
+});
+
+const signed = await prepared.sign(createPrivateKeySigner(privateKey));
+const { hash, token } = await client.tokens.issueToken(signed.toRequest());
+console.log('issued token', token, 'in tx', hash);
+```
+
+## Custom signer (wallet / HSM / no raw key in process)
+
+When the private key lives in a browser wallet, KMS, or HSM, implement the
+`SignerAdapter` interface instead of `createPrivateKeySigner`. You only need to
+sign `prepared.signatureHash` and return `{ r, s, v }` (low-S):
+
+```typescript
+import type { SignerAdapter, Signature } from '@1money/protocol-ts-sdk';
+
+const walletSigner: SignerAdapter = {
+  async signDigest(digest): Promise<Signature> {
+    // digest === prepared.signatureHash, a 0x-prefixed 32-byte hex string.
+    // Produce a low-S secp256k1 signature however your key custody allows.
+    return { r: '0x…', s: '0x…', v: 0 };
+  },
+};
+
+const signed = await prepared.sign(walletSigner);
+// or, if you already have the signature object:
+const signed2 = prepared.attachSignature({ r: '0x…', s: '0x…', v: 0 });
+```
+
+`v` may be `number` (recovery id, e.g. `0`/`1`) or `boolean`. `attachSignature`
+throws on high-S signatures (malleability guard), so ensure your signer enforces
+low-S.
+
+## Alternate path: EIP-712 typed-data payment
+
+Besides the RLP `TransactionBuilder` flow above, the SDK exports a **separate
+EIP-712 typed-data path for payments** (root-level export, via the signing
+layer). Use it when the signer is a browser wallet doing
+`eth_signTypedData_v4` and you submit on-chain calldata to a `submitTypedData`
+contract entrypoint — *not* the REST `transactions.payment` endpoint. Today only
+payment is implemented.
+
+```typescript
+import { preparePaymentTypedTx, parseSig } from '@1money/protocol-ts-sdk';
+
+const prepared = preparePaymentTypedTx({
+  chain_id, nonce, recipient, value, token,
+  memo: { data: 'note' }, // optional, same Memo rules
+});
+
+// 1. Hand prepared.typedData to the wallet for eth_signTypedData_v4.
+const sigHex = await wallet.request({
+  method: 'eth_signTypedData_v4',
+  params: [account, JSON.stringify(prepared.typedData)],
+});
+
+// 2. Parse the 65-byte sig (normalizes v to 27/28) and build the calldata.
+const tx = prepared.encodeCalldata(parseSig(sigHex));
+// → { to, data, value: 0n, gas, gasPrice, type: 'legacy' } — send via your wallet.
+```
+
+`encodeCalldata` requires `v ∈ {27, 28}` (recovery ids `0`/`1` are normalized by
+`parseSig`). The EIP-712 domain is `{ name: '1Money Network', version: '1',
+chainId, verifyingContract: 0xff…fe }`; `buildPaymentEip712TypedData` is exported
+if you need the typed data without the calldata helper. This path is independent
+of the `api()` REST client.
+
+## Verifying the result
+
+After submit you get a `{ hash }` (and `{ token }` for issue). Confirm it landed:
+
+```typescript
+const receipt = await client.transactions.getReceiptByHash(hash);
+console.log(receipt.success ? 'confirmed' : 'failed', 'fee:', receipt.fee_used);
+```
+
+Receipts may not be available immediately — poll `getReceiptByHash` (or
+`getFinalizedByHash` for finality) with a short backoff rather than a single
+call.
+
+## Common mistakes
+
+- **Wrong builder/endpoint pairing** — e.g. building `tokenMint` but calling
+  `tokens.issueToken`. Use the map above.
+- **Numeric amounts** — `value: 1` or `value: 1.5` is wrong; use a base-unit
+  string like `'1000000000000000000'`.
+- **Stale nonce across multiple txs** — re-fetch or locally increment `nonce`
+  between sequential sends from the same sender.
+- **Forgetting `.toRequest()`** — you submit the SignedTx's request body, not the
+  PreparedTx or the SignedTx object itself.
+- **Reaching for `signMessage`/`encodePayload`** — deprecated; use the builder.