@kokosro/ledger-common

⚠️ Experimental: This package is in active development and the API may change.

Shared types, encoding utilities, and platform-agnostic code for the TypeScript ledger ecosystem.

Installation

npm install @kokosro/ledger-common viem

Description

This package provides the core types and utilities shared across the ledger ecosystem. It contains no blockchain execution logic, making it lightweight and suitable for use in both Node.js and browser environments.

Exports

Core Types

import type {
  Account, // Account structure with balance, nonce, code, storage
  AccountState, // Account state management interface
  TxKind, // Transaction type ('MINT' | 'DEPLOY' | 'CALL' | 'BURN' | 'CHANGE_ROOT' | 'ADD_VALIDATOR' | 'REMOVE_VALIDATOR')
  TxUnsigned, // Unsigned transaction structure
  TxSigned, // Signed transaction with signature
  Block, // Complete block with header and transactions
  BlockHeader, // Block header with metadata
  Precommit, // Validator precommit
  State, // State management interface
  ChainParams, // Chain configuration parameters
  CreateStateParams, // State creation parameters
} from "@kokosro/ledger-common";

import { TxKinds } from "@kokosro/ledger-common"; // Transaction kind constants

Encoding Utilities

import {
  getTxSigningHash, // Get hash for transaction signing
  recoverSender, // Recover sender address from signed transaction
  signTransaction, // Sign a transaction with private key
} from "@kokosro/ledger-common";

Network Types

import type {
  NetworkInterface, // Network layer interface
  NetworkMessage, // Generic network message
  ProposeBlockMessage, // Block proposal message
  TransactionMessage, // Transaction broadcast message
  SyncRequestMessage, // Sync request message
  SyncResponseMessage, // Sync response message
  PeerDiscoveryMessage, // Peer discovery message
  HeartbeatMessage, // Heartbeat message
  Peer, // Peer information
  MessageHandler, // Message handler type
} from "@kokosro/ledger-common";

import { MessageType, createMessage } from "@kokosro/ledger-common";

Usage Examples

Signing Transactions

import { signTransaction, getTxSigningHash } from "@kokosro/ledger-common";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");

const unsignedTx = {
  chainId: 1337n,
  kind: "CALL",
  from: account.address,
  to: "0x...",
  value: 1000n,
  data: "0x",
  nonce: 0n,
  computationLimit: 1000000n,
};

const signedTx = await signTransaction(unsignedTx, account);

Working with Types

import type { Account, Block, TxSigned } from "@kokosro/ledger-common";
import { TxKinds } from "@kokosro/ledger-common";

const account: Account = {
  address: "0x...",
  balance: 1000000n,
  nonce: 0n,
  code: null,
  storage: {},
};

// Check transaction kind
if (tx.kind === TxKinds.CALL) {
  // Handle call transaction
}

Related Packages

• @kokosro/ledger - Server-side ledger execution and RPC server
• @kokosro/ledger-client - Lightweight RPC client for browser/Node.js

License

ISC © 2025 kokosro