Submitting an Interaction

Prerequisites

To effectively utilise this guide, we recommend reading the docs regarding Interactions.

Getting Started

This is a beginner’s guide to sending a MOI Interaction using the JS-MOI-SDK. Interactions can also be fired with the JSON-RPC API but users would have to manage the serialisation and signing manually. Alternatively, MOI Voyage offers a simple GUI playground to make RPC Calls and Send Interactions.

Setting up JS-MOI-SDK

The JS-MOI-SDK package is a client library for interacting with the MOI Network using its JSON-RPC interface and can handle POLO serialization and Interaction signing as well. The JS-MOI-SDK package is published on NPM and can be installed from NPM.

npm i js-moi-sdk

To access the JSON-RPC API of the protocol, we usually use the JsonRpcProvider provider but this is applicable only if you are connecting to a node you have access to. The MOI Voyage service provides access to Babylon Protocol RPC with gated and rate-limited access to it when using the VoyageProvider provider.

import { VoyageProvider } from "js-moi-sdk";

// Setup the Voyage JSON-RPC Provider for the Babylon Network
const provider = new VoyageProvider('babylon');

To sign Interactions with JS-MOI-SDK, we need to set up the wallet signer for the sender account. This can be done from a private key mnemonic (for testing) or with a wallet keystore (for production).

Initialize the Wallet with a Private Key Mnemonic

When first registering with MOI Voyage, it will generate 3 different key pairs in your HD wallet that can be used to work with the Babylon Network. Each of these key pairs are derived from the master private key of the wallet with derivation path. You should be able to view this path listed along side the each of the 3 available accounts in Voyage.

For testing and development, we can directly derive the private key of the account from which we wish to send Interaction using its master private key mnemonic and derivation path to the key pair.

// Declare the private key mnemonic for the wallet
const mnemonic = "dizzy soft dwarf ice club crouch mutual outside month shrimp whisper dad";

// Declare the HD wallet path. This path is obtained from your MOI Voyage Dashboard
const path = "m/44'/6174'/7020'/0/0"

Lastly, we define a helper function to load the wallet signer instance for a given provider. This function can be called to return a new instance of the wallet signer for the account parameters we discussed above.

import { Wallet } from "js-moi-sdk";

const loadWallet = async (provider, mnemonic) => {
  const wallet = await Wallet.fromMnemonic(mnemonic, path);
  wallet.connect(provider);
  return wallet;
};

Initialize the Wallet from its Keystore

We can use the wallet keystore to initialize the wallet signer. The keystore is a JSON data structure.

const keystore = `{
    "cipher": "aes-128-ctr",
    "ciphertext": "...",
    "cipherparams": {
        "IV": "..."
    },
    "kdf": "scrypt",
    "kdfparams": {
        "n": 4096,
        "r": 8,
        "p": 1,
        "dklen": 32,
        "salt": "..."
    },
    "mac": "..."
}`;

We can then use the Wallet.fromKeystore method to initialize the wallet signer from the keystore.

import { Wallet } from "js-moi-sdk";

const loadWalletFromKeystore = async (provider, keystore, password) => {
  const wallet = Wallet.fromKeystore(keystore, password);
  wallet.connect(provider);
  return wallet;
};

Steps to Submit an Interaction

In this guide, we will discuss firing a simple IxAssetTransfer Interaction to transfer 50 tokens of the Asset ID 00000000b8fe9f7f6255a6fa08f668ab632a8d081ad87983c77cd274e48ce450f0b349fd to the receiver 0x916f62f7bdf311ba46d9df465283aa4e97a5dcf36e4c0761bc7d87d32557f8cc.

Refer to the JSON-RPC Documentation for the payload format of other Interaction types.

1. Constructing an Interaction

To submit an Interaction, we need to construct a payload object which must then be POLO-serialized and then signed by the private key of the sender’s account. This raw Interaction data and the signature are sent to the network with moi.SendInteraction RPC call.

We construct the Interaction payload as follows:

// IxAssetTransfer Interaction to transfer 50 tokens of an Asset 0x..49fd 
// from the initialized wallet to the address, 0x916..8cc.

const interaction = {
  type: IxType.VALUE_TRANSFER,
  sender: wallet.address,
  receiver: "0x916f62f7bdf311ba46d9df465283aa4e97a5dcf36e4c0761bc7d87d32557f8cc",
  nonce: await wallet.getNonce(),
  transfer_values: new Map([
    ["0x00000000b8fe9f7f6255a6fa08f668ab632a8d081ad87983c77cd274e48ce450f0b349fd", 100]
  ]),
  fuel_price: 1,
  fuel_limit: 100,   
}

2. Serializing & Signing the Interaction

This interaction must be serialized and signed by private key of the wallet to generate an object payload for the moi.SendInteraction RPC Call. This can be done with the following code:

// Serialize the Interaction and sign it with the wallet

const wallet = await loadWallet(provider, mnemonic);

const payload = wallet.signInteraction(interaction);
console.log("Payload:", payload);

Payload: {
 "ix_args": "0e9f0203131696049608900c900c930ca30cb60c03f350520ebca8c09efa19f2ed13012ceb70b2e710241748f4ac11bd4a9b43949b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001c80edf01031653830183018101810180010354455354130d41",
 "signature": "01473045022100e64317f1a0e16ed6b6280ca08881196f7be64a88367a4021f0708b7c3e19528702203d400c1cd5977205d949d00c87700f920c81bc6a5769d8caa8a0829f6965121b02"
}

info

This process of preparing the final payload is handled automatically by the JS-MOI-SDK and does not need to be performed by the developer. We can now proceed to submit the Interaction.

3. Submitting the Interaction

We now submit the interaction to the network and get the Interaction Hash for the submitted Interaction as a response. This Interaction Hash is cryptographically generated and acts as a unique identifier for the submitted Interaction.

When sending the Interaction with wallet.sendInteraction, the nonce and sender fields are automatically added and do not need to be manually entered as we showed above.

// Submit the Interaction to the network
const ix = await wallet.sendInteraction(interaction)

// Obtain the Interaction Hash from the response and print it
console.log("Interaction Hash: ", ix.hash)

// Console Output
Interaction Hash: 0xf72c8a2c2ab15cd1264392c60723972c22730bab541a3e78f16dae010a0b2c22

4. Wait for the Interaction Receipt

Now that we have submitted the Interaction, we wait for the Interaction Receipt confirming that the Interaction has been finalized. This usually occurs within 0.2 seconds, but if the load on the network is very high, it can take a little longer. We can poll for the status on receipt with the following code:

// Poll the network for the Interaction Receipt and print it
const receipt = await ix.wait()
console.log("Interaction Receipt: ", receipt)

// Console Output
Interaction Receipt: {
  ix_type: '0x1',
  ix_hash: '0xf72c8a2c2ab15cd1264392c60723972c22730bab541a3e78f16dae010a0b2c22',
  status: 0,
  fuel_used: '0x64',
  hashes: [
    {
      address: '0x6ef7715969a7a99edf06957e94494e40203b4be2b0ffb325196677a82de6fcb6',
      state_hash: '0xc8b8373f7c793c372768d8b64753a1531b26c392e10f97e5ae7a42d7e24e63ac',
      context_hash: '0x31fe4fc957c5062f3dd8a9174bb0b0b74be467411d4c9b41e4ce73ae2b25fdf1'
    },
    {
      address: '0x9c6cc5cccfe2a3dc447bce25f88cb28ce142459057e6c04b59911b6d3f10930a',
      state_hash: '0xca2b191689624d32576f4d9b67625874e08361f85fcb27be3591240ce86fccc3',
      context_hash: '0x554628df5586c6c6f4d246f51920a0101c98e878728542cbdb1272d30bb2aa29'
    }
  ],
  extra_data: null,
  from: '0x9c6cc5cccfe2a3dc447bce25f88cb28ce142459057e6c04b59911b6d3f10930a',
  to: '0x6ef7715969a7a99edf06957e94494e40203b4be2b0ffb325196677a82de6fcb6',
  ix_index: '0x0',
  parts: [
    {
      address: '0x6ef7715969a7a99edf06957e94494e40203b4be2b0ffb325196677a82de6fcb6',
      hash: '0x865e6601c44596ee238fbea1c3cc92df3330c5928977304ad0e051a75dd9113b',
      height: '0xb'
    },
    {
      address: '0x9c6cc5cccfe2a3dc447bce25f88cb28ce142459057e6c04b59911b6d3f10930a',
      hash: '0x266422f33375b8ba60537ffd790801dbf983a6887121e02f2c9a3a8cc3461cec',
      height: '0x9'
    }
  ]
}

Further Reading

Now that we have successfully submitted a simple IxAssetTransfer Interaction, we can attempt to build simple applications that leverage the capabilities of MOI using the Asset and Logic capabilities of the protocol. Happy Hacking!

• JSON-RPC Documentation
• Create & Manage Assets in MOI
• Deploy & Invoke Logics in MOI

---