Contract Interaction ​

An active account is similar to an instance of a class, where smart-contract code is a class definition and persistent data is a state of all instance variables. Thus, to read the contract variables you can either decode account data or call some getters on it. As in system languages, reading variables from a memory representation of a structure is a tricky idea, in contracts it also depends on how these variables are packed. Therefore, interaction with smart contracts is done using some function calls.

You can interact with contract locally (e.g. getters) or on-chain. Each provider must have a VM and executor that is consistent with those of the validators. Therefore, during getters execution, RPC is used only to obtain the contract state, which can be reused. To execute method on-chain you can send an external message or an internal (through the selected wallet). The result of the on-chain method execution can be obtained by parsing a transaction with it.

Contract ABI ​

To be able to interact with contract, you must know its structure or the methods it implements. In blockchain, all compilers produce JSON ABI with the description of data, methods and events.

type Abi = {
  // Legacy major version definition
  'ABI version': 2;
  // Full ABI version definition (`major.minor`)
  version?: string;
  // Required headers
  header: AbiType[];
  // Function interfaces
  functions: AbiFunction[];
  // Event interfaces
  events: AbiEvent[];
  // State init variables
  data: (AbiType & { key: number })[];
};

Components ​

For a full description, please refer to the ABI specification.

type AbiType = {
  // Each parameter must have its own name
  name: string;
  // Concrete type from the table above
  type: string;
  // Tuple components if it is used in `type`
  components?: ParamType[];
};

type AbiFunction = {
  // Each function in contract must have its own unique name
  name: string;
  // Function arguments
  inputs: AbiType[];
  // Function output types (it can return several values of different types)
  outputs: AbiType[];
  // Optional explicit function id
  id?: string;
};

type AbiEvent = {
  // Each event in contract must have its own unique name
  name: string;
  // Event arguments
  inputs: AbiType[];
  // Optional explicit event id
  id?: string;
};

Declaration ​

Let's go back to the code and declare the ABI of our contract:

const exampleAbi = {
  'ABI version': 2,
  version: '2.3',
  header: ['time'],
  functions: [
    {
      name: 'constructor',
      inputs: [
        { name: 'someParam', type: 'uint128' },
        { name: 'second', type: 'string' },
      ],
      outputs: [],
    },
    {
      name: 'getComplexState',
      inputs: [],
      outputs: [
        {
          components: [
            { name: 'first', type: 'uint32' },
            { name: 'second', type: 'string' },
          ],
          name: 'value0',
          type: 'tuple',
        },
      ],
    },
    {
      name: 'setVariable',
      inputs: [{ name: 'someParam', type: 'uint128' }],
      outputs: [],
    },
    {
      name: 'setVariableExternal',
      inputs: [{ name: 'someParam', type: 'uint128' }],
      outputs: [],
    },
    {
      name: 'getSecondElementWithPrefix',
      inputs: [{ name: 'prefix', type: 'string' }],
      outputs: [{ name: 'value0', type: 'string' }],
    },
    {
      name: 'computeSmth',
      inputs: [
        { name: 'answerId', type: 'uint32' },
        { name: 'offset', type: 'uint32' },
      ],
      outputs: [
        {
          components: [
            { name: 'first', type: 'uint32' },
            { name: 'second', type: 'string' },
          ],
          name: 'res',
          type: 'tuple',
        },
      ],
    },
    {
      name: 'simpleState',
      inputs: [],
      outputs: [{ name: 'simpleState', type: 'uint128' }],
    },
  ],
  data: [{ key: 1, name: 'nonce', type: 'uint32' }],
  events: [
    {
      name: 'StateChanged',
      inputs: [
        {
          components: [
            { name: 'first', type: 'uint32' },
            { name: 'second', type: 'string' },
          ],
          name: 'complexState',
          type: 'tuple',
        },
      ],
      outputs: [],
    },
  ],
  fields: [
    { name: '_pubkey', type: 'uint256' },
    { name: '_timestamp', type: 'uint64' },
    { name: '_constructorFlag', type: 'bool' },
    { name: 'nonce', type: 'uint32' },
    { name: 'simpleState', type: 'uint128' },
    {
      components: [
        { name: 'first', type: 'uint32' },
        { name: 'second', type: 'string' },
      ],
      name: 'complexState',
      type: 'tuple',
    },
  ],
} as const; // NOTE: `as const` is very important here

To fully utilize the features of this library, it is important to declare ABI as a const object with a const type (which should be declared using as const.

Unfortunately, this approach has drawbacks that have to be tolerated for now (you can't import JSON as a const type, issue #32063)

Code of ExampleContract ​

pragma ever-solidity >=0.66;

// Define a custom struct `ComplexType` with two properties.
struct ComplexType {
	uint32 first;
	string second;
}

contract ExampleContract {
	uint32 static nonce;

	uint128 public simpleState;
	ComplexType complexState;

	// A modifier that refunds the sender after the function call.
	modifier cashBack() {
		tvm.rawReserve(address(this).balance - msg.value, 2);
		_;
		msg.sender.transfer({ value: 0, flag: 129 });
	}

	// Event emitted when the complexState is changed.
	event StateChanged(ComplexType complexState);

	// Constructor to initialize the contract state.
	constructor(uint128 someParam, string second) public {
		tvm.accept();
		simpleState = someParam;
		complexState = ComplexType(uint32(someParam % 1000), second);
	}

	// Function to get the current complexState.
	function getComplexState() external view returns (ComplexType) {
		return complexState;
	}

	// Function to set a new value for simpleState and complexState.first, refunds the sender after the call.
	function setVariable(uint128 someParam) public cashBack {
		_setVariable(someParam);
	}

	// Function to set a new value for `simpleState` and `complexState.first`.
	function setVariableExternal(uint128 someParam) public {
		tvm.accept();
		_setVariable(someParam);
	}

	// Internal function to update `simpleState` and `complexState.first`, and emit the `StateChanged` event.
	function _setVariable(uint128 someParam) internal {
		simpleState = someParam;
		complexState.first = uint32(someParam % 1000);
		emit StateChanged(complexState);
	}

	// Function to concatenate a given prefix with the `complexState.second` value.
	function getSecondElementWithPrefix(string prefix) external view returns (string) {
		return prefix + complexState.second;
	}

	// Function to compute and return an updated `ComplexType` value based on the given offset.
	function computeSmth(
		uint32 offset
	) external view responsible returns (ComplexType res) {
		require(offset < 1000, 1337);
		res.first = complexState.first + offset;
		res.second = complexState.second;
		return {value: 0, flag: 68, bounce: false} complexState;
	}
}

Contract Wrapper ​

Contract wrapper (ProviderRpcClient.Contract) is a preferred way to interact with contracts. It is tied to a specific address, it has a bunch of helpers and a proxy object with all methods. Construction doesn't make any requests or subscriptions (since this object doesn't have any state), however it serializes the provided ABI object, so you shouldn't create it in tight loops.

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

const exampleAddress = new Address('0:1f2656c5b9d351fbf1eb1f2053d086ade850c45290e5e0946900fb8ecc401348');
const example = new provider.Contract(exampleAbi, exampleAddress);

Reading contract ​

In most contracts all publicly visible data should be accessed by getters. They don't require user interaction, and only rely on basic permission, so they can be used even without extension via standalone client.

Contract wrapper has a methods Proxy object which contains all functions as properties. To execute a getter, you should first prepare its arguments and then execute the call method on the prepared object.

Simple getters ​

This type of getters is executed locally by simulating external message call and parsing external outgoing messages.

// Optionally request account state
const state = await provider.getFullContractState(exampleAddress);

// Simple getter without any parameters
const complexState = await example.methods.getComplexState().call({
  // You can call several getters "atomicly" on a single contract state
  cachedState: state,
});

// Another getter, but with parameters
const prefixedSecond = await example.methods
  .getSecondElementWithPrefix({
    // Arguments have the same type as described in ABI,
    // but merged into one object by `name`
    prefix: : 'foo',
  })
  .call({
    // NOTE: It will request the state itself if it is not specified
    cachedState: state,
  });

Responsible methods ​

This type of methods can either be called via internal message or locally as a getter via external message. It differs from simple getters as it has additional argument of type uint32 which is usually called answerId.

• When it is called on-chain, it returns the result in outgoing internal message to the caller with answerId as a function id.
• When it is called locally, it behaves the same way as simple getters. However, in this library you could call these methods with an additional responsible: true flag which executes them locally as internal messages. This allows you to skip headers and use the same function signature for contracts with different header configurations.

const computedResult = await example.methods
  .computeSmth({
    offset: : 1200,
    answerId: 13,
  })
  .call({
    responsible: true,
  });
const { value0: nonce } = await example.methods.getNonce({ answerId: 42 }).call({ responsible: true });
console.log(`Computed State: ${nonce}`);

TVM Exceptions ​

There can be exceptions during local contract execution. They may arise either due to an incorrect function signature or due to some checks in contract code. If an exception code is less than 100, then it is likely due to an incorrect ABI or signature or something else. Otherwise, it is an exception from the contract code, and you can find the reason if you have that code.

You can catch TVM exceptions using TvmException class. Although there might be some situations when execution fails due to a TVM exception, but other exception is thrown - in that case it is more likely due to incorrect input or contract state.

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

try {
  const computedSmth = await example.methods
    .computeSmth({
      // Offset is greater than 1000, so it will throw an exception
      offset: 1444,
    })
    .call();
} catch (e) {
  if (e instanceof TvmException) {
    console.log(`TVM Exception: ${e.code}`);
  } else {
    // Re-throw it othersise
    throw e;
  }
}

Sending Messages ​

External messages are used for calling functions in smart contracts from off-chain applications. To send an external message, you should use the contract wrapper, which provides a convenient way to interact with contracts. To call a function in a contract, use the following syntax:

External Msg ​

// Call the `setVariableExternal` function on the example contract with `someParam` as the parameter
const tx = await exampleContract.methods.setVariableExternal({ someParam: 42 }).sendExternal({
  publicKey: senderPublicKey,
});

console.log('Transaction:', tx);

Internal Msg ​

There are two ways to send internal messages in the blockchain: through the provider.Contract instance using the send method or using the Provider.sendMessage method. Both methods have their unique features, and developers should choose the one that best fits their needs.

1. Sending Internal Messages Through the Contract Instance To send an internal message through the contract instance, you need to call the contract's method directly and invoke the send method on the contract instance. The required parameters for this method are defined in the SendInternalParams type.

2. Using Provider.sendMessage This method provides a higher level of abstraction and flexibility, allowing developers to work with the provider directly instead of the contract instance. The required parameters for this method are defined in the ProviderApiRequestParams type.

// 1. Using the contract instance
const { transaction } = await exampleContract.methods.setVariableInternal({ someParam: 42 }).send({
  from: senderAddress,
  value: 1 * 10 ** 9,
  bounce: true,
});

// 2. Using the provider
// Define the payload for the internal message, including ABI, method, params, and flags
const payload = {
  abi: JSON.stringify(exampleAbi),
  method: 'setVariable',
  params: {
    someParam: 42,
  },
};

// Use provider.sendMessage to send an internal message with the specified sender, recipient, amount, bounce flag, and payload
const { transaction } = await provider.sendMessage({
  sender: senderAddress,
  recipient: exampleAddress,
  amount: 1 * 10 ** 9, // 1 Native coin
  bounce: true,
  payload: payload,
});

console.log('Transaction:', transaction);

Comparison and Differences ​

Both methods achieve the same goal of sending internal messages. However, there are some differences between them:

1. Abstraction Level: The provider.Contract.send method offers a lower level of abstraction, allowing developers to work directly with the contract instance and its methods. On the other hand, the ProviderRpcClient.sendMessage method provides a higher level of abstraction, allowing developers to work with the provider directly.

2. Ease of Use: Sending internal messages through the provider.Contract.send method is a more straightforward approach, as developers simply call the contract method and then use the send method to send the message. In contrast, using the ProviderRpcClient.sendMessage method requires specifying the payload, including the ABI, method, and parameters.

3. Flexibility: The ProviderRpcClient.sendMessage method provides more flexibility, as it can be used for different types of internal messages, including those with custom payloads or state initializations. This flexibility makes it a more suitable choice for advanced use cases or when working with multiple contracts.

Ultimately, the choice between these two methods depends on your specific use case and requirements. If you want a more straightforward and contract-focused approach, using the provider.Contract.send method might be the better option. However, if you need more flexibility or prefer working with the provider directly, the ProviderRpcClient.sendMessage method is an excellent choice.

Delayed Messages ​

In blockchain applications, there are situations when it is beneficial to send delayed messages (internal or external) instead of immediate ones. Delayed messages allow for more efficient execution of certain operations, reducing the waiting time for the user and improving the overall experience. By using delayed messages, developers can optimize their smart contracts and applications, ensuring better responsiveness and a smoother user experience.

To send a delayed internal message, you can use the Provider.sendMessageDelayed method. For external delayed messages, you can use the sendExternalDelayed method from the contract instance.

Here are examples of how to send both external and internal delayed messages:

External Msg ​

const { transaction, messageHash, expireAt } = await exampleContract.methods
  .setVariableExternal({ someParam: this.someParam })
  .sendExternalDelayed({
    publicKey: senderPublicKey!,
  });

console.log('Message hash:', messageHash);
console.log('Expire at:', expireAt);

transaction.then(() => {
  console.log('Transaction:', transaction);
});

Internal Msg ​

// 1. Using the contract instance
const { transaction } = await exampleContract.methods.setVariable({ someParam: 42 }).sendDelayed({
  from: senderAddress,
  value: 1 * 10 ** 9,
  bounce: true,
});

// 2. Using the provider
const { transaction, messageHash, expireAt } = await provider.sendMessageDelayed({
  sender: senderAddress,
  recipient: new Address(testContract.address),
  amount: 1 * 10 ** 9,
  bounce: true,
  payload: payload,
});

console.log('Message hash:', messageHash);
console.log('Expire at:', expireAt);

transaction.then(() => {
  console.log('Transaction:', transaction);
});

Deploying Contract ​

In the following example, we will demonstrate how to deploy a simple contract using the ProviderRpcClient. We will first generate the expected uninitialized contract address, then fund this address, and finally call the constructor of the contract to initialize it. Make sure to replace the base64Contract variable with the actual base64-encoded TON Virtual Machine-compatible contract (TVC) of your contract.

import { GetExpectedAddressParams, Contract } from 'everscale-inpage-provider';

type DeployParams<Abi> = GetExpectedAddressParams<Abi> & {
  publicKey: string | undefined;
};

const someParam = 1000;
const secondParam = 'test';

const deployParams: DeployParams<typeof ABI> = {
  tvc: base64Contract,
  workchain: 0,
  publicKey: senderPublicKey,
  initParams: {
    nonce: (Math.random() * 64000).toFixed(),
  },
};
// Get the expected contract address
const expectedAddress = await provider.getExpectedAddress(ABI, deployParams);

// Get the state init
const stateInit = await provider.getStateInit(ABI, deployParams);

// Define the constructor payload
const constructorPayload = {
  abi: JSON.stringify(ABI),
  method: 'constructor',
  params: {
    someParam: someParam.toString(),
    second: secondParam,
  },
};

// Send the coins to the address
await provider.sendMessage({
  sender: senderAddress,
  recipient: expectedAddress,
  amount: 1 * 10 ** 9, // 1 Coin in nanoсents
  bounce: false, // It is important to set 'bounce' to false to ensure funds remain in the contract.

  stateInit: stateInit.stateInit,
});

// Create a contract instance
const exampleContract: Contract<typeof ABI> = new provider.Contract(ABI, expectedAddress);

// Call the contract constructor
await exampleContract.methods
  .constructor({
    someParam: someParam,
    second: secondParam,
  })
  .sendExternal({
    stateInit: stateInit.stateInit,
    publicKey: deployParams.publicKey!,
  });