Quick navigation
CLI commands
create
— create new contracts from templatesbuild
— build contractsrun
— execute deployment and custom scriptstest
— run test suitesverify
— verify contracts using TON Contract Verifier.help
— display command help informationset
— configure language versionconvert
— convert legacy build scriptsrename
— rename contracts across the projectpack
— package contracts for deploymentsnapshot
— create gas usage snapshots
API reference
tonDeepLink
— generate transaction deep linksgetExplorerLink
— generate blockchain explorer URLsgetNormalizedExtMessageHash
— hash external messagescompile
— compile smart contracts programmaticallylibraryCellFromCode
— create library cellsNetworkProvider
— network interaction interfaceUIProvider
— user interface interaction- Type definitions — configuration and option types
Configuration
- Environment variables — wallet and network configuration
- Blueprint configuration — detailed configuration guide
CLI commands
Blueprint provides a comprehensive set of CLI commands for smart contract development, testing, and deployment. Commands support both interactive and non-interactive modes.create
Interactive mode
- Contract name selection (validates CamelCase format)
- Programming language choice (Tolk, FunC, or Tact)
- Template type selection (empty or counter example)
Non-interactive mode
<CONTRACT>
— contract name in CamelCase format (e.g.,MyAwesomeContract
)<TYPE>
— template type from available options
tolk-empty
— an empty contract (Tolk)func-empty
— an empty contract (FunC)tact-empty
— an empty contract (Tact)tolk-counter
— a simple counter contract (Tolk)func-counter
— a simple counter contract (FunC)tact-counter
— a simple counter contract (Tact)
contracts/MyContract.{tolk|fc|tact}
— contract source codewrappers/MyContract.ts
— TypeScript wrapper for contract interactiontests/MyContract.spec.ts
— Jest test suite with basic test casesscripts/deployMyContract.ts
— deployment script with network configuration
build
.compile.ts
configuration files.
Interactive mode
.compile.ts
files for selection. Shows compilation status and allows building individual contracts or all at once.
Non-interactive mode
<CONTRACT>
— specific contract name to build (matches the.compile.ts
filename)--all
— build all contracts in the project that have compilation configurations
run
scripts/
directory with full network provider access. Commonly used for contract deployment, interaction, and maintenance tasks.
Interactive mode
scripts/
directory to select from.
Non-interactive mode
<SCRIPT>
— script name (without.ts
extension)<ARGS...>
— optional arguments passed to the script--<NETWORK>
— network selection (mainnet
,testnet
)--<DEPLOY_METHOD>
— deployment method (tonconnect
,mnemonic
)
--mainnet
— use TON Mainnet--testnet
— use TON Testnet--custom <URL>
— use custom network endpoint--custom-version <VERSION>
— API version (v2
,v4
)--custom-type <TYPE>
— network type (custom
,mainnet
,testnet
)--custom-key <KEY>
— API key (v2 only
)
--tonconnect
— use TON Connect for deployment--deeplink
— use deep link for deployment--mnemonic
— use mnemonic for deployment
--tonscan
— use Tonscan explorer--tonviewer
— use Tonviewer explorer (default)--toncx
— use Toncx explorer--dton
— use Dton explorer
<YOUR_API_KEY>
— API key for the selected provider (v2
only).
- Scripts must be located in
scripts/
directory - Script files must export a
run
function:
test
Run the full project test suite with all .spec.ts
files.
Basic usage
tests/
directory.
Collecting coverage
coverage/
directory.
Gas reporting
Specific test file
- Test files should be located in
tests/
directory - Use
.spec.ts
extension - Supports standard Jest syntax and matchers
verify
Verify a deployed contract using TON Contract Verifier.
Basic usage
Non-interactive mode
<CONTRACT>
— contract name to verify--network <NETWORK>
— network (mainnet
,testnet
)--compiler-version <VERSION>
— compiler version used for building--custom <URL>
— custom network endpoint--custom-version <VERSION>
— API version (v2
default)--custom-type <TYPE>
— network type (mainnet
,testnet
)--custom-key <KEY>
— API key (v2
only)
help
Show detailed help.
set
Sets language versions.
func
— overrides@ton-community/func-js-bin
version
convert
Converts legacy bash build scripts to Blueprint wrappers.
rename
Renames a contract by matching in wrappers, scripts, and tests.
pack
Builds and prepares a publish-ready package of wrappers.
--no-warn
,-n
— ignore warnings about modifyingtsconfig.json
andpackage.json
, and about removing thedist
directory
- Creates deployment-ready package
- Includes compiled artifacts
- Bundles dependencies
snapshot
Creates snapshots with gas usage and cell sizes.
--label=<COMMENT>
,-l=<COMMENT>
— add a comment label to the snapshot
- Run with gas usage and cell sizes collected
- Write a new snapshot
- Useful for regression testing
Environment variables
Blueprint supports environment variables for wallet configuration when using mnemonic provider:WALLET_MNEMONIC
— wallet mnemonic phrase (space-separated words).WALLET_VERSION
— wallet contract version (v1r1
,v1r2
,v1r3
,v2r1
,v2r2
,v3r1
,v3r2
,v4r1
,v4r2
,v4
,v5r1
).WALLET_ID
— wallet ID for versions earlier thanv5r1
.SUBWALLET_NUMBER
— subwallet number forv5r1
wallets.
Example .env file
<MNEMONIC_24_WORDS>
— 24-word wallet mnemonic (space-separated).
API reference
Blueprint exports functions and classes for programmatic interaction with TON smart contracts.tonDeepLink
Generates a TON deep link for transfer.
address
— the recipient’s TON addressamount
— the amount of nanoTON to sendbody
— optional message body as a CellstateInit
— optional state init cell for deploying a contracttestOnly
— optional flag to determine output address format
getExplorerLink
Generates a link to view a TON address in a selected blockchain explorer.
address
— the TON address to view in explorernetwork
— the target network (mainnet
ortestnet
)explorer
— the desired explorer (tonscan
,tonviewer
,toncx
,dton
)
getNormalizedExtMessageHash
Generates a normalized hash of an external-in
message for comparison.
message
— the message to be normalized and hashed (must be of typeexternal-in
)
Buffer
Throws: error if the message type is not external-in
compile
Compiles a contract using the specified configuration for tact
, func
, or tolk
languages.
name
— the name of the contract to compile (should correspond to a file named<name>.compile.ts
)opts
— optionalCompileOpts
, including user data passed to hooks
Cell
Example:
libraryCellFromCode
Packs resulting code hash into library cell.
code
— the contract code cell
NetworkProvider
Interface representing a network provider for interacting with the TON Blockchain.
network()
explorer()
Explorer
name for the current network
sender()
SenderWithSendResult
instance used for sending transactions
api()
BlueprintTonClient
API for direct blockchain interactions
provider()
address
— the contract address to interact withinit
— optional contract initialization datacode
— Contract code celldata
— Contract initial data cell
contractProvider
instance for the specified address
isContractDeployed()
address
— the contract address to check
true
if contract is deployed, false
otherwise
Usage example:
waitForDeploy()
address
— the contract address to monitorattempts
— maximum number of polling attempts (default: 20)sleepDuration
— delay between attempts in milliseconds (default: 2000)
waitForLastTransaction()
attempts
— maximum number of polling attempts (default: 20)sleepDuration
— delay between attempts in milliseconds (default: 2000)
getContractState()
address
— the contract address to query
ContractState
.
Usage example:
getConfig()
configAddress
— optional config contract address (uses default if not provided)
BlockchainConfig
open()
contract
— the contract instance to open
openedContract
wrapper that enables direct method calls
Usage example:
ui()
UIProvider
instance for console interactions
Usage example:
UIProvider
Interface for handling user interactions, such as displaying messages, prompting for input, and managing action prompts. This interface abstracts console interactions and can be used in both interactive and automated scenarios.
write()
message
— the text message to display
prompt()
message
— the prompt message to display
true
for yes, false
for no
Usage example:
inputAddress()
message
— the prompt message to displayfallback
— optional default address to use if user provides empty input
input()
message
— the prompt message to display
choose()
message
— the prompt message to displaychoices
— array of options to choose fromdisplay
— function to convert each choice to a display string
setActionPrompt()
message
— the action prompt message to display
clearActionPrompt()
Type definitions
Blueprint exports several TypeScript types for configuration and compilation options. These types provide type safety and IntelliSense support when working with Blueprint programmatically.CompileOpts
Optional compilation settings, including user data passed to hooks and compilation flags.
hookUserData
— optional user data passed to pre/post compile hooksdebugInfo
— enable debug information in compiled output (default:false
)buildLibrary
— build as a library instead of a regular contract (default:false
)
CommonCompilerConfig
Base configuration shared by all compiler types. This interface defines common compilation hooks and options.
preCompileHook
— optional function called before compilation starts (receivesHookParams
)postCompileHook
— optional function called after compilation completes (receives compiledCell
andHookParams
)buildLibrary
— whether to build as a library (default:false
)
./wrappers/MyContract.compile.ts
FuncCompilerConfig
Configuration specific to the FunC compiler, including optimization levels and source file specifications.
lang
— compiler language identifier (optional, defaults to'func'
)optLevel
— optimization level (0-2, default: 2)debugInfo
— include debug information in outputtargets
— array of FunC source file paths to compilesources
— alternative source specification method
./wrappers/MyContract.compile.ts
TolkCompilerConfig
Configuration for the Tolk compiler, including optimization and debugging options.
lang
— compiler language identifier (must be'tolk'
)entrypoint
— path to the main Tolk source fileoptimizationLevel
— optimization levelwithStackComments
— include stack operation comments in Fift outputwithSrcLineComments
— include source line comments in Fift outputexperimentalOptions
— additional experimental compiler flags
./wrappers/MyContract.compile.ts
TactLegacyCompilerConfig
Configuration for the Tact compiler (legacy configuration format).
lang
— compiler language identifier (must be'tact'
)target
— path to the main Tact source fileoptions
— additional Tact compiler options
./wrappers/MyContract.compile.ts
HookParams
Parameters passed to compilation hooks, providing context about the compilation process.
userData
— optional user data passed fromCompileOpts
SenderWithSendResult
Extended sender interface that tracks the result of the last send operation.
lastSendResult
— optional result from the most recent send operation
BlueprintTonClient
Union type representing supported TON client implementations.
TonClient4
— TON HTTP API v4 clientTonClient
— TON HTTP API v2/v3 clientContractAdapter
— TON API adapterLiteClient
— Lite client for direct node communication
Explorer
Supported blockchain explorer types.
'tonscan'
— TONScan explorer'tonviewer'
— Tonviewer explorer (default)'toncx'
— TON.cx explorer'dton'
— dton.io explorer