@kokosro/ledger

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

Server-side ledger execution, state management, and JSON-RPC server for the TypeScript blockchain.

Installation

npm install @kokosro/ledger viem

Description

This package provides the core blockchain execution engine, including:

• Transaction processing and validation
• Contract execution system
• State management with Merkle Patricia Trie
• Block production and validation
• JSON-RPC server for remote access
• Persistence with LevelDB
• Mempool and fee market

Designed for private blockchain applications, API cost tracking systems, and permissioned execution environments.

Quick Start

Embedded Mode (Simple)

import {
  createLedger,
  registerContractFunction,
  getEmptyAccount,
  TxKinds,
} from "@kokosro/ledger";
import { privateKeyToAccount } from "viem/accounts";

// Register contract functions
registerContractFunction(
  "myContract",
  async ({ caller, address, state, value, data }) => {
    // Your contract logic here
    const count = state.readStorage("count") || "0";
    await state.writeStorage("count", String(parseInt(count) + 1));

    return {
      success: true,
      computationCost: 5000n,
      returnData: "0x",
    };
  }
);

// Create blockchain
const rootAccount = privateKeyToAccount("0x...");
const validatorAccount = privateKeyToAccount("0x...");

const ledger = await createLedger({
  chainParams: {
    chainId: 1337n,
    root: rootAccount.address,
    targetMempoolSize: 100,
    feeBase: 1000n,
    feeSlope: 10n,
    blockSpeedTarget: 5000,
  },
  validators: [validatorAccount.address],
  genesis: [
    {
      ...getEmptyAccount(rootAccount.address),
      balance: 1_000_000n,
    },
  ],
});

// Submit transaction
await ledger.submitTransaction(signedTx);

// Propose block (validator only)
await ledger.proposeBlock(validatorAccount.address);

JSON-RPC Server Mode (Production)

import { createLedger, startJsonRpcServer } from "@kokosro/ledger";

const ledger = await createLedger({
  chainParams: {
    /* ... */
  },
  validators: [validatorAddress],
  genesis: [
    /* ... */
  ],
  persistence: {
    enabled: true,
    dbPath: "./data/ledger",
  },
});

// Start RPC server
const server = await startJsonRpcServer(ledger, {
  port: 37847,
  host: "0.0.0.0",
  cors: true,
});

console.log("JSON-RPC server running at http://localhost:37847");

Key APIs

Ledger Creation

const ledger = await createLedger(config: LedgerConfig): Promise<Ledger>

Contract System

// Register contract function
registerContractFunction(
  name: string,
  handler: ContractHandler
): void

// Declare contract with metadata
declareContract(definition: HumanReadableContract): void

// Example contracts provided
import {
  counterContractDefinition,
  erc20ContractDefinition,
  storageContractDefinition,
  greeterContract,
} from '@kokosro/ledger';

Transaction Utilities

validateTransaction(tx: TxSigned, state: State): Promise<void>
executeTransaction(tx: TxSigned, state: State, context: BlockContext): Promise<TxExecutionResult>
calculateTxFee(tx: TxSigned, baseFee: bigint): bigint
computeContractAddress(deployer: Address, nonce: bigint): Address

Ledger Methods

interface Ledger {
  submitTransaction(tx: TxSigned): Promise<void>;
  proposeBlock(proposer: Address): Promise<Block>;
  getAccount(address: Address): Promise<Account>;
  getBlock(height: bigint): Promise<Block | null>;
  getLatestBlock(): Promise<Block>;
  getChainHeight(): Promise<bigint>;
  getCurrentValidator(): Address;
  getBaseFee(): bigint;
  getTotalSupply(): Promise<bigint>;
  getPendingTransactions(): TxSigned[];
  getMempoolSize(): number;
}

JSON-RPC Server

// Start server
startJsonRpcServer(ledger: Ledger, config?: ServerConfig): Promise<Server>

// Stop server
stopJsonRpcServer(server: Server): Promise<void>

// Handle individual requests
handleJsonRpcRequest(request: JsonRpcRequest, methods: RpcMethodHandler): Promise<JsonRpcResponse>

State Management

const state = await createState(params: CreateStateParams): Promise<State>
const emptyAccount = getEmptyAccount(address: Address): Account

Block & Validator Utilities

createBlock(params): Block
createGenesisBlock(params): Block
validateBlock(block: Block, state: State): Promise<void>
getValidatorForHeight(height: bigint, validators: Address[]): Address
canProposeBlock(proposer: Address, validators: Address[], blockTime: number): boolean

Production Features

Persistence

import { createLedger, createLevelDB } from "@kokosro/ledger";

const ledger = await createLedger({
  // ... config
  persistence: {
    enabled: true,
    dbPath: "./data/ledger",
  },
});

Recovery

import { ChainRecovery } from "@kokosro/ledger";

const recovery = new ChainRecovery(db);
const result = await recovery.loadChain();

if (!result.isNewChain) {
  console.log(`Resumed chain at height ${result.chainHeight}`);
}

Metrics & Monitoring

import { Metrics } from "@kokosro/ledger";

const metrics = new Metrics();
metrics.recordTx(txHash, success);
metrics.recordBlock(blockTime);

const stats = metrics.getStats();
console.log(`TPS: ${stats.tps}, Avg Block Time: ${stats.avgBlockTime}ms`);

Snapshots

import { SnapshotManager } from "@kokosro/ledger";

const snapshots = new SnapshotManager(db, { interval: 1000, keep: 10 });
await snapshots.createSnapshot(height, stateRoot);
const snapshot = await snapshots.getLatestSnapshot();

Transaction Types

• MINT: Create new tokens (root account only)
• DEPLOY: Deploy a contract
• CALL: Execute contract or transfer value
• BURN: Burn tokens
• CHANGE_ROOT: Change root account
• ADD_VALIDATOR: Add validator
• REMOVE_VALIDATOR: Remove validator

Fee Model

Total Fee = Computation Cost + Congestion Fee
Congestion Fee = feeBase + (feeSlope × mempoolSize)

Fees are burned (destroyed), reducing total supply.

Related Packages

• @kokosro/ledger-common - Shared types and utilities
• @kokosro/ledger-client - RPC client for browser/Node.js

License

ISC © 2025 kokosro