Blueprint Node

Local Test Node for TON Developers

Blueprint Node is a local blockchain test node designed for use in smart contract development environments based on @ton/blueprint. Built on top of @ton/sandbox, it enables developers to test contracts under conditions similar to the real TON blockchain.

You can fork from the mainnet or testnet, or spin up a completely fresh local chain. It provides the same JSON-RPC interface as the TON API, along with additional test-oriented methods.

⚡ Quick Start

Installation

npm install @factorial-finance/blueprint-node

Enable Plugin in Blueprint CLI

Add NodePlugin to your blueprint.config.ts file:

import { Config } from '@ton/blueprint';
import { NodePlugin } from '@factorial-finance/blueprint-node';

export const config: Config = {
  plugins: [new NodePlugin()],
};

NodePlugin enables local node functionality in the Blueprint CLI.

Run Local Node

# Default launch (http://localhost:8545/jsonRPC)
npx blueprint node

# Fork from mainnet with custom port and logging
npx blueprint node --fork mainnet --port 8080 --host 0.0.0.0 --log-level debug

Use --fork mainnet or --fork testnet to replicate the real network state locally. See this section of the @ton/sandbox README for more info.

Connect to Client

Once the node is running, connect using TonClient or LocalTonClient:

import { TonClient } from "@ton/ton";

const client = new TonClient({
  endpoint: "http://localhost:8545/jsonRPC",
});

You can now send RPC requests just like on the actual TON network, enabling fork-based testing and debugging.

📡 JSON-RPC API Methods

Blueprint Node supports the TON API's JSON-RPC 2.0 interface, with additional test-friendly extensions. Some network-only methods are not supported.

📋 Available API Methods

• sendBoc(boc) → { "@type": "ok" }
• runGetMethod(address, method, stack) → GetMethodResult
• getAddressInformation(address) → ContractState
• getTransactions(address, limit, lt?, hash?) → Transaction[]
• getTransaction(address, lt, hash) → Transaction
• tryLocateResultTx(source, destination, created_lt) → Transaction
• tryLocateSourceTx(source, destination, created_lt) → Transaction

📋 Test API Methods

These methods are only available on the local node for test purposes.

• setBalance(address, balance) → { "@type": "ok" }
• increaseBalance(address, amount) → { "@type": "ok" }
• setAccountCode(address, code) → { "@type": "ok" }
• setAccountData(address, data) → { "@type": "ok" }
• addLibrary(hash, lib) → { "@type": "ok" }
• setLibraries(libs) → { "@type": "ok" }
• getLibraries() → cell

📋 Not Available API Methods

These network-specific methods are not available in the local node.

• getMasterchainInfo() → MasterchainInfo
• getShards(seqno) → ShardInfo[]
• estimateFee(address, args) → FeeInfo
• getBlockTransactions(workchain, seqno, shard) → BlockTransactions

Extended Client: LocalTonClient

Blueprint Node also provides a convenient wrapper, LocalTonClient, which extends TonClient with blockchain state manipulation features.

import { LocalTonClient } from "@factorial-finance/blueprint-node";

const localTonClient = new LocalTonClient({
  endpoint: "http://localhost:8545/jsonRPC",
});

LocalTonClient behaves just like a normal TON client, but includes additional methods for testing.

🧪 Test API Usage Examples

The following methods are useful for smart contract and integration testing in a local forked environment.

Balance Manipulation

await localTonClient.setBalance(address, balance);
await localTonClient.increaseBalance(address, amount);
const balance = await localTonClient.getBalance(address);

Account State Manipulation

await localTonClient.setAccountCode(address, codeCell);
await localTonClient.setAccountData(address, dataCell);
const state = await localTonClient.getContractState(address);

Library Manipulation

await localTonClient.addLibrary(libraryCell);
await localTonClient.setLibraries(librariesCell);
const libraries = await localTonClient.getLibraries();

All test methods are available only on the local node and must be used for testing purposes only.

🔍 Transaction Visualization & Contract Aliases

Blueprint Node provides powerful debugging features with transaction tree visualization and contract alias system.

Transaction Tree Visualization

When transactions are executed, Blueprint Node displays them in a hierarchical tree format showing parent-child relationships:

[WalletContractV5R1] EQDB...bJT0o (A) → AuthSignedExternal(0x7369676e) DEPLOYED
 └─ [WTONWallet] EQAa...QhlR (B) → ExternalTransfer(0x5db0ab7)
     ├─ [BasicPool] EQCr...iiNx (C) → TransferNotification(0x7362d09c)
     │   ├─ [Unknown] EQCz...sHg (D) → UpdateAccountStatus(0x1c5ee1c3) DEPLOYED
     │   │   └─ [WalletContractV5R1] EQDB...bJT0o (A) → Excess(0xd53276db)
     │   └─ [WalletContractV5R1] EQDB...bJT0o (A) → ActionNotification(0xa1b21e8b)
     └─ [WalletContractV5R1] EQDB...bJT0o (A) → Excess(0xd53276db)

This helps you understand complex transaction flows and debug multi-contract interactions.

Contract Alias System

Blueprint Node automatically identifies contracts by their code hash and displays human-readable names instead of addresses.

Automatic Contract Discovery

The system automatically:

1. Compiles all *.compile.ts files in the wrappers directory to obtain code hashes
2. Parses TypeScript wrapper files to extract static Op and Error definitions
3. Maps code hashes to contract names for automatic identification

Automatic Op/Error Code Extraction

Define opcodes and error codes as static properties in your wrapper classes:

// wrappers/JettonMinter.ts
export class JettonMinter implements Contract {
  constructor(
    readonly address: Address,
    readonly init?: { code: Cell; data: Cell }
  ) {}

  // These will be automatically parsed and registered
  static Op = {
    Mint: 21,
    InternalTransfer: 0x178d4519,
  };

  static Error = {
    NotEnoughGas: 74,
  };
}

The parser will automatically:

• Extract all values from static Op, static Ops, static Opcode, or static Opcodes
• Extract all values from static Error, static Errors, static ErrorCode, or static ErrorCodes
• Support various formats: decimal (123), hex (0x7b)

For example, if your contracts have the opcodes and error codes defined as shown above, the transaction logs will display human-readable names instead of raw numbers:

[JettonMinter] EQD2...8Fzp (A) → Mint (0x15)
 └─ [JettonWallet] EQCM...WzSh (B) → InternalTransfer(0x178d4519)
     └─ [JettonWallet] EQAs...ub-O (C) ✗ NotEnoughGas(74)

Without these definitions or wrapper files, the same transaction would show:

[Unknown] EQD2...8Fzp (A) → UnknownOp:0x15
 └─ [Unknown] EQCM...WzSh (B) → UnknownOp:0x178d4519
     └─ [Unknown] EQAs...ub-O (C) ✗ error:74

Custom Alias Configuration

While opcodes and error codes are automatically extracted from wrapper classes, you can define custom aliases in blueprint.config.ts for external contracts or global definitions:

export const aliases = {
  // Map addresses to contract names
  addresses: {
    EQCrEHHG4Ff8TD3PzuH5tFSwHBD3zxeXaosz48jGLebwiiNx: "BasicPool",
    EQBLqy6raQAciiY39flZXDPMpUf5lvugil_4n_vpIostDVkG: "RedstoneV0",
  },

  // Map code hashes to contract names (optional if using .compile.ts)
  codeHashes: {
    "a1b2c3d4...": "MyCustomContract",
  },

  // Define custom opcodes (merged with auto-parsed ones)
  opcodes: {
    TakeAggregatedPool: 0x75a40ce7,
    UpdatePrice: 0x12345678,
  },

  // Define custom error codes (merged with auto-parsed ones)
  errorCodes: {
    InsufficientBalance: 0x6780b0d9,
    Unauthorized: 0x87654321,
  },
};

💰 Predefined Test Wallets

Blueprint Node provides 10 predefined test wallets for immediate use. Each wallet is in V5R1 format and is preloaded with 10,000 TON at startup.

import { testWallets } from "@factorial-finance/blueprint-node";

console.log(testWallets.mnemonic); // common mnemonic

testWallets.subWallets.forEach((wallet, index) => {
  console.log(`Wallet ${index}: ${wallet.address}`);
});

🔑 Mnemonic: test test test test test test test test test test test junk

Wallet Addresses

#0: EQDBGP2gt1nErQ_DEmtH6qkJW3Adk-EtlUOltPuRRQ_bJT0o
#1: EQAs-k0cKlb64C8xdatIAMn0zu7MocQgeG7xyDYvyulvub-O
#2: EQCBsMxrbwIBJ4P2qFT4GGlu4EJlkxpmodHn-jUa7_FDMIRH
#3: EQCrgYwYH3N1T321viqvZrjCdrAs3rlgzhce605wl1k5K23H
#4: EQA7LJ2KQ2nouSZ5EGShPGqk-O3DInb6ce9YR8nQFmC1QxRl
#5: EQCuPOXXII3o4u8sxOQTkbK618bC-7LY9ac2IYF2DT0Moog6
#6: EQA5awHocQ9xupBmOSpv3cqPqK5eM0ecLTmHwkPLDuQxWhr2
#7: EQB8KhyWNK3ZDGskyv06Phdwwv3c5Qq9k9hsYhJ3Ylnb_KNs
#8: EQD04snFZak9TOFGz8TwTmQt5WWgCdzaQjQrHCgU7RGdPiFn
#9: EQBf2rXty2Crd4QXaHKE652g5YHZ_xK-wVIA8vE6d_b1dApf

⚠️ These wallets are based on a public mnemonic and must not be used on the actual TON network.