Package Exports
- @ston-fi/blueprint-utils
- @ston-fi/blueprint-utils/dist/index.js
- @ston-fi/blueprint-utils/dist/pkg/index.mjs
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ston-fi/blueprint-utils) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
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.