DEV Community: SanchezDario

Cross-Contract Calls in Near Protocol

SanchezDario — Sat, 12 Feb 2022 22:16:35 +0000

Initial clarifications:

The following article is focused on the development of smart contracts using Rust.
Although the examples are developed in NEAR, much of the following information can be transposed to any other blockhain where it can be developed using Rust.
The examples are taken from the following repository: BlockJobs-Marketplace, where several cross-contract calls can be seen in addition to those used below.
This article shows a cross-contract call from a professional services marketplace, to the DAI contract, to allow payments for services in DAI or others fungible tokens.

Introduction:

There are various reasons for requiring calls between contracts, such as requesting and/or modifying information, using code from a third-party contract without copying it, transferring tokens, etc. and this can be done by working in a similar way to how API calls work.
An example of this is shown below, providing a contextual explanation of how a cross-contract call works.

1- Calling contract

To be able to call an external function, the first thing to do is to indicate to our contract what information the function that will be called requires, specifying parameters with their respective data types (in several contracts it is seen that &self is added and the type of data to return, but this can be omitted). For this you must first import near_sdk::ext_contract and implement it as shown below.

use near_sdk::ext_contract;

impl Contract {
   …
}

#[ext_contract(ext_contract)]
trait ExtContract {
fn ft_transfer(&mut self, receiver_id: AccountId, amount: U128, memo: Option<String>);
}
#[ext_contract(ext_self)]
pub trait ExtSelf {
    fn on_buy_service(service_id: u64) -> Service;
}

The 'ext_contract' in parentheses is the name that is being given and will then be used to indicate which trait is being called, since more than one can be set in order to have a better order.
'ExtContract' is a name that is not required later, that is, it is indifferent.
If the function that is called or not, is public, it is also indifferent, placing 'ft' is enough.
The name of the function and the parameters must be exactly the same as those of the contract that is called, in the event of any typing error we will receive an "insufficient gas amount" error.
The trait ExtSelf will be explained later.

1.1 - Make the call

Within the corresponding function, the call is made as follows:

ext_contract::ft_transfer(
   self.contract_me.clone(),
   service.metadata.price.into(),
   None,
   &token, 
   ONE_YOCTO, 
   GAS_FT_TRANSFER
).then(ext_self::on_buy_service(
   service_id,
   &env::current_account_id(), 
   NO_DEPOSIT, 
   BASE_GAS)
);

ft_transfer is being called passing first the 3 corresponding parameters, then the address of the contract (the DAI address must be passed in this case, which is assigned to token), then the amount of NEAR attached to the in the case of a payable type function and finally the amount of gas, a topic that will be expanded on later. The order of the parameters must be strictly respected, otherwise it will fail and the compiler does not always show an error.
The deposit and the gas are in this case assigned in constants, but the numerical value can also be specified directly.
The then method can be omitted, it is used in the case of wanting to execute a second function depending on what the called function returns, this is shown in more detail below.

1.2 - Call back

A second function can be created in the contract that makes the call, which, based on what is returned, executes certain actions. It is not strictly necessary but it is normally called with an on preceding the name of the first function, in the example case the function from which it is initially called is buy_service, so now the name will be on_buy_service and is given by the following code:

pub fn on_buy_service(&mut self, service_id: u64) -> Service {
  match env::promise_result(0) {
      PromiseResult::Successful(_data) => {
          service.sold = true;
          service.on_sale = false;
          self.service_by_id.insert(&service_id, &service);
          return service;
      }
      PromiseResult::Failed => env::panic(b"Callback faild"),
      PromiseResult::NotReady => env::panic(b"Callback faild"),
  };
}

In the event of an error in the call, a panic type error is executed with the message "Callback failed", if the call has been executed correctly, the code that modifies the state of the contract that initially calls is executed (this could done directly in the first function without the then method, but this is good practice.
In this case, the value that is returned is not being used, which is why the data parameter has a "_" in front of it, preventing a warning from being issued, but this value could be necessary for the status modification.
In the initially shared repository you can also see examples where this is omitted.
Although it is not used in this example, it can be useful to return a promise, for which near_sdk::PromiseOrValue must be imported, in this link expands on this topic.

2 - Called contract

The called contract can be one of its own or another, it is only necessary to know the address and the method to call with its parameters.
In the example case, the transfer function of the DAI contract is being called, so if the transfer is executed correctly, on_buy_service is subsequently executed and the status modified as indicated. However, the returned value could be other data such as a boolean for example and from this modify the information. In the example code you can see this by going to the validate_user and validate_tokens functions, both of which are in the mediator.rs contract.

3 - Gas Management

The most common error is "Insufficient gas amount", which can be due to an insufficient amount of gas set or attached, but also due to an error that prevents the called function from finishing executing and returning a result. In the event that this happens, it may be a good idea to issue logs at the beginning and end of each function to see how far the execution is carried out and also to comment the code where state changes are made to verify if the problem is in the call or in the internal code of some of the functions.
If the error is not found by performing the aforementioned, it may be that an amount of gas greater than the maximum supported by Near, which is 300 Tgas, is being established, if in the example 200 Tgas had been passed as a parameter to execute ft_transfer and 120 Tgas for on_buy_service, those 300 would never be enough, or in the case of working on testnet, it may be that not enough gas is being attached. For testing it may be advisable to specify the maximum amount of gas by adding --gas 300000000000000 to the end of the function call. Then the remaining gas is returned to the person who signs the transaction, but if you prefer this value can be adjusted by seeing how much gas is consumed, it is advisable to always indicate a higher amount, perhaps twice as much to ensure that it is not insufficient.

Final clarifications

Remember that it is advisable to write tests for the functions and the calls between contracts that are made.
To view information pertaining to gas usage and the values returned by the functions, you can use Near Explorer.
For questions, we recommend StackOverflow, or the Telegram channel for devs.

I hope this information has been useful to you.

Cross-Contract Calls en Near Protocol

SanchezDario — Sat, 12 Feb 2022 21:49:19 +0000

Aclaraciones iniciales:

El siguiente artículo está enfocado en el desarrollo de contratos inteligentes usando Rust.
Si bien los ejemplos están desarrollados en NEAR, gran parte de la siguiente información se puede transpolar a cualquier otra blockhain donde se pueda desarrollar usando Rust.
Los ejemplos son extraídos del siguiente repositorio: BlockJobs-Marketplace, donde se pueden observar varias cross-contract calls además de las utilizadas a continuación.
En este artículo se muestra una cross-contract call desde un marketplace de servicios profesionales, al contrato de DAI, para permitir realizar los pagos de los servicios en DAI.

Introducción:
Existen diversos motivos para requerir hacer llamadas entre contratos, como solicitar y/o modificar información, utilizar código de un contrato ajeno sin copiarlo, transferir tokens, etc. y esto se puede hacer trabajando de una forma similar a como funcionan las llamadas a una API.
A continuación se muestra un ejemplo de esto, brindando una explicación contextual de como una cross-contract call funciona.

1- Contrato que llama

Para poder llamar una función externa lo primero que se debe hacer es indicar a nuestro contrato qué información requiere la función que será llamada, especificando parámetros con sus respectivos tipos de datos (en varios contratos se ve que se agrega &selfy el tipo de dato a retornar, pero esto se puede omitir). Para esto primeramente se debe importar near_sdk::ext_contract e implementarlo como se muestra a continuación.

use near_sdk::ext_contract;

impl Contract {
   …
}

#[ext_contract(ext_contract)]
trait ExtContract {
fn ft_transfer(&mut self, receiver_id: AccountId, amount: U128, memo: Option<String>);
}
#[ext_contract(ext_self)]
pub trait ExtSelf {
    fn on_buy_service(service_id: u64) -> Service;
}

El 'ext_contract' entre paréntesis es el nombre que se le está dando y luego se utilizará para indicar qué trait se está llamando, ya que se puede establecer más de uno con el fin de tener un mejor orden.
'ExtContract' es una denominación que no se requiere posteriormente, es decir que es indiferente.
Si la función que es llamada o no, es pública, es también indiferente, con colocar 'ft' es suficiente.
El nombre de la función y los parámetros deben ser exactamente iguales a los del contrato que es llamado, ante cualquier error de tipeado recibiremos un error de "insufficient gas amount".

1.1 - Hacer el llamado

Dentro de la función correspondiente, el llamado se realiza de la siguiente forma:

ext_contract::ft_transfer(
   self.contract_me.clone(),
   service.metadata.price.into(),
   None,
   &token, 
   ONE_YOCTO, 
   GAS_FT_TRANSFER
).then(ext_self::on_buy_service(
   service_id,
   &env::current_account_id(), 
   NO_DEPOSIT, 
   BASE_GAS)
);

Se está llamando a ft_transfer pasando primeramente los 3 parámetros correspondientes, luego la dirección del contrato (se debe pasar la dirección de DAI en este caso, la cual está asignada a token), luego la cantidad de NEAR adjunto para el caso de tratarse de una función de tipo payable y finalmente la cantidad de gas, tema que será ampliado más adelante. El orden de los parámetros debe ser estrictamente respetado, de lo contrario fallará y no siempre el compilador muestra error.
El depósito y el gas están en este caso asignados en constantes, pero puede también especificarse el valor numérico directamente.
El método then puede omitirse, se utiliza en el caso de querer ejecutar una segunda función según lo que retorne la función que se está llamando, esto se muestra con mayor detalle a continuación.

1.2 - Call-back

Se puede crear una segunda función en el contrato que realiza la llamada, la cual a partir de lo que se retorna ejecute determinadas acciones. No es estrictamente necesario pero normalmente se le denomina con un on predecediendo al nombre la primer función, en el caso de ejemplo la función desde donde se llama inicialmente es buy_servicepor lo que ahora la denominación será on_buy_service y está dada por el siguiente código:

pub fn on_buy_service(&mut self, service_id: u64) -> Service {
  match env::promise_result(0) {
      PromiseResult::Successful(_data) => {
          service.sold = true;
          service.on_sale = false;
          self.service_by_id.insert(&service_id, &service);
          return service;
      }
      PromiseResult::Failed => env::panic(b"Callback faild"),
      PromiseResult::NotReady => env::panic(b"Callback faild"),
  };
}

En el caso de haber un error en el llamado se ejecuta un error de tipo panic con el mensaje "Callback faild", en caso de haberse ejecutado correctamente la llamada se ejecuta el código que modifica el estado del contrato que llama inicialmente (esto podría hacerse directamente en el primer función prescindiendo del método then, pero se trata de una buena práctica.
En este caso no se está haciendo uso del valor que se retorna, por esto es que la parámentro data tiene un "_" antepuesto, evitando que se emita un warning, pero podría ser necesario dicho valor para la modificación de estado.
En el repositorio compartido inicialmente se pueden ver también ejemplos donde se omite esto.
Si bien no se hace uso en este ejemplo, puede ser útil el retornar una promesa, para lo cual se debe importar near_sdk::PromiseOrValue, en este link se amplía este tema.

2 - Contrato que es llamado

El contrato que se llama puede tratarse tanto de uno propio como uno ajeno, tan solo es necesario conocer la dirección y el método a llamar con sus parámetros.
En el caso de ejemplo se está llamando a la función para transferir del contrato de DAI, por lo tanto si la transferencia se ejecuta correctamente, se ejecuta posteriormente on_buy_service y modificado el estado según se le indique. Sin embargo el valor retornado podría tratarse de otros datos como un booleano por ejemplo y a partir de este modificar la información. En el código de ejemplo se puede observar esto yendo a la función validate_user y validate_tokens, las cuales se encuentran en el contrato mediator.rs.

3 - Manejo del gas

El error más común es el de "Insufficient gas amount", el cual puede deberse a una insuficiente cantidad de gas establecido o adjuntado, pero también a un error que evite que la función llamada termine de ejecutarse y retornar un resultado. En el caso de suceder esto puede ser buena idea el emitir logs al principio y al final de cada función para ver hasta donde se realiza la ejecución y también el comentar el código donde se realiza cambios de estado para verificar si el problema está en la llamada o en el código interno de alguna de las funciones.
Si el error no se encuentra realizando lo antes mencionado , puede ser que se esté estableciendo una cantidad de gas mayor a la máxima soportada por Near que es de 300 Tgas, si en el ejemplo se hubiese pasado como parámetro 200 Tgas para ejecutar ft_transfery 120 Tgas para on_buy_service, esos 300 Tgas nunca serían suficientes, o en el caso de trabajar en testnet, puede ser que no se esté adjuntando el gas suficiente. Para hacer pruebas puede ser recomendable especificar la cantidad máxima de gas agregando --gas 300000000000000 al final del llamado a la función. Luego el gas sobrante se devuelve a quien firma la transacción, pero si se prefiere este valor puede ajustarse viendo cuánto gas se consume, es recomendable indicar siempre una cantidad mayor, quizás el doble para asegurarse de que no sea insuficiente.

Aclaraciones finales

Recuerde que es recomendable escribir test para las funciones y las llamadas entre contratos que se realicen.
Para ver información pertinente al uso de gas y los valores retornados por las funciones puede utilizar Near Explorer.
Para dudas se recomienda StackOverflow, o el canal de telegram para devs.

Espero esta información le haya sido de utilidad.