npm package: @ston-fi/blueprint-utils
Description: A collection of helper functions for TON blueprint
Latest version: 0.14.1

# STON.fi Blueprint Utils
[![TON](https://img.shields.io/badge/based%20on-TON-blue)](https://ton.org/) [![License](https://img.shields.io/badge/license-MIT-brightgreen)](https://opensource.org/licenses/MIT)

A collection of helpers to work with `@ton/blueprint`

## Installation

To install this package use

```bash
npm install -D @ston-fi/blueprint-utils
```

or via yarn

```bash
yarn add @ston-fi/blueprint-utils
```
## Usage

The package consists of various different modules that represent either a collection of useful helper functions or a class with extensive functionality. Below are some of the notable modules:

### Sandbox Graph

The modules is designed to create mermaid md graph from local sandbox transactions. Additional data like mapping of addresses and op codes to human-readable labels, storage and message parsers can be fed into the graph to make it more useful.

#### Example

```ts
import { 
    SandboxGraph, 
    toGraphMap, 
    parseOp, 
    parseErrors, 
    nftMinterOpcodes,
    stdFtOpCodes,
    stdNftOpCodes,
    nftOpcodes,
    jWalletOpcodes,
    jMinterOpcodes,
    tvmErrorCodes,
} from "@ston-fi/blueprint-utils";

const GRAPH = new SandboxGraph({
    opMap: toGraphMap({
        ...nftMinterOpcodes,
        ...stdFtOpCodes,
        ...stdNftOpCodes,
        ...nftOpcodes,
        ...jWalletOpcodes,
        ...jMinterOpcodes,
        ...parseOp("contracts/common/op.fc")
    }),
    errMap: toGraphMap({
        ...tvmErrorCodes,
        ...parseErrors("contracts/common/errors.fc"),
    }),
    directionType: "bidirectional",
    chartType: "LR",
});
```

### Lib Builder

The module provides several helper functions to use masterchain libs on-chain and in the sandbox

#### Example

```ts
import { compile } from '@ton/blueprint';
import { Blockchain } from '@ton/sandbox';
import { buildLibs, buildLibFromCell } from "@ston-fi/blueprint-utils";

const _code = {
    contract1: await compile('YourContractName1'),
    contract2: await compile('YourContractName2'),
}

// lib Cell for Sandbox
const myLibs = buildLibs(_code)

// code Cells used in contracts
const code = {
    contract1: buildLibFromCell(_code.contract1),
    contract2: buildLibFromCell(_code.contract2),
}

const bc = await Blockchain.create()
bc.libs = myLibs

```

### Wrappers

The module contains an abstract implementation of common functions for the base `Contract` interface, as well as more specific one from Jetton standard.

#### Example

```ts
import {
    beginCell,
    Cell,
    ContractProvider,
    Sender,
    SendMode,
    Slice
} from '@ton/core';
import { beginMessage, CommonContractBase, emptyCell } from '@ston-fi/blueprint-utils';

export type DummyConfig = {
    op?: bigint | number,
    msg?: Cell,
    payload?: Cell,
};

export function dummyConfigToCell(config: DummyConfig): Cell {
    return beginCell()
        .storeUint(config.op ?? 0, 32)
        .storeRef(config.msg ?? emptyCell())
        .storeRef(config.payload ?? emptyCell())
        .endCell();
}

export class DummyContract extends CommonContractBase {
    static createFromConfig(config: DummyConfig, code: Cell, workchain = 0) {
        return this.createFromConfigBase(config, dummyConfigToCell, code, workchain)
    }

    async sendMsg(provider: ContractProvider, via: Sender, opts: {
        op: number,
        payload: Slice
    }, value: bigint) {
        await provider.internal(via, {
            value: value,
            sendMode: SendMode.PAY_GAS_SEPARATELY,
            body: beginMessage(opts.op ?? 0)
                .storeSlice(opts.payload)
                .endCell(),
        });
    }
}

```

### Codes

The module contains a number of known op codes and a helpers to parse them from `.fc` files

#### Example

See graph example above for common usage.

### Color

The module contains functions to use ANSI escape code in console output in a convenient way by usage of `<..>` tags. The full list of supported tags can be found [here](/docs/color_tags.md).

#### Example

```ts
import { color } from '@ston-fi/blueprint-utils';

color.log("This text will be <r>Red <g>green <bld><b>blue and bold <y>yellow and bold <clr><c>cyan")
```

### Inspector

The module contains `ContractInspector` that allows you to load compiled contracts' functions as `Slices` or `Cells`. Is useful for passing loaded data to another contract that uses child VM execution.

#### Example

```ts
import { ContractInspector } from '@ston-fi/blueprint-utils';
import { compile } from '@ton/blueprint';

const methods = new ContractInspector(await compile("YourContractName"));
const someMethod = methods.loadMethodCell("get_some_data");

```

### Meta

The module contains helpers  to serialize and deserialize standard metadata in both on-chain and off-chain formats. Only snake format for on-chain metadata is supported.

#### Example

```ts
import { onchainMetadata, metadataCell } from '@ston-fi/blueprint-utils';

// on-chain metadata
const metadataOnChain = {
    name: "SomeToken",
    description: "Some test token",
    decimals: 9,
    symbol: "STT",
    imageData: "build/images/some_image.png", // on-chain image; path to the image on your local machine
    // image: "https://someurl.com/img.png", // or off-chain image
}
const metadataCell1 = metadataCell(onchainMetadata(metadataOnChain))

// off-chain metadata
const metadataOffChain = "https://someurl.com/meta.json"
const metadataCell2 = metadataCell(metadataOffChain)

```

### On-chain Helpers

The module contains helpers designed to be used in on-chain scripts to confirm transaction's success.

#### Example

```ts
import { 
    getSeqNo, 
    emptyCell, 
    waitSeqNoChange, 
    JettonMinterContractX, 
    JettonWalletContractX, 
    prettyBalance, 
    getWalletBalance 
} from '@ston-fi/blueprint-utils';
import { Address, toNano } from '@ton/core';

export async function run(provider: NetworkProvider, args: string[]) {
    const amount = toNano("some_amount")
    const targetAddress = Address.parse("TransferDestinationAddress")
    const senderAddress = provider.sender().address as Address
    
    const jettonMinter = provider.open(JettonMinterContractX.createFromAddress("TokenMinterAddressHere"));
    const jettonWalletAddress = await jettonMinter.getWalletAddress(senderAddress)
    const jettonWallet = provider.open(JettonWalletContractX.createFromAddress(jettonWalletAddress));
    
    const jettonWalletAddressTarget = await jettonMinter.getWalletAddress(targetAddress)
    const jettonWalletTarget = provider.open(JettonWalletContractX.createFromAddress(jettonWalletAddressTarget));
    const oldBalance = await getWalletBalance(jettonWalletTarget)
    
    const seqno = await getSeqNo(provider, senderAddress)
    await jettonWallet.sendTransfer(provider.sender(), {
        value: toNano("0.1"),
        jettonAmount: amount,
        toAddress: targetAddress,
        responseAddress: senderAddress,
        fwdAmount: 0n,
        fwdPayload: emptyCell().beginParse()
    })
    if (await waitSeqNoChange(provider, senderAddress, seqno)) {
        if (await awaitConfirmation(async () => {
            const balance = await getWalletBalance(jettonWalletTarget)
            return balance - oldBalance === amount
        })) {
            color.log(` - <g>Successfully sent tokens`)
            color.log(` - <y>Wallet balance: <b>${prettyBalance(await getWalletBalance(jettonWallet), rawTokenData)}`)
        } else {
            color.log(` - <r>Error sending tokens`)
        }
    }
    
}
```

### Preproc

The module contains `preprocBuildContracts` that executes js-snippets in `.fc` files.

#### Example

```ts
import { preprocBuildContracts, parseVersion } from '@ston-fi/blueprint-utils';

preprocBuildContracts({
    data: {
        version: parseVersion(),
        someOtherVariable1: 123456,
        someOtherVariable2: "some_string",
    }
})
```

## Licensing
The license for this library is the MIT License, see [LICENSE](LICENSE).