@factorial-finance/blueprint-node/README.md

blueprint-node-plugin

# 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`](https://github.com/ton-org/blueprint). Built on top of [`@ton/sandbox`](https://github.com/ton-org/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.

<img src="./docs/main.png" alt="Blueprint Node Screen" width="700" />

## ⚡ 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](https://github.com/ton-org/sandbox?tab=readme-ov-file#performing-testing-on-contracts-from-a-real-network) 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:

```typescript
// 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:

```typescript
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.