Get methods

Get methods are smart contract methods that are supposed to be executed off-chain. They are useful for structured retrieval of data from a smart contract (get_collection_data get-method on an NFT collection), and for any logic that is a part of a smart contract but is needed off-chain (get_nft_address_by_index get-method on an NFT collection). Under the hood of APIs, this happens by fetching the actual state of the smart contract from the blockchain and executing TVM to get the result. This process is purely read-only and does not modify the blockchain state in any way.

Defining

Get methods are processed by the function selector. By convention, the ID of a get method is calculated as crc16("name") | 0x10000 where name is set by the developer. This simplifies practical usage because a human-readable name has to be used instead of some arbitrary number.

A minimal example of a smart contract that has a get method that follows the ID convention:

"Asm.fif" include

<{
  // The ID from the top of the stack is compared with 97865
  97865 EQINT
  // If ID != 97865, an 11 error is thrown by convention
  11 THROWIFNOT
  // Otherwise, 123 is pushed as the result
  123 PUSHINT
}>s

But in practice, it is easier to use PROGRAM{ from the Fift assembler that handles function selector logic.

"Asm.fif" include

PROGRAM{
  DECLPROC main
  // crc16("get_x") | 0x10000 = 97865
  97865 DECLMETHOD get_x
  main PROC:<{
  }>
  get_x PROC:<{
    123 PUSHINT
  }>
}END>s

The above is equivalent to the following Tolk code, which compiles to almost identical Fift code.

Tolk

fun main() { }

get fun get_x(): int {
    return 123;
}

Executing

In order to execute a get method, the actual state of the smart contract has to be fetched, and TVM has to be executed with c7 initialized and the desired parameters pushed on the stack.

Local way

With all the required values known, it is possible to execute a get method completely locally. A minimal example that uses a placeholder c7 for simplicity, as it is only necessary when the get method uses data from it during execution:

"Asm.fif" include

// example code
// could also be defined as a constant cell without using assembly
PROGRAM{
  DECLPROC main
  97865 DECLMETHOD get_x
  main PROC:<{
  }>
  get_x PROC:<{
    123 PUSHINT
  }>
}END>s constant code

// example data
// empty in this case
<b b> constant data

// example c7
// placeholder for simplicity
0 tuple 0x076ef1ea , 1 tuple constant c7

// execute method 97865
97865 code data c7 runvmctx .s
// result: 123 0 C{96A296D224F285C67BEE93C30F8A309157F0DAA35DC5B87E410B78630A09CFC7}
// where:
// 123 is the value returned by the get method
// 0 is the exit code
// C{...} is a new data cell

Note that if the get method uses some values from c7, for example with instructions such as NOW or MYCODE, the c7 tuple should be populated according to its structure.

Decentralized way

The process of fetching the actual contract state and initializing c7 can be handled by liteserver for easier execution. To execute a get method via liteserver, the request follows the liteServer.runSmcMethod TL schema.

In that request, params:bytes is a BoC of a serialized VmStack object containing the stack with arguments.

The response follows the liteServer.runMethodResult TL schema. Apart from the values used for initialization and proofs, the result is included as result:mode.2?bytes, which is a BoC of a serialized VmStack object, similarly to the request.

An example execution via liteclient that handles serialization:

runmethod UQBKgXCNLPexWhs2L79kiARR1phGH1LwXxRbNsCFF9doczSI get_public_key

Result:

arguments:  [ 78748 ]
result:  [ 37001869727465363790964079650574219024351072622925678701060821828351030750605 ]

High-level API

The easiest path is using a high-level API, such as TON Center. It has a /api/v3/runGetMethod endpoint that takes a smart contract address, a get method name, and arguments and returns the resulting stack. Example usage:

curl -X 'POST' \
  'https://toncenter.com/api/v3/runGetMethod' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "EQBG-g6ahkAUGWpefWbx-D_9sQ8oWbvy6puuq78U2c4NUDFS",
  "method": "get_nft_address_by_index",
  "stack": [
    {
      "type": "num",
      "value": "123"
    }
  ]
}'

The result for this call is presented below. The stack in this case contains a single cell element in BoC format.

{
  "gas_used": 4049,
  "exit_code": 0,
  "stack": [
    {
      "type": "cell",
      "value": "te6cckEBAQEAJAAAQ4AVoN3BhVDLKet4AYoVxOHz8WkaFncQfg/M79YWJEV4pxDg5fQi"
    }
  ]
}