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.
Types
At a basic level everything in blockchain is a cell. Each cell consists of up to 1023 data bits and up to 4 references to other cells.
Name | Description | Representation in cell | Abi version |
---|---|---|---|
bool | Boolean type | 1 bit | ^1.0 |
intN | Fixed-sized signed integer, where N is a bit lengthe.g. int8 , int32 , int256 , .. | N bits | ^1.0 |
uintN | Fixed-sized unsigned integer, where N is a bit lengthe.g. uint8 , uint32 , .. | N bits | ^1.0 |
varintN | Variable-length signed integer. Bit length is between log2(N) and 8*(N-1) where N is either 16 or 32e.g. varint16 , varint32 . | 4+len*8 bits for varint16 or 5+len*8 bits for varuint32 where len is first 4 or 5 bits | ^2.1 |
varuintN | Variable-length unsigned integer. Bit length is between log2(N) and 8*(N-1) where N is either 16 or 32e.g. varint16 , varint32 . | Same as varintN | ^2.1 |
cell | TVM cell | Cell reference | ^1.0 |
address | Contract address | 267 bits (usually) | ^1.0 |
bytes | Byte array | A cell reference. This cell contains bytes, aligned to 8 bits with continuation in further references with same align | ^1.0 |
fixedbytesN | Fixed bytes array of length N (up to 32) | N*8 bits | ^1.0 |
string | Byte array which is required to be a valid UTF-8 sequence | Same as bytes | ^2.1 |
optional(T) | Can store a valut of T type or be empty.e.g. optional(string) | 1 bit flag, if it is set then T itself | ^2.1 |
tuple | A product of types. e.g. (uint256,bool,cell) NOTE: Requires components field in JSON ABI. | Same as a sequence of inner types | ^1.0 |
map(K,V) | Dictionary with key type K and value type V .e.g. map(uint32,address) NOTE: K can only be a type which can be represented in one cell. | 1 bit flag, if it is set then cell with dictionary | ^1.0 |
T[] | Array of type T .e.g. uint256[] | 32 bits of array length, then map(uint32,T) | ^1.0 |
ref(T) | Data of type T , but stored in a reference (cell).e.g. ref((uint32,address)) | Cell reference | ^2.2 |
In JSON ABI, types are described as follows:
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[];
};
Functions
In general, function calls are stored in message body, and encoded as function ID
+ encoded arguments
, where function ID
is the first 32 bits of sha256 of the function signature. However, external messages must contain a prefix with optional signature and encoded headers.
In JSON ABI, functions are described as follows:
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;
};
Events
Events are similar to functions, but they can only exist as an external outgoing message and doesn't have anything other than arguments. They are used to provide additional info during the transaction execution.
In JSON ABI, events are described as follows:
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
Code of the contract
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);
INFO
An Address
objects are used throughout the code instead of plain strings to prevent potential errors. However, requests through rawApi
use strings as it is a Proxy object which directly communicates with underlying provider object via JRPC.
Btw, if you have some hardcoded constant address you should better use AddressLiteral
which checks the provided string at compile time.
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;
}
}
Known TVM Exceptions
Basic exceptions
Please refer to the whitepaper 4.5.7
Code | Name | Definition |
---|---|---|
2 | Stack underflow | Not enough arguments in the stack for a primitive |
3 | Stack overflow | More values have been stored on a stack than allowed by this version of TVM |
4 | Integer overflow | Integer does not fit into expected range (by default −2256 ≤ x < 2256), or a division by zero has occurred |
5 | Range check error | Integer out of expected range |
6 | Invalid opcode | Instruction or its immediate arguments cannot be decoded |
7 | Type check error | An argument to a primitive is of incorrect value type |
8 | Cell overflow | Error in one of the serialization primitives |
9 | Cell underflow | Deserialization error |
10 | Dictionary error | Error while deserializing a dictionary object |
11 | Unknown error | Unknown error, may be thrown by user programs |
12 | Fatal error | Thrown by TVM in situations deemed impossible |
13 | Out of gas | Thrown by TVM when the remaining gas (g r ) becomes negative |
Solidity exceptions
Please refer to the docs
Code | Definition |
---|---|
40 | External inbound message has an invalid signature. See tvm.pubkey() and msg.pubkey() . |
50 | Array index or index of <mapping>.at() is out of range. |
51 | Contract's constructor has already been called. |
52 | Replay protection exception. See timestamp in pragma AbiHeader. |
53 | See <address>.unpack() . |
54 | <array>.pop call for an empty array. |
55 | See tvm.insertPubkey() . |
57 | External inbound message is expired. See expire in pragma AbiHeader. |
58 | External inbound message has no signature but has public key. See pubkey in pragma AbiHeader. |
60 | Inbound message has wrong function id. In the contract there are no functions with such function id and there is no fallback function that could handle the message. |
61 | Deploying StateInit has no public key in data field. |
62 | Reserved for internal usage. |
63 | See <optional(Type)>.get() . |
64 | tvm.buildExtMSg() call with wrong parameters. |
65 | Call of the unassigned variable of function type. See Function type. |
66 | Convert an integer to a string with width less than number length. See format() . |
67 | See gasToValue and valueToGas . |
68 | There is no config parameter 20 or 21. |
69 | Zero to the power of zero calculation. |
70 | string method substr was called with substr longer than the whole string. |
71 | Function marked by externalMsg was called by internal message. |
72 | Function marked by internalMsg was called by external message. |
73 | The value can't be converted to enum type. |
74 | Await answer message has wrong source address. |
75 | Await answer message has wrong function id. |
76 | Public function was called before constructor. |
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.
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.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 theProviderApiRequestParams
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:
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, theProviderRpcClient.sendMessage
method provides a higher level of abstraction, allowing developers to work with the provider directly.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 thesend
method to send the message. In contrast, using the ProviderRpcClient.sendMessage method requires specifying the payload, including the ABI, method, and parameters.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);
});
WARNING
All functions can be executed either via external or internal messages. However, if function is not marked as responsible
it will not return anything when called via an internal message.
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!,
});
Important Points
- The deployment process uses external inbound messages, which are designed for calling contracts from outside or deploying them without a source address or value.
- The contract address is generated using the getExpectedAddress method. This method returns the address of the uninitialized contract.
- Ensure the contract's ABI and deploy parameters are correctly defined before initiating the deployment process.
- The contract address must be funded before the constructor is called. Send funds to the contract address with the sendMessage method.
- When sending funds, set the bounce parameter in sendMessage to false. Since the contract has no code yet, it cannot process the incoming message. Setting bounce to false ensures that the funds remain in the contract and are not returned to the sender.