@asentum/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.2.0 (2026-10-20)
+
+Current with node 0.8.1. Full read coverage of the node API, confirmation
+helpers that follow a transaction from in-block to final, typed errors, and
+ase1 addresses everywhere.
+
+### Added
+
+- Chain heads: `getHeads()`, `getTipNumber()`, `getFinalizedNumber()` (`/v3/heads`).
+- Blocks: `getBlock(n, { tip })`, `getBlockReceipts(n, { tip })`, `getRawBlock(n)`, `getFinalizedStatus(h)`.
+- Receipts: `getReceipt(hash, { finalizedOnly })`; the `Receipt` type now lists `finalized`, `confirmations`, `blockHash`, `auraHash` and `error`.
+- `waitForReceipt(hash, { until: 'included' | 'final', timeoutMs, pollIntervalMs, onIncluded, onFinal, onReorg, signal, throwOnFailure, pauseWhenHidden })`. It polls about once a second, backs off on 429 / 5xx, and reports a receipt that disappears or moves to another block (`onReorg`).
+- `tx.wait({ until: 'final' })` and the other wait options. `tx.wait()` and `tx.wait(ms)` keep their 0.1.x meaning.
+- Accounts: `getAccount` (`/asentum/account`: nonce, codeHash, storageRoot), `getPublicKeyStatus` (`/public-key`), `getNonce(addr, { pending: false })`.
+- Contracts: `client.view()` (returns the value, throws `ViewError`), `blockTag` on `viewCall` / `view` / `contract.view`, `getStorageAt`, `getLogs` (decoded `eth_getLogs`, splits ranges over 10,000 blocks), `contract.getEvents`, `contract.getAccount`, `eventTopic(name)`.
+- Validators and consensus: `getParticipation`, `getCommittee`, `getLiveness`, `getTombstones`; `getValidators` types now include the epoch and committee state.
+- Governance reads: `getProposals`, `getProposal`, `getGovernanceLocked`, `getGovernanceWithdrawable`, `getGovernanceLibraries`, `getGovernanceLibrary`.
+- `getApiInfo` (`/api`), `getGenesis` (`/genesis`), `getTransaction` (`eth_getTransactionByHash`).
+- Submission: `submitRawTxBatch` (`/tx/batch`), `wallet.signTransfer` / `signCall` / `signDeploy` (sign without sending), `wallet.sendBatch`.
+- Wei variants: `amountWei` / `valueWei` on every send, `sendTransferWei`, `sendCallWei`, and the strict `aseToWei` and `toWei` helpers.
+- Nonce handling: the wallet allocates consecutive nonces from `pendingNonce`, serialises concurrent sends, and resyncs after a rejection (`wallet.resetNonce()`).
+- Key-less (key-once) transactions: `keyless: 'auto' | 'always'` on the wallet or per send. Default `'off'`.
+- Typed errors: `AsentumError` and `TxRejectedError`, `TxFailedError`, `TimeoutError`, `AbortError`, `ViewError`, `RpcError`, `JsonRpcError`, `RateLimitError`, `HttpError`, `NetworkError`.
+- Transport options: `retries`, `requestTimeoutMs`, `backoffBaseMs`, `backoffMaxMs`, `headers`, custom `fetch`. Every method takes `{ signal, retries }`.
+- Address helpers matching @asentum/connect: `isAse1`, `ase1ToHex`, `hexToAse1`, `toAse1`, `shortAse1`, plus `toHexAddress`, `isHexAddress`, `isAddress`, `addressToBytes`, `bytesToAse1`, `getContractAddress`.
+- `wallet.addressHex`, `contract.addressHex`, `DEFAULT_RPC`, `GOVERNANCE_CONTRACT`, `VERSION`.
+
+### Fixed
+
+- `getBlock` returned the node's `{"error":"not found"}` object instead of `null`.
+- `isReady` returned true for any answer, including a 503.
+- `getBalance` and other reads returned the node's HTTP 200 error body (for example `invalid address`) as if it were data; they now throw `RpcError`.
+- `getReceipt` returned `null` for every error, so a rate limit or a bad hash looked like "not mined yet".
+- `parseAse(number)` lost precision (`1.1` became 1100000000000000128 wei).
+- Every send fetched the chain id again; it is cached now.
+- 429 and 5xx responses were not retried; the gateway's HTML 429 body broke JSON parsing.
+- The package no longer depends on `@asentum/crypto` and `@asentum/types` from npm: their published 0.1.0 builds lack the bech32 and key-less code that the unreleased 0.1.1 source already imported, so a 0.1.1 build would not have loaded outside the monorepo. The SDK now carries the small parts it needs and depends only on `@noble/hashes`, `@noble/post-quantum` and `@chainsafe/ssz`.
+- `tsconfig.json` no longer extends a file outside the repository.
+
+### Changed (breaking)
+
+- `wallet.address` is ase1 (it was checksummed 0x hex). Use `wallet.addressHex` for hex.
+- `contract.address` is always ase1 (a deploy used to give 0x hex). Use `contract.addressHex` for hex.
+- Receipt `sender` and `recipient` are ase1 (the node sends hex). The same for participation, committee, liveness and governance proposer addresses. Addresses inside event data and contract return values are left as the contract wrote them.
+- `getReceipt` throws on transport and RPC errors (after retries) instead of returning `null`. `null` still means "not in a block yet".
+- `new AsentumContract(client, address)` throws on an invalid address (it used to accept any string).
+- Reads that get an HTTP 200 error body throw `RpcError` instead of returning the body.
+- `contract.view` throws `ViewError` (the message format is unchanged, so `catch` blocks that read the message keep working).
+- The default timeout of `tx.wait()` and `waitForDeploy()` is 60 s (was 15 s).
+- `dist` no longer ships `src`; source maps still include the sources.
+
+### Deprecated
+
+- `client.faucet()` and `wallet.requestFaucet()`. `POST /dev/faucet` is off on every public node and only works on a local devnet that turns it on. For test ASE use the airdrop dashboard. They now return `{ accepted: false, reason }` instead of throwing on a 404.
+
+## 0.1.1 (git only, not published to npm)
+
+- Convert ase1 addresses in call arguments to hex before signing and in view calls.
+- A failed transaction's receipt (which carries `error`) is returned instead of being treated as "not found".
+- npm package metadata.
+
+## 0.1.0
+
+- Initial release: `AsentumClient`, `AsentumWallet`, `AsentumContract`.

package/README.md

@@ -1,7 +1,10 @@
 # @asentum/sdk
 
-TypeScript SDK for building on Asentum. Three classes, one import, works
-in Node.js and browsers.
+TypeScript SDK for Asentum. Read the chain, sign with Dilithium3 (ML-DSA-65),
+send transactions, follow them from "in a block" to "final", and work with
+contracts and their events. Works in Node.js 18+ and modern browsers.
+
+Current with node 0.8.1.
 
 ```bash
 npm install @asentum/sdk
@@ -10,192 +13,327 @@ npm install @asentum/sdk
 ## Quick start
 
 ```ts
-import { AsentumClient, AsentumWallet } from '@asentum/sdk';
+import { AsentumClient, AsentumWallet, formatAse } from '@asentum/sdk';
 
 const client = new AsentumClient('https://testnet.asentum.com');
-const wallet = AsentumWallet.create(client);
 
-// Fund from the testnet faucet
-await wallet.requestFaucet();
+// Reads need no keys
+const { finalized, tip } = await client.getHeads();
+const bal = await client.getBalance('ase1v0myp2de3dhj3crvkhxqlnjaw2mvp64a9efkpl');
+console.log(formatAse(bal.balance), 'ASE at block', tip);
 
-// Check balance
-const balance = await wallet.getBalance();
-console.log(balance); // 100000000000000000000n (100 ASE)
+// A wallet signs locally; keys never leave your process
+const wallet = AsentumWallet.fromSecretKey(client, SECRET_KEY_HEX, PUBLIC_KEY_HEX);
+console.log(wallet.address); // ase1...
 
-// Send ASE
 const tx = await wallet.sendTransfer({
-  to: '0x1111111111111111111111111111111111111111',
-  amount: '10',
+  to: 'ase1wtc569gfwk87hplaawr46uj4suwsx2wndgf8ue',
+  amountWei: 10n ** 18n, // 1 ASE
 });
-const receipt = await tx.wait();
-console.log('confirmed in block', receipt.blockNumber);
+const receipt = await tx.wait();          // in a block, about 2.5 s
+if (!receipt.success) throw new Error(receipt.error);
+await tx.wait({ until: 'final' });        // final, a few blocks later
 ```
 
-## Deploy and interact with a contract
+Test ASE comes from the airdrop dashboard (see "Get Test ASE" in the docs).
+The node's `/dev/faucet` route is off on every public node.
+
+## Things to know about the chain
+
+- **Two heads.** The *tip* is the newest block on the best chain. The
+  *finalized* height trails it by about 3 blocks and never changes.
+  `getHeads()` returns both.
+- **Accepted is not included.** `POST /tx` answering `accepted: true` only
+  means the node put the transaction in its mempool. Wait for the receipt.
+- **Receipts use `success`**, a boolean. There is no `status` on the REST
+  receipt. A failed transaction has `success: false` and an `error` reason.
+- **Receipts read the tip by default.** A receipt with `finalized: false` is
+  in a block; rarely that block loses to a sibling and the transaction lands
+  again in a later block. Only `finalized: true` is permanent.
+- **Addresses.** The SDK accepts `ase1...` or `0x...` everywhere and returns
+  ase1 for every address it surfaces, also where the node answers with hex
+  (receipts, participation, committee, governance). Contracts work with
+  lowercase hex internally, so the SDK converts ase1 addresses inside
+  contract arguments to hex before signing or viewing. Hashes and raw bytes
+  stay 0x hex (they have no ase1 form), and so do addresses inside contract
+  return values and event data: convert those with `toAse1` before showing
+  them.
+- **Amounts** are wei (1 ASE = 10^18 wei) as decimal strings in responses.
+- **Rate limits.** The public gateway allows about 25 requests a second per
+  IP and answers 429 with an HTML page; nodes limit block and receipt reads
+  to a burst of 240, then 4 a second. The SDK retries 429 and 5xx with
+  backoff (honouring Retry-After when sent) before it throws `RateLimitError`.
+
+## AsentumClient
 
 ```ts
-// Deploy
-const contract = await wallet.deploy(`
-  function init() {
-    storage.set('greeting', 'hello world');
-    emit('Init', { sender: msg.sender });
-  }
-
-  function getGreeting() {
-    return storage.get('greeting');
-  }
-
-  function setGreeting(value) {
-    storage.set('greeting', value);
-    emit('Updated', { value });
-  }
-`);
-console.log('contract:', contract.address);
-
-// Initialize
-const initTx = await contract.send('init');
-await initTx.wait();
-
-// Read (free, no tx)
-const greeting = await contract.view('getGreeting');
-console.log(greeting); // "hello world"
-
-// Write (sends a tx)
-const setTx = await contract.send('setGreeting', ['gm asentum']);
-await setTx.wait();
-
-console.log(await contract.view('getGreeting')); // "gm asentum"
+const client = new AsentumClient(url?, {
+  retries: 3,              // retries for 429 / 5xx / network errors
+  requestTimeoutMs: 30000,
+  fetch,                   // custom fetch, optional
+  headers: {},             // e.g. Authorization for a private RPC
+});
 ```
 
-## API
-
-### `AsentumClient`
-
-Read-only interface to the chain. No keys, no signing: just reads.
+Every method takes an optional last argument `{ signal?: AbortSignal, retries?: number }`.
+
+### Chain and health
+
+| Method | Route | Returns |
+|---|---|---|
+| `getHeads()` | `GET /v3/heads` | `{ finalized: number, tip: number }` |
+| `getTipNumber()` / `getFinalizedNumber()` | `GET /v3/heads` | `number` |
+| `getBlockNumber()` | `GET /chain` | finalized height, `number` |
+| `getChainInfo()` | `GET /chain` | chain id, finalized height, mempool size, header |
+| `getChainId()` | `GET /chain` | `bigint` (cached) |
+| `getMetadata()` | `GET /metadata` | EIP-3085 metadata |
+| `getApiInfo()` | `GET /api` | node identity |
+| `getGenesis()` | `GET /genesis` | genesis spec |
+| `isHealthy()` | `GET /health` | `boolean` |
+| `isReady()` | `GET /ready` | `boolean` (false on 503; note that node 0.8.1 reports ready even when stalled, so watch `getHeads()`) |
+
+### Accounts
+
+| Method | Route | Returns |
+|---|---|---|
+| `getBalance(addr)` | `GET /balance/<addr>` | `{ address, balance, nonce, pendingNonce }` |
+| `getNonce(addr, { pending? })` | `GET /balance/<addr>` | `bigint`, pendingNonce by default |
+| `getAccount(addr)` | `GET /asentum/account/<addr>` | `{ exists, balance, nonce, codeHash, storageRoot, height }` |
+| `getPublicKeyStatus(addr)` | `GET /public-key/<addr>` | `{ recorded, canOmitKey, ... }` |
+
+### Blocks
+
+| Method | Route | Returns |
+|---|---|---|
+| `getBlock(n, { tip? })` | `GET /block/<n>[?tip=1]` | `Block \| null` (`finalized`, and `confirmations`/`auraHash` on tip blocks) |
+| `getBlockReceipts(n, { tip? })` | `GET /block/<n>/receipts` | `{ receipts, finalized?, available }` |
+| `getRawBlock(n)` | `GET /block-raw/<n>` | SSZ hex or `null` |
+| `getFinalizedStatus(h)` | `GET /v3/finalized?height=` | `{ finalized, auraHash? }` |
+
+### Transactions and receipts
+
+| Method | Route | Returns |
+|---|---|---|
+| `getReceipt(hash, { finalizedOnly? })` | `GET /receipts/<hash>[?tip=0]` | `Receipt \| null` (`success`, `error?`, `finalized`, `confirmations`, `blockHash`, `auraHash?`) |
+| `waitForReceipt(hash, opts)` | polls `GET /receipts` | `Receipt` (see below) |
+| `getTransaction(hash)` | `eth_getTransactionByHash` | `EthTransaction \| null` |
+| `submitRawTx(rawTx)` | `POST /tx` | `{ accepted, reason?, txHash? }` |
+| `submitRawTxBatch(rawTxs)` | `POST /tx/batch` | `{ accepted, rejected, total, results }` |
+
+### Contracts
+
+| Method | Route | Returns |
+|---|---|---|
+| `viewCall(contract, method, args, { blockTag? })` | `POST /view` | `{ ok, returnValue, reason?, blockNumber, finalized, ... }` |
+| `view(contract, method, args, { blockTag? })` | `POST /view` | the return value; throws `ViewError` |
+| `getCode(addr)` / `getContractSource(addr)` | `eth_getCode` | hex / source text |
+| `getStorageAt(addr, key)` | `eth_getStorageAt` | stored text or `null` |
+| `getLogs({ address, event, fromBlock, toBlock })` | `eth_getLogs` | decoded `Log[]` (finalized blocks only; ranges over 10,000 blocks are split) |
+
+`blockTag` is `'tip'` (default; `'latest'` and `'pending'` mean the same) or
+`'finalized'` (`'safe'`). There are no historical state reads.
+
+### Validators, consensus, governance
+
+| Method | Route |
+|---|---|
+| `getValidators()` | `GET /validators` (about 260 KB) |
+| `getParticipation({ lookback })` | `GET /participation` |
+| `getCommittee({ epoch })` | `GET /v3/committee` |
+| `getLiveness()` | `GET /consensus/liveness` |
+| `getTombstones()` | `GET /slashing/tombstones` |
+| `getProposals()` / `getProposal(id)` | `GET /governance/proposals`, `/governance/proposal/<id>` |
+| `getGovernanceLocked(addr)` / `getGovernanceWithdrawable(addr)` | `GET /governance/locked/<addr>`, `/governance/withdrawable/<addr>` |
+| `getGovernanceLibraries()` / `getGovernanceLibrary(name)` | `GET /governance/libraries`, `/governance/library/<name>` |
+| `jsonRpc(method, params)` | `POST /` (any JSON-RPC method) |
+
+`faucet()` is deprecated: it calls `/dev/faucet`, which only works on a local
+devnet that turned it on.
+
+## AsentumWallet
 
 ```ts
-const client = new AsentumClient('https://testnet.asentum.com');
+const wallet = AsentumWallet.create(client);                    // random key
+const wallet2 = AsentumWallet.fromSeed(client, seed32);         // deterministic
+const wallet3 = AsentumWallet.fromSecretKey(client, skHex, pkHex);
 
-await client.getBlockNumber();           // number
-await client.getChainId();               // bigint
-await client.getBlock(42);               // Block | null
-await client.getBalance('0x...');        // { address, balance, nonce }
-await client.getNonce('0x...');          // bigint
-await client.getReceipt('0xabc...');     // Receipt | null
-await client.getCode('0x...');           // hex string
-await client.getContractSource('0x...');  // JS source string | null
-await client.viewCall('0x...', 'name');  // ViewCallResult
-await client.getValidators();            // { count, validators[] }
-await client.getMetadata();              // EIP-3085 metadata
-await client.isHealthy();                // boolean
-await client.faucet('0x...');            // TxResult (testnet only)
-```
+wallet.address;      // ase1...
+wallet.addressHex;   // 0x... lowercase, what contracts see as msg.sender
+wallet.secretKeyHex; // back this up like a password
+wallet.publicKeyHex;
 
-### `AsentumWallet`
+await wallet.getBalance(); // bigint wei
+await wallet.getNonce();   // bigint, the node's pendingNonce
+```
 
-A client + Dilithium3 keypair. Can sign and submit transactions.
+### Sending
 
 ```ts
-// Create random
-const wallet = AsentumWallet.create(client);
-
-// From seed (deterministic)
-const wallet2 = AsentumWallet.fromSeed(client, seed32bytes);
-
-// From exported keys
-const wallet3 = AsentumWallet.fromSecretKey(client, '0xsk...', '0xpk...');
+await wallet.sendTransfer({ to, amountWei: 10n ** 18n });
+await wallet.sendCall({ to: contract, method: 'swap', args: [...], valueWei: 0n });
+const c = await wallet.deploy(source); // c.address is known right away
+await c.waitForDeploy();
+```
 
-wallet.address;        // '0x...' checksummed
-wallet.secretKeyHex;   // for backup
-wallet.publicKeyHex;
+Every send returns `{ hash, nonce, from, contractAddress?, wait() }` once the
+node has accepted it, and throws `TxRejectedError` (with `reason`) when it
+did not. A rejected transaction never reaches the chain.
 
-await wallet.getBalance();     // bigint (wei)
-await wallet.getNonce();       // bigint
-await wallet.requestFaucet();  // TxResult
+**Amounts.** `amountWei` / `valueWei` are exact wei. The older `amount` /
+`value` fields go through `parseAse`: a number or decimal string is ASE
+(`'1.5'` is 1.5 ASE), a bigint is wei, and an integer string longer than 18
+digits is read as wei. `sendTransferWei` and `sendCallWei` take wei only.
 
-// Send transfer
-const tx = await wallet.sendTransfer({ to: '0x...', amount: '1.5' });
-const receipt = await tx.wait();
+**Nonces.** The wallet asks the node for `pendingNonce` and hands out
+consecutive nonces itself, so back-to-back and concurrent sends from one
+wallet get n, n+1, n+2. After a rejection it asks the node again
+(`wallet.resetNonce()` does the same by hand). Pass `nonce` to override.
+Submit and poll through the same RPC: `pendingNonce` is per node.
 
-// Deploy contract
-const contract = await wallet.deploy('function init() { ... }');
+**Batches.** Sign first, then submit in one request:
 
-// Call contract (write)
-const tx2 = await wallet.sendCall({
-  to: '0x...',
-  method: 'transfer',
-  args: ['0xbob...', '100'],
-});
+```ts
+const a = await wallet.signCall({ to, method: 'a' });
+const b = await wallet.signCall({ to, method: 'b' });
+const res = await wallet.sendBatch([a, b]);   // POST /tx/batch
+res.results[0].accepted; res.results[0].wait();
 ```
 
-### `AsentumContract`
+**Key-less transactions.** Once the chain has an account's public key on
+record, its transactions can leave the key out and are about a third
+smaller. `AsentumWallet.create(client, { keyless: 'auto' })` switches to that
+as soon as `getPublicKeyStatus().canOmitKey` is true. The default is `'off'`.
 
-A deployed contract with view + send helpers.
+Other overrides on every send: `gasLimit` (defaults: 21,000 for transfers,
+2,000,000 for calls, at least 2,000,000 for deploys; contract calls need
+at least 50,000), `maxFeePerGas` (default 1), `signal`.
 
-```ts
-// From a deploy
-const contract = await wallet.deploy(source);
+## AsentumContract
 
-// Or wrap an existing address
+```ts
 import { AsentumContract } from '@asentum/sdk';
-const contract = new AsentumContract(client, '0xcontract...');
-
-// Read (free)
-const result = await contract.view('balanceOf', ['0x...']);
 
-// Read with full result (includes gas + events)
-const full = await contract.viewFull('balanceOf', ['0x...']);
-
-// Write (needs wallet)
-const tx = await contract.send('transfer', ['0x...', '100']);
-await tx.wait();
+const pool = new AsentumContract(client, 'ase1v0myp2de3dhj3crvkhxqlnjaw2mvp64a9efkpl');
+await pool.view('getPool', ['3']);                          // reads the tip
+await pool.view('getPool', ['3'], { blockTag: 'finalized' });
+await pool.viewFull('getPool', ['3']);                      // value, gas, events, blockNumber
+const tx = await pool.connect(wallet).send('swapExactIn', [...], { valueWei });
+await pool.getEvents('Swap', { fromBlock: 570000, toBlock: 571000 });
+await pool.getSource();
+await pool.getAccount(); // codeHash = BLAKE3 of the source
+```
 
-// Attach a wallet for future send() calls
-const signed = contract.connect(wallet);
-await signed.send('transfer', ['0x...', '50']);
+## Fast confirmations
 
-// Get source code
-const source = await contract.getSource();
+A transaction is in a block about one block after you send it (roughly 2.5
+seconds) and final a few blocks later (roughly 7 to 10 seconds). Show
+success at the first point, act on it off chain only at the second.
 
-// Wait for deploy confirmation
-await contract.waitForDeploy();
+```ts
+import { TimeoutError } from '@asentum/sdk';
+
+const tx = await contract.send('swapExactIn', args);
+setStatus(tx.hash, 'pending');
+
+try {
+  await tx.wait({
+    until: 'final',
+    onIncluded: (r) => setStatus(tx.hash, r.success ? 'in-block' : 'failed'),
+    onReorg: () => setStatus(tx.hash, 'pending'),   // its block lost; it will land again
+    onFinal: (r) => setStatus(tx.hash, r.success ? 'final' : 'failed'),
+    timeoutMs: 120_000,
+    signal,                                          // AbortSignal, optional
+  });
+} catch (e) {
+  if (e instanceof TimeoutError) setStatus(tx.hash, 'still-pending'); // not a failure
+  else throw e;
+}
 ```
 
-### Helpers
+`client.waitForReceipt(hash, options)` is the same for any hash. Options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `until` | `'included'` | `'included'`: resolve at the first receipt. `'final'`: resolve once `finalized: true`. |
+| `timeoutMs` | 60,000 / 120,000 | Rejects with `TimeoutError` (`lastReceipt` set if it was in a block). |
+| `pollIntervalMs` | 1,000 | Blocks are about 2.5 s apart; faster buys nothing. |
+| `onIncluded(r)` | | In a block. Fires again if a reorg moves it to another block. |
+| `onReorg(prev)` | | The block it was in lost to a sibling. |
+| `onFinal(r)` | | Final (with `until: 'final'`). |
+| `throwOnFailure` | `false` | Reject with `TxFailedError` on `success: false` instead of resolving. |
+| `signal` | | Stop waiting (`AbortError`). The transaction is not affected. |
+| `pauseWhenHidden` | `true` | In a browser, no polling while the tab is hidden. |
+
+The poller backs off on 429 and 5xx (Retry-After when sent, otherwise
+doubling up to 10 s) and keeps going through network blips.
+
+`tx.wait()` with no argument behaves as in 0.1.x: it resolves at the first
+receipt (in a block), including a failed one. `tx.wait(ms)` still takes a
+timeout.
+
+## Errors
+
+All errors the SDK throws on purpose extend `AsentumError` and carry a
+stable `code`:
+
+| Class | When |
+|---|---|
+| `TxRejectedError` | `POST /tx` answered `accepted: false` (`reason`, `isNonceError`) |
+| `TxFailedError` | the receipt has `success: false` (with `throwOnFailure`) |
+| `TimeoutError` | waiting ran out (`lastReceipt`); the tx may still land |
+| `AbortError` | your AbortSignal fired |
+| `ViewError` | `POST /view` answered `ok: false` |
+| `RpcError` | HTTP 200 with an `error` body (bad address, bad hash, failed governance read) |
+| `JsonRpcError` | a JSON-RPC error object (`rpcCode`) |
+| `RateLimitError` | HTTP 429 after retries (`retryAfterMs`) |
+| `HttpError` | any other non-2xx (`status`, `body`) |
+| `NetworkError` | fetch failed or timed out |
+
+"Not found" is not an error: `getReceipt`, `getBlock`, `getTransaction`,
+`getRawBlock` and `getProposal` return `null`.
+
+## Helpers
 
 ```ts
-import { parseAse, formatAse } from '@asentum/sdk';
-
-parseAse('1');      // 1000000000000000000n (1 ASE in wei)
-parseAse('0.5');    // 500000000000000000n
-parseAse(100n);     // 100n (already wei)
-
-formatAse(1500000000000000000n);  // "1.5"
-formatAse('1000000000000000000'); // "1"
+import {
+  toAse1, toHexAddress, hexToAse1, ase1ToHex, isAse1, isHexAddress, isAddress, shortAse1,
+  ase1ArgsToHex, aseToWei, parseAse, formatAse, toWei, eventTopic, getContractAddress,
+} from '@asentum/sdk';
+
+toAse1('0x72f14d1509758feb87fdeb875d7255871d0329d3'); // 'ase1wtc569gfwk87hplaawr46uj4suwsx2wndgf8ue'
+toHexAddress('ase1wtc569gfwk87hplaawr46uj4suwsx2wndgf8ue'); // '0x72f1...29d3'
+ase1ArgsToHex(['ase1...', { owner: 'ase1...' }]); // every ase1 inside becomes 0x hex
+aseToWei('1.5');        // 1500000000000000000n (always ASE)
+formatAse(15n * 10n ** 17n); // '1.5'
+eventTopic('Swap');     // topics[0] for eth_getLogs: BLAKE3 of the name
+getContractAddress(wallet.address, 3n); // where a deploy with nonce 3 lands
 ```
 
-## How it works
+## Upgrading from 0.1.x
 
-The SDK wraps the node's HTTP RPC endpoints:
+See [CHANGELOG.md](./CHANGELOG.md). The short list: `wallet.address` and
+`contract.address` are ase1 now (`addressHex` has the hex), receipt
+`sender`/`recipient` are ase1, `getBlock` returns `null` for a missing block,
+`getReceipt` throws on transport errors instead of returning `null`, and the
+faucet helpers are deprecated.
 
-| SDK method | RPC endpoint |
-|------------|-------------|
-| `getBlock(n)` | `GET /block/{n}` |
-| `getBalance(addr)` | `GET /balance/{addr}` |
-| `viewCall(addr, method, args)` | `POST /view` |
-| `sendTransfer/sendCall/deploy` | `POST /tx` (signed SSZ bytes) |
-| `getCode(addr)` | `POST / eth_getCode` (JSON-RPC) |
-| `faucet(addr)` | `POST /dev/faucet` |
+## How it works
 
-Transactions are built via SSZ schemas from `@asentum/types`, hashed
-with BLAKE3, signed with Dilithium3 from `@asentum/crypto`, and
-submitted as hex-encoded wire bytes. The entire signing pipeline runs
-locally: private keys never leave your process.
+Transactions are SSZ encoded, hashed with BLAKE3, signed with ML-DSA-65
+(Dilithium3) locally and submitted as hex to `POST /tx`. The transaction
+hash is BLAKE3 of the signed bytes, so the SDK knows it before the node
+answers. Reads use the node's REST routes, plus JSON-RPC for code, storage,
+transactions and logs. See the [Node API Reference](https://asentum.com/docs/reference/api)
+and [Fast Confirmations](https://asentum.com/docs/guides/fast-confirmations).
 
-## Requirements
+## Development
 
-- Node.js 22+ or any modern browser with `fetch` and `crypto.getRandomValues`
-- An Asentum RPC endpoint (the public testnet is at `https://testnet.asentum.com`)
+```bash
+npm test                 # unit tests (mocked fetch)
+npm run test:live        # read-only smoke test against https://testnet.asentum.com
+npm run typecheck
+npm run build
+```
 
 ## License