Skip to main content

Overview

Contracts are invoked through a pair of host functions call and try_call:

  • try_call(contract, function, args) calls function exported from contract, passing args and returning a Status on any error.
  • call(contract, function, args) just calls try_call with its arguments and traps on Status, essentially propagating the error.

In both cases contract is a Binary host object containing the contract ID, function is a Symbol holding the name of an exported function to call, and args is a Vector of values to pass as arguments.

These host functions can be invoked in two separate ways:

  • From outside the host, such as when a user submits a transaction that calls a contract.
  • From within the host, when one contract calls another.

Both cases follow the same logic:

  • The contract's Wasm bytecode is retrieved from a CONTRACT_DATA ledger entry in the host's storage system.
  • A Wasm VM is instantiated for the duration of the invocation.
  • The function is looked up and invoked, with arguments passed from caller to callee.

When a call occurs from outside the host, any arguments will typically be provided in serialized XDR form accompanying the transaction, and will be deserialized and converted to host objects automatically before invoking the contract.

When a call occurs from inside the host, the caller and callee contracts share the same host and the caller can pass references to host objects directly to the callee without any need to serialize or deserialize them.

Since host objects are immutable, there is limited risk to passing a shared reference from one contract to another: the callee cannot modify the object in a way that would surprise the caller, only create new objects.