Rialo TypeScript CDK

A TypeScript library for interacting with the Rialo blockchain. Provides cryptographic primitives, transaction building, and RPC client for blockchain communication.

Installation

npm install @rialo/ts-cdk

Quick Start

Create a keypair and sign a message

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

import { createRialoClient, RIALO_DEVNET_CHAIN } from "@rialo/ts-cdk";

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

import { TransactionBuilder, transferInstruction } from "@rialo/ts-cdk";

// transaction valid from
const validFrom = 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)
  .setValidFrom(validFrom)
  .addInstruction(transfer)
  .build();

const signedTx = tx.sign(keypair);

// Send to network
const signature = await client.sendTransaction(signedTx.serialize());

Generate and use mnemonics

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.

import { Keypair, PublicKey, Signature } 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);

// validFrom for transactions
const validFrom = BigInt(Date.now());

Transactions

Build and sign transactions with instructions.

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)
  .setValidFrom(validFrom)
  .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.

import {
  createRialoClient,
  getDefaultRialoClientConfig,
  RIALO_DEVNET_CHAIN,
  RIALO_MAINNET_CHAIN
} from "@rialo/ts-cdk";

// Using preset chain configurations
const client = createRialoClient({ chain: RIALO_DEVNET_CHAIN });

// Using getDefaultRialoClientConfig helper
const config = getDefaultRialoClientConfig('mainnet');
const mainnetClient = createRialoClient({
  ...config,
  transport: {
    timeout: 30000,
    maxRetries: 3,
  }
});

// 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}`);
  }
}

// Send transactions
const signature = await client.sendTransaction(serializedTx);

// Send and wait for confirmation
const result = await client.sendAndConfirmTransaction(serializedTx);
console.log(`Executed: ${result.executed}`);

// Confirm an existing transaction
const confirmed = await client.confirmTransaction(signature, {
  maxRetries: 10,
  retryDelay: 200,
});

// Devnet/testnet only - request airdrop
const airdropSig = await client.requestAirdrop(publicKey, 1_000_000_000n);

// Request airdrop and wait for confirmation
const airdropResult = await client.requestAirdropAndConfirm(
  publicKey,
  1_000_000_000n
);

Signers

Interface for different signing strategies.

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.

// 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

// 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

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

// 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

import { 
  URL_MAINNET,
  URL_TESTNET,
  URL_DEVNET,
  URL_LOCALNET 
} from "@rialo/ts-cdk";

Constants

import {
  KELVIN_PER_RLO,        // 1_000_000_000
  SYSTEM_PROGRAM_ID,      // "11111111111111111111111111111111"
  PUBLIC_KEY_LENGTH,      // 32
  SECRET_KEY_LENGTH,      // 32
  SIGNATURE_LENGTH,       // 64
} 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:

pnpm tsx examples/01-basic-operations.ts

Development

# 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