@rialo/ts-cdk 0.1.0

package/README.md

@@ -0,0 +1,350 @@
+# Rialo TypeScript 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.
+
+## Installation
+
+```bash
+npm install @rialo/ts-cdk
+```
+
+## Quick Start
+
+### Create a keypair and sign a message
+
+```typescript
+import { Keypair } from "@rialo/ts-cdk";
+
+const keypair = Keypair.generate();
+console.log("Address:", keypair.publicKey.toString());
+
+const message = new TextEncoder().encode("Hello Rialo");
+const signature = keypair.sign(message);
+const isValid = keypair.verify(message, signature);
+```
+
+### Connect to the blockchain
+
+```typescript
+import { createRialoClient, URL_DEVNET } from "@rialo/ts-cdk";
+
+const client = createRialoClient(URL_DEVNET);
+
+// Query blockchain
+const balance = await client.getBalance(keypair.publicKey);
+const height = await client.getBlockHeight();
+const blockhash = await client.getLatestBlockhash();
+```
+
+### Build and send a transaction
+
+```typescript
+import { TransactionBuilder, transferInstruction } from "@rialo/ts-cdk";
+
+// Get blockhash for replay protection
+const blockhash = await client.getLatestBlockhash();
+
+// transaction creation time
+const txCreationTime = BigInt(Date.now());
+
+// Create transfer instruction
+const transfer = transferInstruction(
+  keypair.publicKey,
+  recipientAddress,
+  BigInt(1_000_000) // amount in kelvins
+);
+
+// Build and sign transaction
+const tx = TransactionBuilder.create()
+  .setPayer(keypair.publicKey)
+  .setRecentBlockhash(blockhash)
+  .setTxCreationTime(txCreationTime)
+  .addInstruction(transfer)
+  .build();
+
+const signedTx = tx.sign(keypair);
+
+// Send to network
+const signature = await client.sendTransaction(signedTx.serialize());
+```
+
+### Generate and use mnemonics
+
+```typescript
+import { Mnemonic } from "@rialo/ts-cdk";
+
+// Generate 12-word mnemonic
+const mnemonic = Mnemonic.generate();
+
+// Derive keypair (default path: m/44'/756'/0'/0')
+const keypair = await mnemonic.toKeypair();
+
+// Use custom derivation path
+const keypair2 = await mnemonic.toKeypair("m/44'/756'/0'/1'");
+
+// Restore from existing mnemonic
+const restored = Mnemonic.fromPhrase("your twelve word mnemonic phrase here...");
+const restoredKeypair = await restored.toKeypair();
+```
+
+## Core Modules
+
+### Crypto
+
+Ed25519 cryptographic primitives for key management and signing.
+
+```typescript
+import { Keypair, PublicKey, Signature, Blockhash } from "@rialo/ts-cdk";
+
+// Generate random keypair
+const keypair = Keypair.generate();
+
+// From existing secret key
+const keypair = Keypair.fromSecretKey(secretBytes);
+
+// Public key operations
+const pubkey = PublicKey.fromString("base58string");
+const address = pubkey.toString();
+const bytes = pubkey.toBytes();
+
+// Signature operations
+const sig = Signature.fromBytes(signatureBytes);
+
+// Blockhash for transactions
+const blockhash = Blockhash.fromString("base58blockhash");
+
+// txCreationTime for transactions
+const txCreationTime = BigInt(Date.now());
+```
+
+### Transactions
+
+Build and sign transactions with instructions.
+
+```typescript
+import { 
+  TransactionBuilder, 
+  transferInstruction,
+  type Instruction,
+  type AccountMeta 
+} from "@rialo/ts-cdk";
+
+// Simple transfer
+const transfer = transferInstruction(from, to, amount);
+
+// 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
+};
+
+// Build transaction
+const tx = TransactionBuilder.create()
+  .setPayer(payerPublicKey)
+  .setRecentBlockhash(blockhash)
+  .setTxCreationTime(txCreationTime)
+  .addInstruction(instruction)
+  .build();
+
+// Single signer
+const signed = tx.sign(keypair);
+
+// Multi-sig
+const partial = tx.partialSign(signer1);
+const complete = partial.partialSign(signer2);
+
+// Serialize for network
+const bytes = signed.serialize();
+```
+
+### RPC Client
+
+Communicate with Rialo blockchain nodes.
+
+```typescript
+import { createRialoClient, URL_DEVNET, URL_MAINNET } from "@rialo/ts-cdk";
+
+const client = createRialoClient(URL_DEVNET, {
+  timeout: 30000,
+  maxRetries: 3,
+});
+
+// Query methods
+const balance = await client.getBalance(publicKey);
+const accountInfo = await client.getAccountInfo(publicKey);
+const blockHeight = await client.getBlockHeight();
+const blockhash = await client.getLatestBlockhash();
+const txInfo = await client.getTransaction(signature);
+
+// Send transactions
+const signature = await client.sendTransaction(serializedTx);
+
+// Devnet only - request airdrop
+await client.requestAirdrop(publicKey, BigInt(1_000_000_000));
+```
+
+### Signers
+
+Interface for different signing strategies.
+
+```typescript
+import { KeypairSigner, type Signer } from "@rialo/ts-cdk";
+
+// Keypair signer for local signing
+const signer = new KeypairSigner(keypair);
+
+// Use signer interface
+const signature = await signer.sign(message);
+const pubkey = signer.publicKey();
+
+// 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
+  }
+}
+```
+
+## Advanced Features
+
+### Hierarchical Deterministic Wallets
+
+The SDK uses SLIP-0010 for Ed25519 key derivation with BIP44 paths.
+
+```typescript
+// Coin type 756 (R=7, L=5, O=6 on phone keypad)
+const defaultPath = "m/44'/756'/0'/0'";
+
+// Derive multiple accounts
+const account0 = await mnemonic.toKeypair(0);
+const account1 = await mnemonic.toKeypair(1);
+const account2 = await mnemonic.toKeypair(2);
+```
+
+### Transaction Serialization
+
+```typescript
+// Serialize signed transaction
+const bytes = signedTx.serialize();
+
+// Deserialize
+import { Transaction } from "@rialo/ts-cdk";
+const tx = Transaction.deserialize(bytes);
+
+// Check signing status
+const isSigned = tx.isSigned();
+const sigCount = tx.getRequiredSignatureCount();
+```
+
+### Error Handling
+
+```typescript
+import { RialoError, RialoErrorType } from "@rialo/ts-cdk";
+
+try {
+  await client.sendTransaction(tx);
+} catch (error) {
+  if (error instanceof RialoError) {
+    switch (error.type) {
+      case RialoErrorType.NETWORK:
+        // Retry logic
+        break;
+      case RialoErrorType.INVALID_INPUT:
+        // Handle invalid input
+        break;
+      case RialoErrorType.RPC:
+        // RPC specific error
+        console.log(error.details); // RPC error details
+        break;
+    }
+  }
+}
+```
+
+### 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";
+```
+
+## 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
+  BLOCKHASH_LENGTH,       // 32
+} from "@rialo/ts-cdk";
+```
+
+## Examples
+
+The `examples/` directory contains complete working examples:
+
+- `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
+
+Run examples:
+```bash
+pnpm tsx examples/01-basic-operations.ts
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Lint
+pnpm lint
+```
+
+## 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
+
+Apache License 2.0