@rialo/ts-cdk 0.4.2 → 0.8.0-alpha.0

package/README.md

@@ -1,441 +1,502 @@
-# Rialo TypeScript CDK
+# @rialo/ts-cdk
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-
-A TypeScript library for interacting with the Rialo blockchain. Provides cryptographic primitives, transaction building, and RPC client for blockchain communication.
+TypeScript library for building on the Rialo blockchain. Provides Ed25519 cryptographic
+primitives, BIP39/SLIP-0010 HD wallet derivation, transaction construction and signing,
+a JSON-RPC client for node communication, program deployment, and HPKE encryption for
+TEE programs. Works in Node.js ≥ 18 and modern browsers (ESM and CJS bundles included).
 
 ## Installation
 
 ```bash
 npm install @rialo/ts-cdk
+# or
+pnpm add @rialo/ts-cdk
+# or
+yarn add @rialo/ts-cdk
 ```
 
-## Quick Start
+Requires Node.js ≥ 18. Ships both ESM (`dist/index.mjs`) and CJS (`dist/index.js`) bundles with
+bundled TypeScript declarations. Works in modern browsers when bundled with Vite/webpack.
 
-### Create a keypair and sign a message
+## Key public types
 
-```typescript
-import { Keypair } from "@rialo/ts-cdk";
+### Cryptography
 
-const keypair = Keypair.generate();
-console.log("Address:", keypair.publicKey.toString());
+| Export | Purpose |
+|---|---|
+| `Keypair` | Ed25519 keypair; generate, derive from seed, sign, verify, dispose |
+| `PublicKey` | 32-byte Ed25519 public key; PDA derivation, base58 encoding |
+| `Signature` | 64-byte Ed25519 signature; base58 encoding |
+| `Mnemonic` | BIP39 mnemonic; generate, restore, derive keypairs via SLIP-0010 |
 
-const message = new TextEncoder().encode("Hello Rialo");
-const signature = keypair.sign(message);
-const isValid = keypair.verify(message, signature);
-```
-
-### Connect to the blockchain
+### Keyring management
 
-```typescript
-import { createRialoClient, RIALO_DEVNET_CHAIN } from "@rialo/ts-cdk";
+| Export | Purpose |
+|---|---|
+| `RialoKeyring` | Named collection of `Keypair` instances with an active signing key |
+| `InMemoryKeyringProvider` | Create `RialoKeyring` from a mnemonic or a list of keypairs |
+| `DerivedKeypairInfo` | Metadata for a single derived keypair (index, pubkey, path) |
 
-const client = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
-
-// Query blockchain
-const balance = await client.getBalance(keypair.publicKey);
-const height = await client.getBlockHeight();
-const chainId = client.getChainIdentifier();
-```
-
-### Build and send a transaction
+### Transactions
 
-```typescript
-import { TransactionBuilder, transferInstruction } from "@rialo/ts-cdk";
+| Export | Purpose |
+|---|---|
+| `TransactionBuilder` | Fluent builder for constructing transactions |
+| `Transaction` | Signed/unsigned transaction; serialize, deserialize, multi-sig |
+| `Message` | Compiled transaction message with account keys and instructions |
+| `Instruction` | Single operation: program ID, accounts, data |
+| `AccountMeta` | Account reference with `isSigner` / `isWritable` flags |
+| `AccountMetaTable` | Deduplication table for account references within a message |
+| `transferInstruction` | System-program transfer helper |
+| `createAccount` | System-program create-account helper |
 
-// transaction valid from
-const validFrom = BigInt(Date.now());
+### RPC
 
-// Create transfer instruction
-const transfer = transferInstruction(
-  keypair.publicKey,
-  recipientAddress,
-  BigInt(1_000_000) // amount in kelvins
-);
+| Export | Purpose |
+|---|---|
+| `createRialoClient` | Factory for `RialoClient`; accepts a chain preset or custom config |
+| `getDefaultRialoClientConfig` | Returns a `RialoClientConfig` for `"mainnet"`, `"devnet"`, `"testnet"`, or `"localnet"` |
+| `RialoClient` | Full RPC surface for a Rialo node |
+| `RIALO_MAINNET_CHAIN` / `…TESTNET…` / `…DEVNET…` / `…LOCALNET…` | Chain presets |
 
-// Build and sign transaction
-const tx = TransactionBuilder.create()
-  .setPayer(keypair.publicKey)
-  .setValidFrom(validFrom)
-  .addInstruction(transfer)
-  .build();
+### Other
 
-const signedTx = tx.sign(keypair);
+| Export | Purpose |
+|---|---|
+| `Signer` / `KeypairSigner` | Abstract signing interface for hardware wallets and custom signers |
+| `ProgramDeployment` | Deploy PolkaVM program binaries to the network |
+| `RexValue` | Typed wrapper for plain or HPKE-encrypted byte payloads |
+| `RialoError` / `RialoErrorType` | Structured error with discriminated type field |
 
-// Send to network
-const signature = await client.sendTransaction(signedTx.serialize());
-```
+## Usage
 
-### Generate and use mnemonics
+### Keypair and signing
 
 ```typescript
-import { Mnemonic } from "@rialo/ts-cdk";
+import { Keypair, PublicKey } from "@rialo/ts-cdk";
 
-// Generate 12-word mnemonic
-const mnemonic = Mnemonic.generate();
+// Generate a random keypair
+const keypair = Keypair.generate();
+console.log("Address:", keypair.publicKey.toString());
 
-// Derive keypair (default path: m/44'/756'/0'/0')
-const keypair = await mnemonic.toKeypair();
+// Restore from a known 32-byte secret key
+const restored = Keypair.fromSecretKey(secretKeyBytes);
 
-// Use custom derivation path
-const keypair2 = await mnemonic.toKeypair("m/44'/756'/0'/1'");
+const message = new TextEncoder().encode("Hello Rialo");
+const sig = keypair.sign(message);
+const ok = keypair.verify(message, sig);
 
-// Restore from existing mnemonic
-const restored = Mnemonic.fromPhrase("your twelve word mnemonic phrase here...");
-const restoredKeypair = await restored.toKeypair();
+// Always dispose keypairs when finished to zero out the private key.
+keypair.dispose();
 ```
 
-## Core Modules
+### BIP39 mnemonic and HD derivation
 
-### Crypto
-
-Ed25519 cryptographic primitives for key management and signing.
+Rialo uses BIP44 coin type 756 with SLIP-0010 (`m/44'/756'/{index}'/0'`).
 
 ```typescript
-import { Keypair, PublicKey, Signature } from "@rialo/ts-cdk";
+import { Mnemonic } from "@rialo/ts-cdk";
 
-// Generate random keypair
-const keypair = Keypair.generate();
+// Generate a new 12-word mnemonic (pass 256 for 24-word)
+const mnemonic = Mnemonic.generate();           // 128-bit entropy, 12 words
+console.log(mnemonic.toString());
+console.log("Words:", mnemonic.getWordCount()); // 12
+
+// Validate a phrase without constructing a Mnemonic
+const valid = Mnemonic.isValid("word1 word2 … word12");
 
-// From existing secret key
-const keypair = Keypair.fromSecretKey(secretBytes);
+// Restore from an existing phrase
+const restored = Mnemonic.fromPhrase("word1 word2 … word12");
 
-// Public key operations
-const pubkey = PublicKey.fromString("base58string");
-const address = pubkey.toString();
-const bytes = pubkey.toBytes();
+// Derive account keypairs
+const account0 = await mnemonic.toKeypair(0);  // m/44'/756'/0'/0'
+const account1 = await mnemonic.toKeypair(1);  // m/44'/756'/1'/0'
 
-// Signature operations
-const sig = Signature.fromBytes(signatureBytes);
+// With an optional BIP39 passphrase
+const secure = await mnemonic.toKeypair(0, { passphrase: "my-secret" });
 
-// validFrom for transactions
-const validFrom = BigInt(Date.now());
+// Derive with an explicit full path (advanced)
+const custom = await mnemonic.toKeypairWithPath("m/44'/756'/0'/0'");
+
+// Derive multiple at once (indices 0–4)
+const keypairs = await mnemonic.deriveKeypairs(5);
+
+// Convert to raw 64-byte BIP39 seed
+const seed = await mnemonic.toSeed();
 ```
 
-### Transactions
+### Keyring management
 
-Build and sign transactions with instructions.
+`RialoKeyring` manages a set of derived keypairs and tracks the active signing key,
+useful when an application needs to sign on behalf of multiple accounts.
 
 ```typescript
-import { 
-  TransactionBuilder, 
-  transferInstruction,
-  type Instruction,
-  type AccountMeta 
-} from "@rialo/ts-cdk";
+import { Mnemonic, InMemoryKeyringProvider } from "@rialo/ts-cdk";
 
-// Simple transfer
-const transfer = transferInstruction(from, to, amount);
+const mnemonic = Mnemonic.generate();
+const provider = new InMemoryKeyringProvider();
 
-// Custom instruction
-const instruction: Instruction = {
-  programId: PublicKey.fromString("YourProgramId"),
-  accounts: [
-    { pubkey: account1, isSigner: true, isWritable: true },
-    { pubkey: account2, isSigner: false, isWritable: true },
-  ],
-  data: instructionData, // Uint8Array
-};
+// Derive 3 keypairs into a single keyring
+const keyring = await provider.createFromMnemonic(mnemonic, 3);
 
-// Build transaction
-const tx = TransactionBuilder.create()
-  .setPayer(payerPublicKey)
-  .setValidFrom(validFrom)
-  .addInstruction(instruction)
-  .build();
+// Switch the active keypair
+keyring.setActiveKeypair(2);
+console.log("Active:", keyring.pubkeyString());
 
-// Single signer
-const signed = tx.sign(keypair);
+// Sign with the active keypair
+const sig = keyring.sign(messageBytes);
 
-// Multi-sig
-const partial = tx.partialSign(signer1);
-const complete = partial.partialSign(signer2);
+// Sign with a specific keypair without switching active
+const sig1 = keyring.signWithKeypair(messageBytes, 1);
+
+// Inspect all keypairs
+for (const info of keyring.getKeypairsInfo()) {
+  console.log(`index=${info.index}  pubkey=${info.pubkeyString}`);
+}
 
-// Serialize for network
-const bytes = signed.serialize();
+// Securely zero all private keys when done
+keyring.dispose();
 ```
 
-### RPC Client
+### Build and send a transaction
 
-Communicate with Rialo blockchain nodes.
+`TransactionBuilder` requires a `configHashPrefix` fetched from the network. Every
+transaction submitted to a live node must carry the current prefix or it will be
+rejected.
 
 ```typescript
 import {
+  TransactionBuilder,
+  transferInstruction,
   createRialoClient,
   getDefaultRialoClientConfig,
   RIALO_DEVNET_CHAIN,
-  RIALO_MAINNET_CHAIN
 } from "@rialo/ts-cdk";
 
-// Using preset chain configurations
+// Using a chain preset directly
 const client = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
 
-// Using getDefaultRialoClientConfig helper
-const config = getDefaultRialoClientConfig('mainnet');
-const mainnetClient = createRialoClient({
-  ...config,
-  transport: {
-    timeout: 30000,
-    maxRetries: 3,
-  }
-});
+// Or by network name — useful when network comes from config/env
+// const client = createRialoClient(getDefaultRialoClientConfig("devnet"));
 
-// Query methods
-const balance = await client.getBalance(publicKey);
-const accountInfo = await client.getAccountInfo(publicKey);
-const blockHeight = await client.getBlockHeight();
-const chainId = client.getChainIdentifier();
-
-// Get transaction info (returns blockHeight and optional error)
-const txInfo = await client.getTransaction(signature);
-if (txInfo) {
-  console.log(`Confirmed in block: ${txInfo.blockHeight}`);
-  if (txInfo.err) {
-    console.log(`Transaction failed: ${txInfo.err}`);
-  }
-}
+const configHashPrefix = await client.getConfigHashPrefix();  // required
 
-// Send transactions
-const signature = await client.sendTransaction(serializedTx);
+const transfer = transferInstruction(
+  keypair.publicKey,
+  recipientPubkey,
+  1_000_000n,       // amount in kelvin; 1 RLO = 1_000_000_000 kelvin
+);
 
-// Send and wait for confirmation
-const result = await client.sendAndConfirmTransaction(serializedTx);
-console.log(`Executed: ${result.executed}`);
+const tx = TransactionBuilder.create()
+  .setPayer(keypair.publicKey)
+  .setValidFrom(BigInt(Date.now()))
+  .setConfigHashPrefix(configHashPrefix)
+  .addInstruction(transfer)
+  .build();
 
-// Confirm an existing transaction
-const confirmed = await client.confirmTransaction(signature, {
-  maxRetries: 10,
-  retryDelay: 200,
-});
+const signedTx = tx.sign(keypair);
+const sig = await client.sendTransaction(signedTx.serialize());
+console.log("Signature:", sig.toString());
+```
 
-// Devnet/testnet only - request airdrop
-const airdropSig = await client.requestAirdrop(publicKey, 1_000_000_000n);
+### Multi-sig transactions
 
-// Request airdrop and wait for confirmation
-const airdropResult = await client.requestAirdropAndConfirm(
-  publicKey,
-  1_000_000_000n
-);
+```typescript
+// Each partial sign adds one signer's signature; isSigned() returns true when all
+// required signers have contributed.
+const partial = tx.partialSign(signer1);
+const complete = partial.partialSign(signer2);
+complete.ensureSigned();              // throws if any signature is missing
 
-// Get minimum balance for rent exemption
-const minBalance = await client.getMinimumBalanceForRentExemption(128);
+// Async signer interface (hardware wallets, browser extensions, etc.)
+const signedAsync = await tx.signWith(new KeypairSigner(keypair));
+```
 
-// Get fee for a message
-const fee = await client.getFeeForMessage(base64Message);
+### Deserialize a transaction
 
-// Batch query multiple accounts
-const accounts = await client.getMultipleAccounts([pubkey1, pubkey2]);
+`Transaction.deserialize` reconstructs a transaction from its wire bytes — useful for
+inspecting or re-signing transactions received from another party.
 
-// Get accounts by owner/program with pagination
-const result = await client.getAccountsByOwner(programId, { type: "programAccounts" });
+```typescript
+import { Transaction } from "@rialo/ts-cdk";
 
-// Workflow lineage traversal
-const lineage = await client.getWorkflowLineage({
-  signature: rootTxSignature,
-  maxDepth: 5,
-});
+// Reconstruct from wire bytes (e.g. received over a socket)
+const tx = Transaction.deserialize(wireBytes);
 
-// Get subscription for an account and nonce
-const sub = await client.getSubscription(accountPubkey, "my-nonce");
+// Inspect the compiled message
+for (const ix of tx.message.instructions) {
+  console.log("program:", ix.programId.toString());
+}
 
-// Get transactions triggered by a subscription
-const triggered = await client.getTriggeredTransactions(subscriptionPubkey);
+// Re-sign (e.g. when acting as co-signer)
+const reSigned = tx.partialSign(myKeypair);
 ```
 
-### Signers
+### Borsh serialization for instruction data
 
-Interface for different signing strategies.
+Use Borsh to encode typed parameters into the opaque `data` field of an `Instruction`.
 
 ```typescript
-import { KeypairSigner, type Signer } from "@rialo/ts-cdk";
+import { field, serialize, deserialize } from "@dao-xyz/borsh";
+import { Instruction, AccountMeta } from "@rialo/ts-cdk";
 
-// Keypair signer for local signing
-const signer = new KeypairSigner(keypair);
+class TransferParams {
+  @field({ type: "u64" }) amount!: bigint;
+  constructor(amount: bigint) { this.amount = amount; }
+}
 
-// Use signer interface
-const signature = await signer.sign(message);
-const pubkey = signer.publicKey();
+const params = new TransferParams(1_000_000n);
+const data = Buffer.from(serialize(params));
 
-// Implement custom signer for hardware wallets, etc.
-class CustomSigner implements Signer {
-  async sign(message: Uint8Array): Promise<Signature> {
-    // your signing logic
-  }
-  publicKey(): PublicKey {
-    // return public key
-  }
-}
+const ix = new Instruction({
+  programId: myProgramId,
+  accounts: [new AccountMeta({ pubkey: myAccount, isSigner: false, isWritable: true })],
+  data,
+});
 ```
 
-## Advanced Features
-
 ### Program Derived Addresses (PDAs)
 
-PDAs are deterministic addresses derived from seeds and a program ID. They are off the Ed25519 curve, meaning no private key exists for them - only the program can sign on their behalf.
+PDAs are off-curve addresses deterministically derived from seeds and a program ID.
+No private key exists; only the program can sign on their behalf.
 
 ```typescript
 import { PublicKey } from "@rialo/ts-cdk";
 
-// Find a PDA with automatic bump seed discovery
-const [vaultPda, vaultBump] = PublicKey.findProgramAddress(
+// Automatic bump discovery — returns [address, bump]
+const [vaultPda, bump] = PublicKey.findProgramAddress(
   ["vault", userPubkey.toBytes()],
-  programId
+  programId,
 );
 
-console.log(`Vault: ${vaultPda}, Bump: ${vaultBump}`);
-
-// Create PDA with known bump (more efficient for verification)
+// With known bump (more efficient)
 const pda = PublicKey.createProgramAddress(
-  ["metadata", mintPubkey.toBytes(), new Uint8Array([254])],
-  metadataProgramId
+  ["metadata", mintPubkey.toBytes(), new Uint8Array([bump])],
+  metadataProgramId,
 );
+```
 
-// Create derived address from base key (CAN be on curve)
-const derivedAddress = PublicKey.createWithSeed(
-  userPubkey,
-  "savings-account",
-  systemProgramId
-);
+> **Note:** Each seed must be ≤ 32 bytes; at most 16 seeds per derivation. String seeds
+> are UTF-8-encoded automatically.
+
+### Deploy a program
+
+```typescript
+import { ProgramDeployment } from "@rialo/ts-cdk";
+
+const deployment = new ProgramDeployment({
+  programData: fs.readFileSync("program.polkavm"),
+  programKeypair: programKeypair,
+  config: {
+    chunkSize: 900,         // bytes per upload chunk
+    maxRetries: 5,
+  },
+});
 
-// Check if an address is on the Ed25519 curve
-const isOnCurve = pubkey.isOnCurve();
+const programId = await deployment.deploy(client, payerKeypair);
+console.log("Program deployed:", programId.toString());
 ```
 
-**Seed Constraints:**
+### Encrypt a secret for TEE programs
 
-- Maximum 16 seeds per derivation
-- Each seed maximum 32 bytes
-- Seeds can be strings (UTF-8 encoded) or `Uint8Array`
+`RexValue` wraps a plain or HPKE-encrypted payload. Use it to pass sensitive data to
+programs that run inside a Trusted Execution Environment (TEE). The node's HPKE public
+key is fetched via `getSecretSharingPubkey()`; the CDK handles the HPKE encryption.
 
-### Hierarchical Deterministic Wallets
+```typescript
+import { RexValue } from "@rialo/ts-cdk";
+
+// 1. Fetch the TEE's HPKE public key from the node
+const skPub = await client.getSecretSharingPubkey();
+
+// 2. Encrypt your secret — RexValue.fromPlaintext performs HPKE encryption
+const plaintext = new TextEncoder().encode("Bearer sk-…");
+const rexValue = await RexValue.fromPlaintext(plaintext, skPub);
+
+// 3. Serialise as Borsh bytes and embed in your instruction data
+const borshBytes = rexValue.toBorsh();
+```
+
+To include unencrypted bytes (for non-sensitive payloads):
+
+```typescript
+const plain = RexValue.plain(new TextEncoder().encode("public-data"));
+const borshBytes = plain.toBorsh();
+```
 
-The SDK uses SLIP-0010 for Ed25519 key derivation with BIP44 paths.
+### Custom signer (hardware wallets)
 
 ```typescript
-// Coin type 756 (R=7, L=5, O=6 on phone keypad)
-const defaultPath = "m/44'/756'/0'/0'";
+import { type Signer, PublicKey, Signature } from "@rialo/ts-cdk";
+
+class LedgerSigner implements Signer {
+  async getPublicKey(): Promise<PublicKey> {
+    return PublicKey.fromBytes(await ledger.getPublicKey());
+  }
+  async signMessage(message: Uint8Array): Promise<Signature> {
+    const sigBytes = await ledger.sign(message);
+    return Signature.fromBytes(sigBytes);
+  }
+}
 
-// Derive multiple accounts
-const account0 = await mnemonic.toKeypair(0);
-const account1 = await mnemonic.toKeypair(1);
-const account2 = await mnemonic.toKeypair(2);
+const signedTx = await tx.signWith(new LedgerSigner());
 ```
 
-### Transaction Serialization
+### Subscription workflows (REX)
+
+REX subscriptions let a program trigger downstream transactions automatically. Use
+`getSubscription` to inspect an active subscription and `getTriggeredTransactions` to
+audit which transactions it has fired.
 
 ```typescript
-// Serialize signed transaction
-const bytes = signedTx.serialize();
+import { createRialoClient, RIALO_DEVNET_CHAIN } from "@rialo/ts-cdk";
 
-// Deserialize
-import { Transaction } from "@rialo/ts-cdk";
-const tx = Transaction.deserialize(bytes);
+const client = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
+
+// Look up a subscription by subscriber address and nonce
+const subscription = await client.getSubscription(subscriberPubkey, nonce);
+console.log("Topic:", subscription.topic);
+console.log("Kind:", subscription.kind);
 
-// Check signing status
-const isSigned = tx.isSigned();
-const sigCount = tx.getRequiredSignatureCount();
+// List the last 10 transactions triggered by this subscription account
+const triggered = await client.getTriggeredTransactions(subscriptionAccount, 10);
+for (const tx of triggered) {
+  console.log(`sig=${tx.signature}  block=${tx.blockNumber}`);
+}
 ```
 
-### Error Handling
+### Workflow lineage
+
+```typescript
+const lineage = await client.getWorkflowLineage(request);
+// lineage.nodes contains the DAG of related transactions.
+```
+
+## Error handling
 
 ```typescript
 import { RialoError, RialoErrorType } from "@rialo/ts-cdk";
 
 try {
-  await client.sendTransaction(tx);
-} catch (error) {
-  if (error instanceof RialoError) {
-    switch (error.type) {
+  await client.sendTransaction(signedTx.serialize());
+} catch (err) {
+  if (err instanceof RialoError) {
+    switch (err.type) {
+      case RialoErrorType.RPC:
+        console.error("Node error", err.details?.code, err.details?.message);
+        break;
       case RialoErrorType.NETWORK:
-        // Retry logic
+        console.error("Network failure:", err.cause);
         break;
       case RialoErrorType.INVALID_INPUT:
-        // Handle invalid input
-        break;
-      case RialoErrorType.RPC:
-        // RPC specific error
-        console.log(error.details); // RPC error details
+        console.error("Bad argument:", err.message);
         break;
+      default:
+        throw err;
     }
   }
 }
 ```
 
-### Keypair Security
-
-```typescript
-// Generate keypair
-const keypair = Keypair.generate();
-
-// Use for signing
-const signature = keypair.sign(message);
-
-// Securely dispose when done
-keypair.dispose(); // Zeros out private key in memory
-```
-
-## Network URLs
-
-```typescript
-import { 
-  URL_MAINNET,
-  URL_TESTNET,
-  URL_DEVNET,
-  URL_LOCALNET 
-} from "@rialo/ts-cdk";
-```
+### Error types
+
+| `RialoErrorType` | Condition |
+|---|---|
+| `RPC` | Node rejected the request |
+| `NETWORK` | HTTP/network failure |
+| `TRANSACTION` | Transaction build or signing error |
+| `WALLET` | Keypair load or create failure |
+| `ENCRYPTION` | HPKE encryption/decryption failure |
+| `BIP32` | HD key derivation error |
+| `INVALID_INPUT` | Invalid parameter or data |
+| `PARSE_PUBKEY` | Public key parse failure |
+| `INVALID_BLOCKHASH_FORMAT` | Blockhash format error |
+| `CONFIG` | Configuration load or parse failure |
+| `JSON` | JSON parse error |
+| `SERIALIZATION` | Borsh/bincode serialisation error |
+| `PASSWORD` | Password validation failure |
+
+## RPC reference
+
+| Method | Returns | Notes |
+|---|---|---|
+| `getConfigHashPrefix()` | `ConfigHashPrefix` | Required for every `TransactionBuilder` |
+| `getBalance(pubkey)` | `Kelvin` | Balance as `bigint` |
+| `sendTransaction(bytes, opts?)` | `Signature` | Submit signed bytes |
+| `sendAndConfirmTransaction(bytes, opts?)` | `ConfirmedTransaction` | Submit and poll |
+| `confirmTransaction(sig, opts?)` | `ConfirmedTransaction` | Poll by signature |
+| `getAccountInfo(pubkey)` | `AccountInfo` | Raw account data |
+| `getMultipleAccounts(pubkeys)` | `OptionalAccountInfo[]` | Batch query |
+| `getAccountsByOwner(owner, filter?)` | `[OwnerAccount[], PaginationInfo?]` | Program accounts |
+| `getBlockHeight()` | `bigint` | Finalized height |
+| `getTransaction(sig)` | `TransactionResponse` | By signature |
+| `getEpochInfo()` | `EpochInfo` | Current epoch |
+| `getSignaturesForAddress(pubkey)` | `SignatureInfo[]` | Transaction history for an account |
+| `requestAirdrop(pubkey, kelvin)` | `Signature` | Devnet/testnet only |
+| `requestAirdropAndConfirm(pubkey, kelvin)` | `ConfirmedTransaction` | Airdrop + wait |
+| `getFeeForMessage(base64Msg)` | `FeeResponse` | Estimate fee before sending |
+| `getMinimumBalanceForRentExemption(size)` | `bigint` | Rent-exempt threshold |
+| `getSecretSharingPubkey()` | `SecretSharingPubkey` | TEE HPKE public key |
+| `getWorkflowLineage(req)` | `GetWorkflowLineageResponse` | Workflow DAG traversal |
+| `getSubscription(subscriber, nonce)` | `Subscription` | REX subscription lookup |
+| `getTriggeredTransactions(account, limit?)` | `TriggeredTransaction[]` | Subscription-triggered txs |
 
 ## Constants
 
 ```typescript
 import {
-  KELVIN_PER_RLO,        // 1_000_000_000
-  SYSTEM_PROGRAM_ID,      // "11111111111111111111111111111111"
-  PUBLIC_KEY_LENGTH,      // 32
-  SECRET_KEY_LENGTH,      // 32
-  SIGNATURE_LENGTH,       // 64
+  KELVIN_PER_RLO,         // 1_000_000_000
+  SYSTEM_PROGRAM_ID,       // "11111111111111111111111111111111"
+  PUBLIC_KEY_LENGTH,       // 32
+  SECRET_KEY_LENGTH,       // 32
+  SIGNATURE_LENGTH,        // 64
+  URL_MAINNET,             // "https://mainnet.rialo.io:4101"
+  URL_TESTNET,             // "https://testnet.rialo.io:4101"
+  URL_DEVNET,              // "https://devnet.rialo.io:4101"
+  URL_LOCALNET,            // "http://localhost:4104"
 } from "@rialo/ts-cdk";
+
+// Currency conversion (KELVIN_PER_RLO is a number; use BigInt() when passing to RPC methods)
+const kelvin = BigInt(Math.round(1.5 * KELVIN_PER_RLO));   // 1.5 RLO → 1_500_000_000n kelvin
 ```
 
-## Examples
+## Caveats
 
-The `examples/` directory contains complete working examples:
+- **`configHashPrefix`** — `TransactionBuilder.setConfigHashPrefix()` is required.
+  Omitting it or using a stale value causes the node to reject the transaction with a
+  replay-protection error.
 
-- `01-basic-operations.ts` - Keypairs, signatures, and basic types
-- `02-wallet-management.ts` - HD wallet patterns (reference implementation)
-- `03-transaction-operations.ts` - Transaction building and signing
-- `05-alice-bob-transaction.ts` - Complete transfer workflow with RPC
+- **Currency units** — all RPC amounts are in *kelvin*; 1 RLO = `KELVIN_PER_RLO`
+  (1 000 000 000) kelvin. The `transferInstruction` helper takes kelvin as `bigint`.
 
-Run examples:
+- **Derivation path** — Rialo uses BIP44 coin type 756. `Mnemonic.toKeypair(index)` uses
+  `m/44'/756'/{index}'/0'`. Keys derived on other coin types are not compatible.
 
-```bash
-pnpm tsx examples/01-basic-operations.ts
-```
+- **Keypair disposal** — call `keypair.dispose()` (and `keyring.dispose()`) when the
+  keypair is no longer needed. After disposal, signing methods throw `CryptoError`.
 
-## Development
+- **PDA seeds** — strings are UTF-8-encoded; `Uint8Array` seeds are used as-is. A seed
+  exceeding 32 bytes throws `CryptoError.MAX_SEED_LENGTH_EXCEEDED`.
 
-```bash
-# Install dependencies
-pnpm install
+- **Node.js version** — requires Node.js ≥ 18 for the native `crypto` module and
+  `TextEncoder`/`TextDecoder` globals.
 
-# Build
-pnpm build
+- **`AccountMetaTable`** — used internally by `TransactionBuilder` to deduplicate account
+  references in a compiled `Message`. Constructing it manually is only needed for
+  advanced multi-program transactions.
 
-# Test
-pnpm test
+## Development
 
-# Lint
-pnpm lint
+```bash
+pnpm install
+pnpm build       # compiles ESM + CJS bundles to dist/
+pnpm test        # runs vitest suite
+pnpm lint        # biome check
 ```
 
-## Security
-
-- Private keys stored as `Uint8Array` in memory
-- Uses `@noble/curves` and `@noble/hashes` for cryptography
-- Call `keypair.dispose()` to zero out private keys
-- Never commit private keys or mnemonics
-- Use environment variables for sensitive data
-
-## License
+## See also
 
-Apache License 2.0
+- [`rialo-cdk`](../rialo-rs-cdk/README.md) — underlying Rust crate; source of truth for wire format and error codes
+- [`rialo-py-cdk`](../rialo-py-cdk/README.md) — Python bindings with equivalent API surface
+- `developer-frameworks/cdk/spec.wit` — WIT specification from which the RPC surface is derived
+- `developer-frameworks/cdk/rialo-ts-cdk/examples/` — runnable end-to-end examples