Locklift

In previous articles, we have used everscale-inpage-provider or eversdk. They are great for writing server applications that need to interact with the BC and to understand what is happening when deploying and interacting with contracts. Eversdk also has bindings for many languages.

However, for the development/testing of complex decentralized applications consisting of multiple contracts, a more advanced framework with support for testing, network and key management is needed.

And in our ecosystem, we have such a framework, it's Locklift. Under the hood, it uses everscale-inpage-provider and everscale-standalone-client, and brings convenient tools specifically for the development of large smart contract systems. We will take our tokenDice from the previous example and the production-ready version of tip-3, and create a locklift project for them with deployment and testing scripts

Full code of this example available here.

How we got it:

mkdir locklift-dice
cd locklift-dice

npm init
npm install --save-dev locklift

npx locklift init -f

We have obtained the boilerplate of a new project. We will use the already compiled contract of tip3, so that the blockchain explorer https://venomscan.com can automatically understand from our contract code that this is a tip3 token. (The code depends on the compiler version used to compile it)."

Install tip3 and bignumber.js:

npm i git+https://github.com/broxus/tip3.git#480c1b4481d1dddb028b408b20ba8c19abd1a4a4 --saveDev
npm i bignumber.js --saveDev

We are also moving our contract TokenDice.tsol, 1 to 1 to contracts/TokenDice.tsol, only changing the import paths of the Tip3 token to the production interfaces of the broxus' tip3 token.

-import "./interfaces/ITokenRoot.tsol";
-import "./interfaces/ITokenWallet.tsol";
-import "./interfaces/IAcceptTokensTransferCallback.tsol";
-import "./interfaces/IAcceptTokensMintCallback.tsol";
+import "broxus-ton-tokens-contracts/contracts/interfaces/ITokenRoot.tsol";
+import "broxus-ton-tokens-contracts/contracts/interfaces/ITokenWallet.tsol";
+import "broxus-ton-tokens-contracts/contracts/interfaces/IAcceptTokensTransferCallback.tsol";
+import "broxus-ton-tokens-contracts/contracts/interfaces/IAcceptTokensMintCallback.tsol";

Let's move on to the locklift.config.ts file, this is the main configuration file. If you see some typescript errors, ignore them, this is because we have not yet built the contracts and the factory is not initialized. This file contains compiler and linker version settings (to get reproducible builds), as well as settings for different networks.

We have added the paths to the "external" already compiled contracts in the "compiler" section so that the framework can import them and conveniently wrap them in a special factory. With locklift, we don't need to use everdev to compile and link, it will do everything itself, and pass the contracts to the global factory.

compiler: {
  // Specify path to your T-Solidity-Compiler
  // path: "/mnt/o/projects/broxus/TON-Solidity-Compiler/build/solc/solc",

  // Or specify version of compiler
  version: "0.64.0",

  // Specify config for extarnal contracts as in exapmple
-  // externalContracts: {
-  //   "node_modules/broxus-ton-tokens-contracts/build": ['TokenRoot', 'TokenWallet']
-  // }
+  externalContracts: {
+   "node_modules/broxus-ton-tokens-contracts/build": ['TokenRootUpgradeable', 'TokenWalletUpgradeable', 'TokenWalletPlatform'],
+  },

This config also contains settings for all networks separately (local, test, main). We will use the local network for testing, and it already has a pre-configured giver for it.

I will remind you that the giver is any contract that is used to deploy contracts using an external message, it can also be used to manually refill any contracts. To deploy your contracts to a non-local test network, you need to configure the giver and keys for the test/main network, as well as set up authentication for the endpoints. To do this, read here.

There are also seed phrase settings, from which the first N key pairs will be obtained and added to the keyStore. For the local network, you can use the already installed seed phrase, and for the test/main network you need to configure it yourself, following the instructions mentioned above.

For the local network, we will uncomment the set seed phrase. We will use it for our wallet from which we will deploy our smart contracts.

local: {
      // ...
      keys: {
        // Use everdev to generate your phrase
        // !!! Never commit it in your repos !!!
-       // phrase: "action inject penalty envelope rabbit element slim tornado dinner pizza off blood",
+       phrase: "action inject penalty envelope rabbit element slim tornado dinner pizza off blood",
        amount: 20,
      },
      // ...
},

By the command npx locklift build or before running tests or scripts, locklift finds all contracts that are in ./contracts, compiles and links them, and makes them available within scripts in locklift.factory global variable.

This is the end of the configuration, now let's move on to the analysis of our scripts, which are located in the ./scripts folder. The command npx locklift run --script scripts/0-deploy-owner-everwallet.ts --network local runs the 0th script, which will deploy the owner's EverwWallet of our token.

import {EverWalletAccount} from "everscale-standalone-client";

async function main() : Promise<any> {
    // Get keypair from the seed phrase
    const signer = (await locklift.keystore.getSigner("0"))!;

    // Get the contract by the pubkey.
    const diceOwnerWallet = await EverWalletAccount.fromPubkey({publicKey: signer.publicKey, workchain: 0});

    // Fulfil wallet's balance from the giver
    await locklift.giver.sendTo(diceOwnerWallet.address, locklift.utils.toNano(10));
    console.log('EverWallet deployed at', diceOwnerWallet.address.toString());
}

main()
    .then(() => process.exit(0))
    .catch(e => {
        console.log(e);
        process.exit(1);
    });

Next script npx locklift run --script scripts/1-deploy-token-root.ts --network local will deploy the TokenRoot contract with the owner we deployed above.

import {zeroAddress} from "locklift";
import BigNumber from "bignumber.js";
import {EverWalletAccount} from "everscale-standalone-client/nodejs";

async function main() {
  const signer = (await locklift.keystore.getSigner("0"))!;
  // The same EverWallet we deployed in script 0, because they are from one pubkey
  const diceOwnerWallet = await EverWalletAccount.fromPubkey({publicKey: signer.publicKey, workchain: 0});

  // Production ready tip-3 has a bit more constructor arguments than our
  // toy example, because it is support more features, like burn tokens.

  // Also, we will use Upgradable version of tip3 token.
  // It makes sense to use upgradable version of token even if you don't want
  // to upgrade token contract in the future. You can just send ownership
  // of the root to the black hole if you do not want to upgrade the token or
  // have ability to mint additional tokens.

  // Contract of the token wallet
  const TokenWalletUpgradable = locklift.factory.getContractArtifacts("TokenWalletUpgradeable");
  // Contract of the token root
  const TokenRootUpgradeable = locklift.factory.getContractArtifacts("TokenRootUpgradeable");

  // Special platform contract. It is necessary for
  // upgradable contracts in distributed programming.
  // We always deploy this small contract and then 
  // upgrade it to the real one. We describe this pattern
  // in "How to upgrade contracts" article of this chapter.
  const TokenWalletPlatform = locklift.factory.getContractArtifacts("TokenWalletPlatform");

  // There are three options for deploying a TokenRoot
  // The first one is a simple deployment with an external message.
  // So we will just set a temporarily pubkey to it, to be sure the contract's
  // constructor is called correctly.
  // ( The message which one called the constructor is
  // signed by owner of static variable - pubkey ).

  // The second one is deploying by an internal message with stateInit,
  // like we deployed in the simple-tip3 example. From the
  // address which one is set as a owner of the TokenRoot.

  // And the third one is using a special "deployer" contract.
  // It is like fabric for contracts to support deployment for wallets
  // which ones are not supported stateInit sending or other contracts
  // like dao. It is easier to deploy a token root by just
  // calling " the deploy method" of some contract rather to build an stateInit.
  // factory - https://github.com/broxus/tip3/blob/master/contracts/additional/TokenFactory.tsol

  // We will use a simple deployment by an external message,
  // to show you how it is can be done with locklift.

  // Construtor params:
  // Root token constructor params:
  // Mint initial supply to zero address
  const initialSupplyTo = zeroAddress;
  // How many tokens mint after deploy to initialSupplyTo
  const initialSupply = '0';
  // Disable future minting of the new tokens
  const disableMint = false;
  // Disable ability of the root owner to burn user's tokens
  const disableBurnByRoot = false;
  // Is users can burn their tokens.
  // Useful in some applications like bridges.
  const pauseBurn = false;
  // How many nano VENOMs use to deploy wallet if initial supplier
  const initialDeployWalletValue = '0';

  // TokenRoot static params:
  // Owner of the root contract (can mint or burn tokens)
  const rootOwner = diceOwnerWallet.address;
  // Name of the token
  const name = "USDice";
  // Symbol
  const symbol = "UD";
  // Decimals - 9
  const decimals = 9;
  

  const { contract: tokenRoot } = await locklift.factory.deployContract({
    contract: "TokenRootUpgradeable",
    publicKey: signer.publicKey,
    //Static variables
    initParams: {
      randomNonce_: locklift.utils.getRandomNonce(),
      rootOwner_: rootOwner,
      name_: name,
      symbol_: symbol,
      deployer_: zeroAddress,
      decimals_: 9,
      walletCode_: TokenWalletUpgradable.code,
      platformCode_: TokenWalletPlatform.code
    },
    constructorParams: {
      initialSupplyTo: initialSupplyTo,
      initialSupply: new BigNumber(initialSupply).shiftedBy(decimals).toFixed(),
      deployWalletValue: initialDeployWalletValue,
      mintDisabled: disableMint,
      burnByRootDisabled: disableBurnByRoot,
      burnPaused: pauseBurn,
      remainingGasTo: diceOwnerWallet.address,
    },
    // How many tokens send from the giver to the contract
    // before deploy it by an external message
    value: locklift.utils.toNano(2),
  });

  console.log(`Token root deployed at: ${tokenRoot.address.toString()}`);
}

main()
  .then(() => process.exit(0))
  .catch(e => {
      console.log(e);
      process.exit(1);
  });

Next script npx locklift run --script scripts/2-deploy-token-dice-contract.ts --network local will deploy TokenDice.tsol, with the TokenRoot and owner we deployed in previous scripts.

import {Address} from "locklift";
import {checkIsContractDeployed} from "./utils";
import {EverWalletAccount} from "everscale-standalone-client/nodejs";

async function main() {
  // The same EverWallet we deployed in script 0, because they are from one pubkey
  const signer = (await locklift.keystore.getSigner("0"))!;
  const diceOwnerWallet = await EverWalletAccount.fromPubkey({publicKey: signer.publicKey, workchain: 0});

  // !!!
  // Put there address of the token root the previous script!
  // !!!
  const tokenRootAddress = '0:cb5f57378e82174ed95502b01df16235d8d94e974ce24a4dc8a10143f23c0c44';
  await checkIsContractDeployed(new Address(tokenRootAddress), 'TokenRoot')

  // We will deploy TokenDice.tsol by the internal message from our EverWallet
  const TokenDice = locklift.factory.getContractArtifacts("TokenDice");

  // Calculate the state init for tvc and initial params.
  // StateInit - code + static variables, to deploy the contract
  // Also this function return address of the future contract
  // Because address it is a hash(stateInit)
  const {address: diceContractAddress, stateInit: tokenDiceStateInit} = await locklift.provider.getStateInit(TokenDice.abi, {
    workchain: 0,
    tvc: TokenDice.tvc,
    initParams: {
      tokenRoot_: new Address(tokenRootAddress),
      owner_: diceOwnerWallet.address
    }
  })


  // We need to add our EverWallet as account to provider
  // to use .send({from: 'address'})
  await locklift.factory.accounts.storage.addAccount(diceOwnerWallet);

  // Contract instance
  const tokenDice = new locklift.provider.Contract(TokenDice.abi, diceContractAddress);

  console.log('Try deploy at', tokenDice.address.toString());

  // Tracing is a method similar to subscriber.trace(tx) that we 
  // used in previous articles, but it does not return a stream,
  // but retrieves the entire chain of transactions through
  // graphql itself. It also has a multitude of settings, such 
  // as which errors to ignore, or a convenient beautyPrint of
  // the transaction graph in the console. 
  // See the locklift documentation to learn more about its capabilities.
  
  // Deploy TokenDice by inernal from our EverWallet 
  const tracing = await locklift.tracing.trace(
    tokenDice.methods.constructor({}).send({
      from: diceOwnerWallet.address,
      amount: locklift.utils.toNano(3),
      stateInit: tokenDiceStateInit
    })
  )

  await checkIsContractDeployed(diceContractAddress, 'TokenDice')
  console.log(`Token dice deployed at: ${diceContractAddress.toString()}`);
}

main()
  .then(() => process.exit(0))
  .catch(e => {
    console.log(e);
    process.exit(1);
  });

And the last script npx locklift run --script scripts/3-mint-tokens.ts --network local will mint some tokens from the TokenRoot to our EverWallet.

import {Address} from "locklift";
import {checkIsContractDeployed} from "./utils";
import {EverWalletAccount} from "everscale-standalone-client/nodejs";

async function main() {
  const signer = (await locklift.keystore.getSigner("0"))!;
  // The same EverWallet we deployed in script 0, because they are from one pubkey
  const diceOwnerWallet = await EverWalletAccount.fromPubkey({publicKey: signer.publicKey, workchain: 0});
  // We need to add our EverWallet as account to provider
  // to use .send({from: 'address'})
  await locklift.factory.accounts.storage.addAccount(diceOwnerWallet);

  const mintTo = diceOwnerWallet.address;

  // Put there address of the token root the previous script.
  const tokenRootAddress = '0:cb5f57378e82174ed95502b01df16235d8d94e974ce24a4dc8a10143f23c0c44';

  await checkIsContractDeployed(new Address(tokenRootAddress), 'TokenRootUpgradeable')
  const TokenRoot = locklift.factory.getDeployedContract('TokenRootUpgradeable', new Address(tokenRootAddress));

  // Call the method from our wallet
  const tracing = await locklift.tracing.trace(TokenRoot.methods.mint({
    amount: 10_000_000_000, //10 tokens * 9 decimals
    recipient: mintTo,
    deployWalletValue: locklift.utils.toNano(0.1), // 0.1 VENOMs
    remainingGasTo: diceOwnerWallet.address,
    notify: false,
    payload: "",
  }).send({
    from: diceOwnerWallet.address,
    amount: locklift.utils.toNano(1)
  }));


  const tokenWalletAddress = (await TokenRoot.methods.walletOf({answerId: 0, walletOwner: mintTo}).call()).value0;
  const TokenWallet = locklift.factory.getDeployedContract('TokenWalletUpgradeable', tokenWalletAddress);

  const {value0: tokenWalletBalance} = await TokenWallet.methods.balance({ answerId: 0 }).call();
  const { value0: totalSupply } = await TokenRoot.methods.totalSupply({ answerId: 0 }).call();

  console.log(`Tokens minted to ${mintTo.toString()}, wallet balance is ${tokenWalletBalance}, total supply is ${totalSupply}`);
}

main()
  .then(() => process.exit(0))
  .catch(e => {
    console.log(e);
    process.exit(1);
  });

So that's it, we have written an example that deploys TokenRoot, TokenDice, and mints a few tokens to our wallet.

We have also written simple tests where the dice game is checked, run the command npx locklift test --network local, and you can read the test itself in the ./test folder.

I remind you that to deploy contracts to testnet/mainnet, you need to configure givers and create a seed phrase, as described here.

Also, when you already have a deployed contract, you do not necessarily have to write scripts to call its methods from the owner's wallet, you can use EverWallet and web.ui as described here.

Next you can proceed to the description of how to write the frontend for our dice game on tokens, or move on to advanced study on writing smart contracts.