diff --git a/docs/evm/nac-usage.md b/docs/evm/nac-usage.md index 0431f3df..40ee94dd 100644 --- a/docs/evm/nac-usage.md +++ b/docs/evm/nac-usage.md @@ -44,9 +44,7 @@ gateway.callMichelson("KT1…", "default", michelsonParams); The `data` parameter must be encoded in Michelson binary format. For simple types you can construct the payload inline: for example, passing a `nat` with value 42 encodes as `hex"002a"` (tag `0x00` = integer, value `0x2a` = 42). Worked Solidity examples using this pattern are available in the [`solidity_examples/` directory](https://gitlab.com/tezos/tezos/-/tree/master/etherlink/kernel_latest/solidity_examples) of the Etherlink sources. For complex types, off-line tools such as Taquito's `packData` function can compute the encoding. -## Return value - -In the case of a regular Michelson call (`callMichelson`), there is no return value. +A Michelson call (via `callMichelson`) has no return value. ## `callMichelsonView` @@ -162,6 +160,9 @@ Because `callMichelson` is declared `external payable` (no return value), the re // success == false if Michelson reverted ``` +Note that for the specific case when the Michelson callee fails by going out of gas (OOG), it is wise to reserve some gas to handle the failure, otherwise you would OOG yourself and everything would revert. +See an examples of limiting the gas for the call in the [NAC walkthrough](/tutorials/nac-counter/). + ### `callMichelsonView` `callMichelsonView` follows the same failure model. Any of the following causes a revert that propagates to the EVM caller: diff --git a/docs/michelson/nac-usage.md b/docs/michelson/nac-usage.md index 0696e841..3e1697ae 100644 --- a/docs/michelson/nac-usage.md +++ b/docs/michelson/nac-usage.md @@ -151,6 +151,10 @@ IF_NONE { … } (* use the returned bytes *) ``` +:::note +Both `%call_evm` and `staticcall_evm` are implemented using a low-level entrypoint `%call` that exposes the internal HTTP protocol between the Michelson runtime and the EVM runtime. This is not a supported public interface. It adds nothing that a smart contract author would reach for in practice: `%call_evm` covers state-mutating calls, `staticcall_evm` covers read-only views. +::: + ## Address translation Cross-interface calls run under the caller's alias (see [Accounts and Aliases](/overview/accounts-and-aliases)). The gateway exposes two on-chain views to translate between native addresses and aliases. Both take the address as a `string` in its printable form (base58check for the Michelson interface, `0x…` hex for the EVM interface) rather than as a Michelson `address`, and identify interfaces by a `nat` runtime id: `0` for the Michelson interface, `1` for the EVM interface. Michelson has no instruction to convert an `address` to a `string`, so the address to translate must already be available as a `string`, for example as a parameter. diff --git a/docs/overview/resources.md b/docs/overview/resources.md index 8db7d18f..fe3722c8 100644 --- a/docs/overview/resources.md +++ b/docs/overview/resources.md @@ -27,6 +27,7 @@ When an EVM contract calls the Michelson gateway: 1. **Setting limits.** The EVM contract's remaining gas is converted to a Michelson gas limit using `c`. The Michelson storage limit is set to a generous upper bound (storage allocation in the Michelson interface is converted to gas when going back to the EVM interface). 2. **On failure.** The error is returned to the EVM caller, along with the remaining gas. The EVM caller can catch the failure and continue. +Note that if the Michelson callee failed by going out of gas (OOG), the EVM caller should have reserved some gas to handle the failure, otherwise it will OOG itself and everything reverts. 3. **On success.** The Michelson storage cost is expressed as additional EVM gas units: `g_storage = storage_cost / base_fee_per_gas`. The remaining EVM gas is converted from the remaining Michelson gas minus `g_storage`. If the resulting gas is negative, the call reverts with an out-of-gas error. In the end, storage allocation in the Michelson runtime is accounted as gas in the EVM runtime, which preserves its semantics.