Skip to content

Create the payload to call a smart contract

Users can change the state of a smart contract by calling an action on the contract. To do this we create a transaction with a specific payload, sign it and send it to the blockchain.

A transaction targets a specific smart contract using its blockchain address and includes a payload that defines the action to call and its arguments. This payload, also known as RPC (remote procedure call), is a byte-encoded representation of the action (using a numeric shortname) and its arguments, serialized according to the RPC binary specification.

Every smart contract has an Application Binary Interface (ABI), which lists available actions and their required arguments. The ABI is stored on-chain as part of the contract and is essential for constructing transactions.

To view a contract’s available actions and arguments, run:

  cargo pbc abi show <path-to-ABI-file>

Below, we demonstrate two methods for creating an RPC payload:

  1. Manually creating RPC – Directly encoding the RPC serialization based on the ABI and RPC specification.
  2. Code Generation – Using the codegen tool to generate code for RPC serialization.

Manual creation of the RPC for the give_nickname action

We want to call the give_nickname-action on a Nickname contract from the examples. If you do not want to compile the contract yourself you can download the ABI here. Calling the abi show command on the ABI of the Nickname contract gives us

#[state]
pub struct ContractState {
    map: AvlTreeMap<Address, String>,
}
#[init]
pub fn initialize ()
#[action(shortname = 0x01)]
pub fn give_nickname (
    key: Address,
    value: String,
)
#[action(shortname = 0x02)]
pub fn remove_nickname (
    key: Address,
)

The Nickname contract has two actions. The give_nickname- and the remove_nickname-action. We would like to give the blockchain address 00123456789abcdef0123456789abcdef123456789 the nickname, perfection. To do this we need to create a transaction payload that calls the give_nickname action with the two parameters.

To create the correct RPC we follow the RPC specification.

This results in the following bytes in the RPC payload:

0x01 // The shortname for the give_nickname action.
0x00 0x12 0x34 0x56 0x78 0x9a 0xbc 0xde 0xf0 0x12 0x34 0x56 0x78 0x9a 0xbc 0xde 0xf1 0x23 0x45 0x67 0x89 // key: The 21-byte blockchain address.
0x00 0x00 0x00 0x0a // value: The length of the String 'perfection'.
0x70 0x65 0x72 0x66 0x65 0x63 0x74 0x69 0x6f 0x6e // value: The UTF-8 encoding of the String 'perfection'

Code Generation: Generate code from the ABI

Instead of coding the serializing of RPC manually like shown above, it is possible to generate code that implements the RPC serialization for a smart contract.

To generate the code from the ABI-file you use the following command.

cargo pbc abi codegen --dont-deserialize-state [target-language] <path-to-abi> <generated-code-output-path>

You can generate code in Java and TypeScript. The command generates a single file, that contains a method for each of the callable actions for the provided contract.

Code Generation: Generate code for the Nickname contract

To generate RPC serialization code for the Nickname contract. If you did not download the ABI, download the ABI now from here

Go to the folder the ABI is in and depending on the language the code generated should be in, run one of the following commands:

Using TypeScript

cargo pbc abi codegen --dont-deserialize-state --ts nickname.abi Nickname.ts
Generated TypeScript code for Nickname 
// This file is auto-generated from an abi-file using AbiCodegen.
/* eslint-disable */
// @ts-nocheck
// noinspection ES6UnusedImports
import {
  AbiByteInput,
  AbiByteOutput,
  AvlTreeMap,
  BlockchainAddress,
  BlockchainPublicKey,
  BlockchainStateClient,
  BlsPublicKey,
  BlsSignature,
  BN,
  Hash,
  Signature,
  StateWithClient,
} from "@partisiablockchain/abi-client";

type Option<K> = K | undefined;
export class Nickname {
  private readonly _client: BlockchainStateClient | undefined;
  private readonly _address: BlockchainAddress | undefined;

  public constructor(
    client: BlockchainStateClient | undefined,
    address: BlockchainAddress | undefined
  ) {
    this._address = address;
    this._client = client;
  }
}
export function initialize(): Buffer {
  return AbiByteOutput.serializeBigEndian((_out) => {
    _out.writeBytes(Buffer.from("ffffffff0f", "hex"));
  });
}

export function giveNickname(key: BlockchainAddress, value: string): Buffer {
  return AbiByteOutput.serializeBigEndian((_out) => {
    _out.writeBytes(Buffer.from("01", "hex"));
    _out.writeAddress(key);
    _out.writeString(value);
  });
}

export function removeNickname(key: BlockchainAddress): Buffer {
  return AbiByteOutput.serializeBigEndian((_out) => {
    _out.writeBytes(Buffer.from("02", "hex"));
    _out.writeAddress(key);
  });
}

The generated code will produce correct RPC according to the RPC binary specification.

Using Java

cargo pbc abi codegen --dont-deserialize-state --java nickname.abi Nickname.java
Generated Java code for Nickname 
// This file is auto-generated from an abi-file using AbiCodegen.
package com.partisiablockchain.language.abicodegen;

import com.partisiablockchain.BlockchainAddress;
import com.partisiablockchain.crypto.BlockchainPublicKey;
import com.partisiablockchain.crypto.BlsPublicKey;
import com.partisiablockchain.crypto.BlsSignature;
import com.partisiablockchain.crypto.Hash;
import com.partisiablockchain.crypto.Signature;
import com.partisiablockchain.language.codegenlib.AbiByteInput;
import com.partisiablockchain.language.codegenlib.AbiByteOutput;
import com.partisiablockchain.language.codegenlib.AbiGenerated;
import com.partisiablockchain.language.codegenlib.AvlTreeMap;
import com.partisiablockchain.language.codegenlib.BlockchainStateClient;
import com.partisiablockchain.language.codegenlib.StateWithClient;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.List;
import java.util.Map;
@AbiGenerated
public final class Nickname {
  private final BlockchainStateClient _client;
  private final BlockchainAddress _address;

  public Nickname(
      BlockchainStateClient client,
      BlockchainAddress address) {
    this._address = address;
    this._client = client;
  }

  public static byte[] initialize() {
    return AbiByteOutput.serializeBigEndian(_out -> {
      _out.writeBytes(HexFormat.of().parseHex("ffffffff0f"));
    });
  }

  public static byte[] giveNickname(BlockchainAddress key, String value) {
    return AbiByteOutput.serializeBigEndian(_out -> {
      _out.writeBytes(HexFormat.of().parseHex("01"));
      _out.writeAddress(key);
      _out.writeString(value);
    });
  }

  public static byte[] removeNickname(BlockchainAddress key) {
    return AbiByteOutput.serializeBigEndian(_out -> {
      _out.writeBytes(HexFormat.of().parseHex("02"));
      _out.writeAddress(key);
    });
  }

}