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

package/AGENTS.md

@@ -1,28 +1,115 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-Core TypeScript sources live in `src/`, with domain folders for `api/`, `client/`, and shared `utils/`. Entry points such as `src/index.ts` stitch those modules together, while accompanying specs sit in sibling `__test__` directories (`src/api/tokens/__test__/index.test.ts`, etc.). Compiled artifacts are emitted to `es/` (ESM), `lib/` (CJS), and `umd/` for CDN usage, so never edit those outputs directly. Reference assets reside in `public/`, examples in `examples/`, and longer-form docs in `docs/`. Build behavior is centralized in `omni.config.js`, bundling tweaks in `rollup.config.js`, and TypeScript settings in `tsconfig.json`.
-
-## Build, Test & Development Commands
-Use your preferred package manager, but stay consistent per branch.
-```bash
-pnpm install            # or npm install – install dev + peer tooling
-npm run build           # omni build -> emits es/lib/umd bundles
-npm run build:remote    # same build with RUN_ENV=remote for hosted targets
-npm test                # nyc + mocha using .mocharc.js
-npm run lint            # prettier check + eslint (ts/tsx)
-npm run lint:fix        # applies prettier/eslint autofixes
-```
-Run linting before opening a PR; CI expects clean output directories.
-
-## Coding Style & Naming Conventions
-The repo enforces `.editorconfig` (LF, UTF-8, two-space indents) and `prettier.config.js` (tabWidth 2, printWidth 50, single quotes, arrowParens `avoid`, trailing commas `none`). ESLint runs with `@typescript-eslint` rules over `src/**`. Prefer descriptive module exports (`api/checkpoints`, `client/rpc`) and keep test files named `*.test.ts`. Public APIs should expose camelCase functions, PascalCase classes, and never leak internal helper names.
-
-## Testing Guidelines
-All specs use Mocha + Chai and live beside their subjects (`__test__/`). Structure tests as `describe('<module>')` blocks with explicit success/error cases that mirror the SDK’s `.success/.timeout/.error` flow. Execute `npm test` locally; NYC writes reports to `.nyc_output/` and enforces the existing coverage baselines, so add scenarios rather than loosening thresholds. When adding a module, stub network calls and favor deterministic fixtures.
-
-## Commit & Pull Request Guidelines
-Commitlint extends the conventional config with allowed types such as `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, plus the project tag `[1MONEY-PROTOCOL-TS-SDK]`. Format messages as `type(scope): summary`, e.g., `feat(api): add token metadata endpoint`. Before pushing, run `npm run lint && npm test` and ensure generated bundles are excluded from diffs. PRs should describe the change, list validation commands, link related issues, and include API or screenshot evidence when touching user-facing behavior.
-
-## Security & Configuration Tips
-Never commit `.env` values; tests should rely on mocked data or public endpoints. When debugging against live protocol nodes, set `RUN_ENV=remote` only in your shell and prefer the `testnet` client configuration shown in `README.md`. Audit dependencies before enabling new wallets or transports, and keep peer versions (`axios`, `viem`, `@ethereumjs/rlp`) aligned with the ranges declared in `package.json`.
+# AGENTS.md
+
+This file provides guidance to CODE AGENT when working with code in this repository.
+
+## Keeping Docs & Skills in Sync (required)
+
+**Any code change that adds or alters public behavior MUST update the docs and the
+`skills/1money-protocol-sdk` skill in the same change.** The skill is what teaches
+agents to consume the SDK correctly — stale skill content produces wrong code.
+
+Update the matching file(s) when you touch:
+
+| Code change | Update |
+| --- | --- |
+| Read endpoint added/changed (`src/api/**`) | `skills/1money-protocol-sdk/references/api-reference.md` |
+| Transaction builder or signing changed (`src/signing/**`) | `skills/1money-protocol-sdk/references/transactions.md` |
+| Client/promise-wrapper, error, config, network, or utils (`src/client/**`, `src/utils/**`) | `skills/1money-protocol-sdk/references/client-and-errors.md` |
+| New/removed public export or import subpath (`src/index.ts`, `/api`, `/client`, `/utils`) | `skills/1money-protocol-sdk/SKILL.md` (the import map + builder→endpoint table) |
+| Commands, architecture, or conventions | this `AGENTS.md` (and the module `README.md`) |
+
+Checklist before opening a PR: function signatures, the builder→endpoint table in
+`SKILL.md`, enum values, and code examples still match the source. Also update the
+affected module `README.md` and `src/__integration__/QUICKSTART.md` if the public
+flow changed.
+
+## Development Commands
+
+### Building
+- `npm run build` - Build the project using omni build tool (generates lib/, es/, and umd/ directories)
+- `npm run build:remote` - Build for remote deployment with RUN_ENV=remote
+
+### Testing
+- `npm test` - Run unit tests (nyc + Mocha, config `.mocharc.js`)
+- `npm run test:integration` - Run integration tests against a live network
+  (`.mocharc.integration.js`, requires `RUN_INTEGRATION_TESTS=true`)
+- `npm run test:integration:testnet` / `:local` - Pin the integration network
+- `npm run test:all` - Unit + integration
+- Unit tests live in `src/**/__test__/*.ts`; integration suite in `src/__integration__/`
+  (see its `QUICKSTART.md`)
+- TS is loaded via `mocha.tsx.js` (tsx CJS transform) + `tsconfig-paths/register`;
+  `.mocharc.js` disables Node 22 strip-types so tsx resolves paths correctly
+
+### Linting & Code Quality
+- `npm run lint` - Run both Prettier and ESLint checks
+- `npm run lint:fix` - Auto-fix Prettier and ESLint issues
+- `npm run lint:es` - ESLint TypeScript files in src/
+- `npm run lint:prettier` - Check Prettier formatting
+- Individual fix commands: `lint:es_fix`, `lint:prettier_fix`
+
+### Development Workflow
+- `npm run new` - Generate new components using omni CLI
+- `npm run release` - Release package using omni tool
+
+## Project Architecture
+
+This is a TypeScript SDK for the 1Money Network Protocol with a modular architecture:
+
+### Core Structure
+- **src/index.ts** - Main entry point, exports api client and utilities
+- **src/api/** - API client modules for different endpoints (accounts, tokens, transactions, checkpoints, chain)
+- **src/client/** - Core HTTP client with promise wrapper system
+- **src/signing/** - Transaction signing: EIP-712 (`eip712/`), payload `builders/`, `signer.ts`, `core.ts`
+- **src/utils/** - Helpers: address derivation, tx hashing, `encode.ts`, `memo/`
+
+### Key Architecture Patterns
+
+#### API Client Pattern
+The main `api()` function creates a configured client that returns typed API modules. It supports:
+- Network selection (mainnet/testnet/local) with automatic base URL switching
+- Configurable timeouts
+- Modular API endpoints (accounts, tokens, transactions, checkpoints, chain)
+
+#### Promise Wrapper System
+Uses a custom promise wrapper in `src/client/core.ts` that provides:
+- `.success()`, `.error()`, `.timeout()`, `.rest()` handlers
+- Support for both traditional promise chains and async/await
+- Structured error handling with typed responses
+
+#### Module Organization
+Each API module (accounts, tokens, etc.) has:
+- `index.ts` - API methods
+- `types.ts` - TypeScript interfaces
+- `__test__/index.test.ts` - Unit tests
+- `README.md` - Module documentation
+
+### Build System
+- Uses **omni-door CLI** for build orchestration
+- **Rollup** for bundling with multiple output formats:
+  - CommonJS (`lib/`)
+  - ES Modules (`es/`)
+  - UMD bundle (`umd/1money-protocol-ts-sdk.min.js`)
+- **tsc-alias** for path alias resolution
+- External dependencies: axios, viem, @ethereumjs/rlp (peer dependencies)
+
+### TypeScript Configuration
+- Target: ESNext with strict mode enabled
+- Path aliases: `@/*` maps to `src/*`
+- Generates declaration files (.d.ts)
+- Excludes test files from compilation
+
+### Testing Strategy
+- Uses Mocha with nyc for coverage
+- Tests located alongside source files in `__test__/` directories
+- Supports both TypeScript and JavaScript test files
+- 60-second timeout for async operations
+
+## Code Style & Commits
+
+- Prettier (`prettier.config.js`): 2-space, **printWidth 50**, single quotes,
+  no trailing commas, `arrowParens: avoid`, semicolons on.
+- ESLint (`@typescript-eslint`) over `src/`.
+- Commits follow conventional format `type(scope): summary`; allowed types are in
+  `commitlint.config.js` (`feat`, `fix`, `chore`, `optimize`, `[1MONEY-PROTOCOL-TS-SDK]`, …).
+- Husky hooks run automatically: `pre-commit` → lint-staged, `commit-msg` → `npm run lint:commit`,
+  plus a `pre-push` check. Don't bypass them.

package/CLAUDE.md

@@ -1,77 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-### Building
-- `npm run build` - Build the project using omni build tool (generates lib/, es/, and umd/ directories)
-- `npm run build:remote` - Build for remote deployment with RUN_ENV=remote
-
-### Testing
-- `npm test` - Run all tests using Mocha with nyc coverage
-- Tests are located in `src/**/__test__/*.ts` files
-- Uses Mocha with TypeScript support via tsx loader
-
-### Linting & Code Quality
-- `npm run lint` - Run both Prettier and ESLint checks
-- `npm run lint:fix` - Auto-fix Prettier and ESLint issues
-- `npm run lint:es` - ESLint TypeScript files in src/
-- `npm run lint:prettier` - Check Prettier formatting
-- Individual fix commands: `lint:es_fix`, `lint:prettier_fix`
-
-### Development Workflow
-- `npm run new` - Generate new components using omni CLI
-- `npm run release` - Release package using omni tool
-
-## Project Architecture
-
-This is a TypeScript SDK for the 1Money Network Protocol with a modular architecture:
-
-### Core Structure
-- **src/index.ts** - Main entry point, exports api client and utilities
-- **src/api/** - API client modules for different endpoints (accounts, tokens, transactions, checkpoints, chain)
-- **src/client/** - Core HTTP client with promise wrapper system
-- **src/utils/** - Utility functions for signing, address derivation, transaction hashing
-
-### Key Architecture Patterns
-
-#### API Client Pattern
-The main `api()` function creates a configured client that returns typed API modules. It supports:
-- Network selection (mainnet/testnet/local) with automatic base URL switching
-- Configurable timeouts
-- Modular API endpoints (accounts, tokens, transactions, checkpoints, chain)
-
-#### Promise Wrapper System
-Uses a custom promise wrapper in `src/client/core.ts` that provides:
-- `.success()`, `.error()`, `.timeout()`, `.rest()` handlers
-- Support for both traditional promise chains and async/await
-- Structured error handling with typed responses
-
-#### Module Organization
-Each API module (accounts, tokens, etc.) has:
-- `index.ts` - API methods
-- `types.ts` - TypeScript interfaces
-- `__test__/index.test.ts` - Unit tests
-- `README.md` - Module documentation
-
-### Build System
-- Uses **omni-door CLI** for build orchestration
-- **Rollup** for bundling with multiple output formats:
-  - CommonJS (`lib/`)
-  - ES Modules (`es/`)
-  - UMD bundle (`umd/1money-protocol-ts-sdk.min.js`)
-- **tsc-alias** for path alias resolution
-- External dependencies: axios, viem, @ethereumjs/rlp (peer dependencies)
-
-### TypeScript Configuration
-- Target: ESNext with strict mode enabled
-- Path aliases: `@/*` maps to `src/*`
-- Generates declaration files (.d.ts)
-- Excludes test files from compilation
-
-### Testing Strategy
-- Uses Mocha with nyc for coverage
-- Tests located alongside source files in `__test__/` directories
-- Supports both TypeScript and JavaScript test files
-- 60-second timeout for async operations
+@AGENTS.md

package/es/api/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const TESTNET_API_URL = "https://api.testnet.1money.network";
-export declare const MAINNET_API_URL = "https://api.1money.network";
+export declare const MAINNET_API_URL = "https://api.mainnet.1money.network";
 export declare const LOCAL_API_URL = "http://localhost:18555";
 export declare const CHAIN_IDS: {
     readonly MAINNET: 21210;

package/es/api/index.js

@@ -355,7 +355,7 @@ function setInitConfig(config) {
 }
 client.axios;// Base URLs for the API
 const TESTNET_API_URL = 'https://api.testnet.1money.network';
-const MAINNET_API_URL = 'https://api.1money.network';
+const MAINNET_API_URL = 'https://api.mainnet.1money.network';
 const LOCAL_API_URL = 'http://localhost:18555';
 // API version
 const API_VERSION = 'v1';const API_PREFIX$4 = `/${API_VERSION}/accounts`;

package/es/index.js

@@ -1424,7 +1424,7 @@ var client$1 = {
     axiosStatic
 };// Base URLs for the API
 const TESTNET_API_URL = 'https://api.testnet.1money.network';
-const MAINNET_API_URL = 'https://api.1money.network';
+const MAINNET_API_URL = 'https://api.mainnet.1money.network';
 const LOCAL_API_URL = 'http://localhost:18555';
 // API version
 const API_VERSION = 'v1';const API_PREFIX$4 = `/${API_VERSION}/accounts`;

package/lib/api/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const TESTNET_API_URL = "https://api.testnet.1money.network";
-export declare const MAINNET_API_URL = "https://api.1money.network";
+export declare const MAINNET_API_URL = "https://api.mainnet.1money.network";
 export declare const LOCAL_API_URL = "http://localhost:18555";
 export declare const CHAIN_IDS: {
     readonly MAINNET: 21210;

package/lib/api/index.js

@@ -478,7 +478,7 @@ function setInitConfig(config) {
 }
 client.axios;// Base URLs for the API
 var TESTNET_API_URL = 'https://api.testnet.1money.network';
-var MAINNET_API_URL = 'https://api.1money.network';
+var MAINNET_API_URL = 'https://api.mainnet.1money.network';
 var LOCAL_API_URL = 'http://localhost:18555';
 // API version
 var API_VERSION = 'v1';var API_PREFIX$4 = "/".concat(API_VERSION, "/accounts");

package/lib/index.js

@@ -1546,7 +1546,7 @@ var client$1 = {
     axiosStatic: axiosStatic
 };// Base URLs for the API
 var TESTNET_API_URL = 'https://api.testnet.1money.network';
-var MAINNET_API_URL = 'https://api.1money.network';
+var MAINNET_API_URL = 'https://api.mainnet.1money.network';
 var LOCAL_API_URL = 'http://localhost:18555';
 // API version
 var API_VERSION = 'v1';var API_PREFIX$4 = "/".concat(API_VERSION, "/accounts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1money/protocol-ts-sdk",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "ts sdk for 1Money protocol network",
   "main": "lib/index.js",
   "module": "es/index.js",

package/skills/1money-protocol-sdk/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: 1money-protocol-sdk
+description: >-
+  Use when writing or reviewing code that consumes the @1money/protocol-ts-sdk
+  package to talk to the 1Money Network blockchain. Covers initializing the
+  api() client, the .success()/.error()/.timeout()/.rest() promise-wrapper
+  pattern, and the build → sign → submit flow for transactions (payments, token
+  issue/mint/burn, authority grants, blacklist/whitelist, pause, metadata,
+  bridge, clawback) via TransactionBuilder + createPrivateKeySigner. Trigger
+  whenever the user mentions 1Money / 1money / "protocol-ts-sdk", or asks to
+  issue/mint/burn/transfer a token, query a nonce/balance/checkpoint/chain id,
+  estimate a fee, sign or submit a 1Money transaction, or handle the SDK's
+  promise/error pattern — even if they don't name the package. Do NOT use for
+  generic EVM/ethers/viem work unrelated to 1Money, or for the 1Money UI
+  component / React hooks / Figma skills (different domains).
+---
+
+# Using the @1money/protocol-ts-sdk
+
+This skill makes Claude correct and idiomatic when building apps on top of
+`@1money/protocol-ts-sdk` — the TypeScript SDK for the **1Money Network**
+blockchain. The SDK does three things, and almost every task is one of them:
+
+1. **Read chain state** — query nonces, balances, token metadata, checkpoints,
+   chain id, transactions, fee estimates. (`api()` client, GET methods.)
+2. **Write transactions** — build an unsigned tx, sign it, submit it. This is a
+   strict three-step pipeline; getting the steps or their order wrong is the
+   most common failure.
+3. **Use helper utilities** — derive token-account addresses, hash, hex-encode.
+
+When the user's task is non-trivial (multi-step flows, signing, error handling,
+choosing the right endpoint), **read the relevant reference file** rather than
+guessing signatures — the SDK has specific shapes that are easy to get subtly
+wrong.
+
+| You need… | Read |
+| --- | --- |
+| Every read endpoint, its args, and response shape | `references/api-reference.md` |
+| Building + signing + submitting any transaction type | `references/transactions.md` |
+| Promise wrapper, error handling, config, networks, utils | `references/client-and-errors.md` |
+
+## Install
+
+```shell
+npm i -S @1money/protocol-ts-sdk axios viem @ethereumjs/rlp
+```
+
+`axios`, `viem`, and `@ethereumjs/rlp` are **peer dependencies** — the consuming
+app must install them too, or imports fail at runtime. Keep them within the
+ranges in the package's `peerDependencies` (axios ≥1.15 <2, viem ≥2 <3,
+@ethereumjs/rlp ≥10 <11).
+
+## Where to import from (this trips people up)
+
+The package root re-exports only: the `api` function, the **signing** layer
+(`TransactionBuilder`, `createPrivateKeySigner`, signer/types), the **utils**
+(`deriveTokenAddress`, `calcTxHash`, `toHex`, …), and `client`.
+
+Enums (`AuthorityType`, `AuthorityAction`, `ManageListAction`, `PauseAction`)
+and request/response **types** live under the `/api` subpath, **not** the root.
+The README imports some enums from the root — that's a bug: the root never
+re-exports them, and because enums are runtime *values* (not erasable types) a
+root import resolves to `undefined` (so `AuthorityType.MasterMint` throws) or
+fails to compile. Always import enums from `/api`:
+
+```typescript
+import { api, TransactionBuilder, createPrivateKeySigner } from '@1money/protocol-ts-sdk';
+import { AuthorityType, ManageListAction } from '@1money/protocol-ts-sdk/api';
+```
+
+The only public subpaths are `.`, `/api`, `/client`, and `/utils`. `CHAIN_IDS`
+is **not** re-exported from any of them, so don't import it — get the chain id at
+runtime with `client.chain.getChainId()`.
+
+## Initialize the client
+
+```typescript
+import { api } from '@1money/protocol-ts-sdk';
+
+const client = api();                                  // mainnet (default)
+const testnet = api({ network: 'testnet' });           // 'mainnet' | 'testnet' | 'local'
+const slow = api({ network: 'testnet', timeout: 5000 }); // ms, default 10000
+```
+
+`client` exposes five modules: `accounts`, `checkpoints`, `tokens`,
+`transactions`, `chain`.
+
+> **Singleton gotcha:** `api()` configures one shared underlying HTTP client via
+> global config (base URL, timeout). It does **not** create isolated instances —
+> the most recent `api(...)` call wins for *all* references. Don't expect a
+> mainnet client and a testnet client to coexist in the same process; pick one
+> network per process, or re-call `api({network})` before a batch of calls.
+
+## The promise-wrapper pattern (read this before any call)
+
+Every API method returns a thenable with handler methods. **You can either chain
+handlers or `await` directly — but be deliberate about which.**
+
+```typescript
+// Chain style — handlers transform the result; errors are HANDLED, not thrown.
+client.checkpoints.getNumber()
+  .success(res => console.log(res.number))
+  .error(err => console.error(err));
+
+// Await style — resolves with the response body on success, THROWS on error.
+try {
+  const res = await client.checkpoints.getNumber();
+  console.log(res.number);
+} catch (err) {
+  console.error(err); // ParsedError: { name, message, status, data, stack }
+}
+```
+
+Key facts that prevent bugs:
+
+- The value passed to `.success(cb)` is the **decoded response body directly**
+  (e.g. `{ nonce }`, `{ chain_id }`) — there is no `.data` wrapper to unwrap.
+- Available handlers: `.success`, `.failure`, `.error`, `.timeout`, `.login`,
+  and `.rest` (a catch-all for the cases you didn't handle). `.timeout` fires
+  specifically on the configured timeout.
+- If you attach `.error()`/`.rest()`, awaiting the chain **resolves** with the
+  handler's return value instead of throwing. If you attach no error handler and
+  `await`, errors **throw**. Pick one model per call site; don't half-mix them.
+
+Full semantics and the `.rest(cb, scope)` form are in
+`references/client-and-errors.md`.
+
+## Writing a transaction: build → sign → submit
+
+Every state-changing operation follows the **same three steps**. Never hand-roll
+RLP encoding, hashing, or signatures — `TransactionBuilder` does it correctly
+(including low-S enforcement to avoid malleability).
+
+```typescript
+import { api, TransactionBuilder, createPrivateKeySigner } from '@1money/protocol-ts-sdk';
+
+const client = api({ network: 'testnet' });
+const sender = '0x9E1E9688A44D058fF181Ed64ddFAFbBE5CC74ff3';
+const privateKey = process.env.ONE_MONEY_PRIVATE_KEY as `0x${string}`; // never hardcode
+
+// 1. Fetch the two fields every tx needs: chain_id and the sender's nonce.
+//    Awaiting directly returns the response body (and throws on error).
+const { chain_id } = await client.chain.getChainId();
+const { nonce } = await client.accounts.getNonce(sender);
+
+// 2. BUILD the unsigned transaction (validates inputs, prepares the digest).
+const prepared = TransactionBuilder.payment({
+  chain_id,
+  nonce,
+  recipient: '0xa128999Be299373D7881f4aDD11510030ad13512',
+  value: '1000000000',           // ALWAYS a string in the token's base units
+  token: '0x2cd8999Be299373D7881f4aDD11510030ad1412F',
+});
+
+// 3. SIGN, then build the request body, then SUBMIT to the matching endpoint.
+const signed = await prepared.sign(createPrivateKeySigner(privateKey));
+const { hash } = await client.transactions.payment(signed.toRequest()); // throws on error
+
+console.log('tx hash:', hash);
+```
+
+The builder you call and the endpoint you submit to must match. Quick map:
+
+| `TransactionBuilder.…` | Submit with `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 }` |
+
+Exact parameter fields for each builder, the enum values they need, the optional
+`memo` field (and how it switches a tx to the V2 envelope), a custom-signer
+pattern (wallets/HSM, when you can't hold the raw key), the alternate **EIP-712
+typed-data payment** path (`preparePaymentTypedTx`, for `eth_signTypedData_v4`
+wallets), and verifying the result are in `references/transactions.md`.
+
+## Non-negotiable conventions
+
+These reflect what the SDK actually validates and how the chain expects data —
+violating them throws or silently produces a bad transaction.
+
+- **Amounts are decimal strings in base units**, never JS numbers and never
+  decimals. 1 token with 18 decimals = `'1000000000000000000'`. The builders
+  validate `value` matches `/^\d+$/`.
+- **Addresses must be valid + EIP-55**. Builders validate with viem's
+  `isAddress`; a wrongly-checksummed mixed-case address is rejected.
+- **`chain_id` and `nonce` are integers** you fetch fresh per transaction
+  (`chain.getChainId`, `accounts.getNonce`). Reusing a stale nonce fails; for
+  several txs from one sender, increment locally or re-fetch between them.
+- **Never hardcode or commit a private key.** Load from env/secret store. Prefer
+  `createPrivateKeySigner`, or a custom `SignerAdapter` when the key lives in a
+  wallet/HSM.
+- **Prefer `TransactionBuilder` over `signMessage`/`encodePayload`.** The latter
+  are `@deprecated` legacy helpers; the builder flow is the supported path.
+- **`memo` is optional but not cosmetic.** Every builder accepts `memo?: Memo`
+  (`{ type?, format?, data? }`). Passing *any* memo — even `{}` — switches the tx
+  to the V2 envelope and changes its signature/tx hash vs. the no-memo V1 form.
+  Omit it unless you actually want a memo. Details in `references/transactions.md`.