STON.fi Blueprint Utils

A collection of helpers to work with @ton/blueprint

Installation

To install this package use

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

or via yarn

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

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

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

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.

Example

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

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

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

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

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.