Working with cells ​

Cells are the basic storage elements in the blockchain, used to represent and manipulate data in contracts. In this guide, we will explore the basic methods for working with cells provided by everscale-inpage-provider.

Here is the ABI definition we'll use in our examples:

const ABI = [
  { name: 'name', type: 'string' },
  { name: 'age', type: 'uint32' },
  { name: 'city', type: 'string' },
] as const;

Packing data into a cell ​

To pack data into a TVM cell, use the packIntoCell method. It creates a base64 encoded BOC (Bag of Cells) from the provided data, structure, and ABI version.

import { ProviderRpcClient } from 'everscale-inpage-provider';

const provider = new ProviderRpcClient();

// Make sure the provider is initialized.
await provider.ensureInitialized();

// Request permissions from the user to execute API methods using the provider.
await provider.requestPermissions({ permissions: ['basic'] });

// Define the data to pack.
const dataToPack = {
  name: 'Alice',
  age: 30,
  city: 'New York',
};

// Pack the data into BOC.
const { boc, hash } = await provider.packIntoCell({
  structure: ABI,
  data: dataToPack,
});

console.log('Packed data:', boc);
console.log('Packed data hash:', hash);

Unpacking data from a cell ​

To unpack data from a TVM cell, use the unpackFromCell method. It decodes the base64-encoded string into an object according to the provided ABI.

// Define the data to unpack.
const bocToUnpack = 'te6ccgEBAwEAGQACCAAAAB4CAQAQTmV3IFlvcmsACkFsaWNl';

// Unpack the data from BOC.
const unpacked = await provider.unpackFromCell({
  structure: ABI,
  boc: bocToUnpack,
  allowPartial: true,
});
console.log('Unpacked data:', unpacked.data);

Computing Hash of Base64 Encoded BOC ​

We will explore how to compute the hash of a base64 encoded BOC (Bag of Cells) using the getBocHash method provided by the everscale-inpage-provider.

Get BOC Hash ​

The getBocHash method computes the hash of a base64 encoded BOC and returns the hash as a hexadecimal string. This method requires basic permissions.

Here's an example of how to use the getBocHash method:

// Define the base64 encoded BOC.
const boc = 'te6ccgEBAwEAGQACCAAAAB4CAQAQTmV3IFlvcmsACkFsaWNl';

// Compute the hash of the base64 encoded BOC.
const hash = await provider.getBocHash(boc);

console.log('BOC hash:', hash);

Extracting Public Key from Raw Account State ​

The extractPublicKey method is useful when you need to obtain the public key associated with a contract's raw account state. This can be helpful, for example, when verifying the integrity of a transaction or checking the owner of a contract. Keep in mind that this method can only be used on contracts that have been deployed and have a pubkey header.

const exampleBOC = `te6ccgECJAEABVQAAq+ABZ3CHw48OB0mTpE8eqZinXiv5scdevb2gcI/pRjrelBFjS9+hkTHXAAAAGmBdY7yEh23xBWmo7FjLZOuSyzxWmQsy2Iuh1QTrvQw03v4IzLNJK91loBAAwEBgfvlEQAVS8EtkmmQXS+aqup1WIq0Oaj5Ef1aKt620rWnAAABh8qr9wqAABHVgAAAAAAAAAAAAAAAAAAB9AAAAABAAgAIdGVzdAQkiu1TIOMDIMD/4wIgwP7jAvILIQUEIwLc7UTQ10nDAfhmjQhgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE+Gkh2zzTAAGOFIMI1xgg+CjIzs7J+QBY+EL5EPKo3tM/AfhDIbnytCD4I4ED6KiCCBt3QKC58rT4Y9MfAds88jwLBgN67UTQ10nDAfhmItDTA/pAMPhpqTgA+ER/b3GCCJiWgG9ybW9zcG90+GTcIccA4wIh1w0f8rwh4wMB2zzyPCAgBgIoIIIQQT7ay7vjAiCCEHEJa0q74wIOBwM8IIIQZwdgDrrjAiCCEG6/VtK64wIgghBxCWtKuuMCDAoIA3Iw+Eby4Ez4Qm7jANHbPCGOISPQ0wH6QDAxyM+HIM6CEPEJa0rPC4EBbyICyx/MyXD7AJEw4uMA8gAfCR0ABPhMAkgw+EJu4wD4RvJz03/U0fgAIfhrAYED6KkItR8BbwL4bNs88gALEQJu7UTQ10nCAY6scO1E0PQFcSGAQPQOb5GT1wsf3nAgiG8C+Gz4a/hqgED0DvK91wv/+GJw+GPjDSMfAygw+Eby4Ez4Qm7jANN/0ds82zzyAB8NEQFC+CdvEGim/mChtX9y+wLbPPhJyM+FiM6Ab89AyYEAgfsAEwRQIIIQETcOALrjAiCCED/haBW64wIgghBAAi9yuuMCIIIQQT7ay7rjAhwUEA8BUDDR2zz4SyGOHI0EcAAAAAAAAAAAAAAAADBPtrLgyM7Lf8lw+wDe8gAfAygw+Eby4Ez4Qm7jANN/0ds82zzyAB8SEQA++Ez4S/hK+EP4QsjL/8s/z4PLH8t/AW8iAssfzMntVAEI+ADbPBMAZiD4a4ED6KkItR/4TAFvUCD4bI0EcAAAAAAAAAAAAAAAABTOcilgyM4BbyICyx/MyXD7AANoMPhG8uBM+EJu4wDU0ds8IY4bI9DTAfpAMDHIz4cgzoIQv+FoFc8LgczJcPsAkTDi4wDyAB8VHQEM+ExvEds8FgQ8Ads8WNBfMts8MzOUIHHXRo6I1TFfMts8MzPoMNs8GhkZFwEkliFviMAAs46GIds8M88R6MkxGAAcb41vjVkgb4iSb4yRMOIBUiHPNab5IddLIJYjcCLXMTTeMCG7jo1c1xgzI84zXds8NMgz31MSzmwxGwEwbwAB0JUg10rDAI6J1QHIzlIg2zwy6MjOGwA4URBviJ5vjSBviIQHoZRvjG8A35JvAOJYb4xvjAPwMPhG8uBM+EJu4wDTH/hEWG91+GTTH9HbPCGOHyPQ0wH6QDAxyM+HIM6CEJE3DgDPC4EBbyICyx/MyXCONPhEIG8TIW8S+ElVAm8RyM+EgMoAz4RAzgH6AvQAgGrPQPhEbxXPCx8BbyICyx/MyfhEbxTi+wDjAPIAHx4dACjtRNDT/9M/MfhDWMjL/8s/zsntVAFaIIED6Lny5Tn4TG8QoLUfcIhvAgFvUPhMbxFvUTD4RHBvcoBEb3Rwb3H4ZPhMIwBA7UTQ0//TP9MAMdMf03/TH9RZbwIB0fhs+Gv4avhj+GIACvhG8uBMAhD0pCD0vfLATiMiABRzb2wgMC42Ni4wAAA=`;

// Extract public key from boc
const publicKey = await provider.extractPublicKey(exampleBOC);

console.log('Public key:', publicKey);

Converting Contract Code to TVC ​

The codeToTvc method is essential when you want to convert a base64 encoded contract code into a TVC (TVM Container) file with default init data. This conversion is necessary when deploying a contract, as the TVC format is used to store the contract's code and data in a compact binary form, suitable for execution on the TON Virtual Machine.

const base64Contract = `te6ccgECJAEABNsAAgE0AwEBAcACAEPQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgBCSK7VMg4wMgwP/jAiDA/uMC8gshBQQjAtztRNDXScMB+GaNCGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAT4aSHbPN=YgAK+Eby4EwCEPSkIPS98sBOIyIAFHNvbCAwLjY2LjAAAA==`;

// Convert contract code to TVC
const tvc = await provider.codeToTvc(base64Contract);

console.log('TVC:', tvc);

Merging and Splitting TVC ​

The mergeTvc and splitTvc methods provide a convenient way to manage the contract's code and data separately or combined into a single state init. These methods are particularly useful during the development and testing phases, where you may need to modify or inspect the contract code and data independently.

// Merge code and data into state init
const mergedTvc = await provider.mergeTvc({ code: base64Contract, data: exampleBOC });

// Split state init into code and data
const { code, data } = await provider.splitTvc(mergedTvc.tvc);

Setting and Retrieving Code Salt ​

The setCodeSalt and getCodeSalt methods allow you to manage the salt value associated with a contract's code. The salt value is an optional component that can be used to ensure the uniqueness of a contract's code, preventing collisions or other issues when deploying multiple instances of the same contract. These methods enable you to set and retrieve the salt value easily, ensuring the contract's code is unique and secure.

saltParams;
// Set code salt
const saltParams = { structure: exampleAbi, data: saltData };
const saltedCode = await provider.setCodeSalt({ code: contractCode, salt: saltParams });

// Get code salt
const codeSalt = await provider.getCodeSalt({ code: saltedCode.code });

Getting Expected Address ​

The getExpectedAddress method is valuable when you need to compute the expected address of a contract before its deployment. This method takes into account the provided TVC, workchain, public key, and init params, returning the address that the contract will have once it is deployed. This can be useful for pre-allocating resources or setting up permissions in advance, ensuring a smooth deployment process.

const deployParams = {
  tvc: base64Contract,
  workchain: 0,
  publicKey: 'public_key',
  initParams: {
    nonce: 0,
  },
};

// Get the expected address of the contract
const expectedAddress = await provider.getExpectedAddress(deployParams);

console.log('Expected address:', expectedAddress);