Skip to main content

Interactions

What’s an Interaction?​

A MOI Interaction refers to any kind of action between participants on the MOI network. It results in a state change on the respective accounts of the interaction participants. For example, if Bob were to send Alice 1 unit of an asset, that asset must be deducted from Bob’s balance and credited to Alice; this is known as an Asset Transfer which is facilitated through AssetTransfer.

Other examples of Interaction in MOI include:

  • The creation of a new Asset
  • The transfer of one or more existing Assets between participants
  • The minting/burning of an existing supply adjustable Asset
  • The deployment of a new Logic
  • The invocation of a routine on an existing Logic

Just like Transactions in other blockchain networks, Interactions in MOI need to be broadcast to the whole network, and all Guardian nodes in the network compete to finalize them. Any node can attempt to finalize an Interaction by successfully locking the context of the Interaction participants, executing the Interaction and finalizing the state transitions on the participants. Interactions require a fee for the cost incurred by the network to validate & execute them.

Interaction vs Operation​

The primary difference between Interactions in MOI and Transactions in other blockchain protocols is the degree of general-purpose capability and flexibility.

  • An Interaction intrinsically describes unique state transitions based on its type, and thus it is very easy to optimize consensus and design specific zk-proofs for these Interactions because the scope of the state transition is limited.
  • A Operation, on the other hand, is designed to be a general-purpose wrapper and has a very large scope of state transition, thus limiting the ability of the network to perform advanced validation and other optimisations without relying on the operation execution layer.
  • While Interactions are designed to express transitions between participants, Transactions are intended to express transitions between network state checkpoints and hence better at expressing units of transition on a large-scale peer-to-peer network
  • Interactions are also capable of being highly customizable with participants being able to choose the parameters and constraints within which they are finalized, allowing for a very flexible modulation of trust.

Structure of an Interaction​

  • type - the type of the Interaction, eg, AssetTransfer or LogicInvoke
  • nonce - a sequentially increasing counter indicating the ixn number on the sender account.
  • sender - the address of the sender account. The interaction must be signed by the private key of this address. The execution fuel for the Interaction is deducted from the spendable balances of this account as KMOI tokens.
  • receiver - the address of the receiver account. This field can be omitted for Interaction types such as LogicDeploy and AssetCreate
  • fuel_price - the maximum cost for each unit of fuel, measured in KMOI tokens. At present, the only valid value for this is 1, signifying that each fuel unit equals 1 KMOI Token (1 fuel unit = 1 KMOI Token).
  • fuel_limit - the highest quantity of fuel units that the Interaction is allowed to consume. To proceed, the sender account must have a balance of KMOI tokens equal to or greater than this specified amount.
  • transfer_values - the amount of tokens for different assets to transfer from the sender to the receiver expressed as mapping of Asset ID to the transfer value.
  • payload - arbitrary data object depending on the Interaction type.

Example Interaction Objects​

{
    "nonce": 0,
    "sender": "0xbdfa7699df0d291d368a7d6bdda0a34d703458d2ba2c76c6a5dcac0915ce16ad",
    "fuel_price": "0x1",
    "fuel_limit": "0x200",
    "ix_operations": [
      {
        "type": 2, // AssetTransfer
        "beneficiary: "0x377a4674fca572f072a8176d61b86d9015914b9df0a57bb1d80fafecce233084",
        "asset_id": "0x00000000b8fe9f7f6255a6fa08f668ab632a8d081ad87983c77cd274e48ce450f0b349fd",
        "amount": "0xa"
      },
      {
        "type": 2, // AssetTransfer
        "beneficiary: "0x377a4674fca572f072a8176d61b86d9015914b9df0a57bb1d80fafecce233084",
        "asset_id": "0x00000001844181b39a1b15b417243e6231381b447a3f8b44aa15fbeb845c5d716696e71d",
        "amount": "0x1"
      }
    ]
}

Each Interaction type may require different fields to be set along with a different structure for the payload of the Interaction. Refer to the Types of Interactions section and the JSON-RPC Documentation for more information on the payload structure for each Interaction type.

This Interaction object needs to be POLO-encoded and signed with the private key of the sender, allowing to network to prove the origin and validity of the interaction. This process of encoding and signing the Interaction is typically handled by a client SDK like JS-MOI-SDK.

For more information on how to submit an Interaction to the network, refer to the tutorial on Submitting an Interaction.

Execution Fuel for an Interaction​

The Fuel parameters fuel_price and fuel_limit in the Interaction determine the fuel dynamics and cost of that Interaction. Fuel is paid for with the KMOI asset [Asset ID: 0x…].

  • Price adjustment of an Interaction is not supported for the Babylon TestNet, i.e, the fuel_price of an Interaction must always be 0x1 [1 fuel unit = 1 KMOI]. Any other value for this field will result in the Interaction being rejected by the network.
  • The account of the Interaction sender must have sufficient balance of KMOI for the specified fuel_limit of an Interaction. This fuel_limit value must be large enough for the cost of the Interaction execution (based on the Interaction Type). For LogicInvoke, additional FUEL will be charged based on code execution of the Logic.

For more information about Execution Fuel and KMOI in MOI. Refer to Execution Fuel.

Interaction Lifecycle​

Once the interactions has been submitted to the network the following happens:

  1. An interaction hash is cryptographically generated: 0x43d99bc7729218611a21b12c933c949d4f31684f1d6954ff417d0477538ff032
  2. The interaction is broadcast to the entire network and is added to the interaction pool consisting of other pending network interactions.
  3. Guardians will then attempt to finalize this Interaction (and other Interactions with the same context lock) by forming an ICS (Interaction Consensus Set) Cluster around it, the formation of this cluster indicates the successful locking on the context states of the interaction participants.
  4. Once the ICS is formed, all Guardians in the cluster will execute the Interactions, verify each other’s execution, update the participant contexts and agree on the state transition for each of the interaction participants. Once consensus is reached, the Interactions are bundled into a Tesseract for each participant and added to their respective participant Lattices.
  5. Each Interaction when included in a Tesseract is bundled with an Ixn Receipt with the proof and output of the Interaction. This receipt can be retrieved for interaction with the ixn hash.
  6. After successfully transitioning the context state of the interaction participants, the updated state is propagated to the rest of the network and the ICS cluster is dismissed.

At any point in time, millions of Interactions can be finalized in parallel across multiple ICS Clusters around the network that are being dynamically assembled and dismissed based on the context of the Interaction and its Participants.

Types of Interactions​

Interaction TypeIx TypeDescriptionBase Fuel CostExample RPC CallTutorial
ParticipantCreate1Create a new Participant with the given amount in the account. If the participant account does not exist, it will be created.100 FUEL per AssetParticipantCreatePending Tutorial
AssetTransfer1Transfer some Assets from the sender to the receiver. Each specified Asset must already exist. If the receiver account does not exist, it will be created.100 FUEL per AssetAssetTransferPending Tutorial
AssetCreate3Create a new native Asset with the given properties and return its unique Asset ID. The sender of this Interaction will be marked as the owner of the newly created Asset100 FUELAssetCreatePending Tutorial
AssetMint6Increase the supply of an Asset. The sender of this Interaction must be the owner of the Asset. The standard of the Asset must also support supply modulation. The newly minted supply is credited to owner’s account.100 FUELAssetMintPending Tutorial
AssetBurn7Decrease the supply of an Asset. The sender of this Interaction must be the owner of the Asset. The standard of the Asset must also support supply modulation. The amount to burn is deducted from the owner’s account.100 FUELAssetBurnPending Tutorial
LogicDeploy8Deploy a new Logic with the given Manifest and return its unique Asset ID. Optionally call a deployer routine to initialize its state (if it has one). The sender of this Interaction will be marked as the owner of the newly deployed Logic.100 FUEL for Manifest Compile + x FUEL for Deployer Code ExecutionLogicDeployPending Tutorial
LogicInvoke9Invoke a routine on a Logic with specified Callsite and Calldata. The Logic ID must already exist along with the Callsite on that Logic.x FUEL for Routine Code ExecutionLogicInvokePending Tutorial

Future Interaction Types​

The set of supported Interaction in MOI today, only covers the core capabilities of the MOI Protocol for the Babylon TestNet. This set will be extended in future rollouts to support capabilities like native fuel management, governance, voting, etc.