search

doiim / tikua

Isomorphic JS Cartesi package designed for seamless integration with any visual library on both Browser and Terminal environments. The SDK supports any provider or network, offering complete configurability to define applications with multiple chain support. It adapts to specific configurations and provides warnings for unsupported provider chains
Apache License 2.0
2 stars 1 forks source link

readme

Tikua logo

Tikua

Isomorphic JS package designed for seamless integration with any visual library on both Browser and Terminal environments. The SDK supports any provider or network, offering complete configurability to define applications with multiple chain support. It adapts to specific configurations and provides warnings for any unsupported provider chains.

Installation

npm install -s @doiim/tikua

Usage

You can jump directly to our Examples folder to see how to implement Tikua on multiple platforms. Additionally, you can find a detailed description of the Tikua Class and its functions.

Tikua SDK

The Tikua class is the main entry point for this SDK. It is instantiated with the following parameters:

const abi = [
  "function attackDragon(uint256 dragonId, string weapon)",
  "function dragonStatus(uint256 dragonId) returns (uint256)",
];
const tikua = new Tikua({
  appAddress: "0x0123123",
  appEndpoint: "https://host.backend/",
  provider,
  abi,
});

sendInput

Send a function input to the Cartesi contract.

Returns a promise that resolves to the transaction hash of the sent input.

const txHash = await tikua.sendInput("attackDragon", [1, "sword"]);
sequenceDiagram
    User->>+InputBox: sendInput
    InputBox->>+Cartesi Machine: Advance Input

fetchInspect

Fetch the inspect data for a transaction ID.

const status = await tikua.fetchInspect("dragonStatus", [dragonId]);
sequenceDiagram
    User->>+Cartesi Machine: Call Inspect
    Cartesi Machine-->Cartesi Machine: Create Report
    Cartesi Machine->>-User: Return Report

Returns a promise that resolves to the inspect data of the transaction.

addNoticesListener

Listen for all notices triggered by the Cartesi Machine

const unsubscribe = await tikua.addNoticesListener(1000, (result) => {
  console.log(result);
});
sequenceDiagram
    User->>+Tikua: addNoticesListener
    Tikua->>+User: return unsubscribe()
    Tikua->>+GraphQL Server: Fetch new Notices(recurrent)
    GraphQL Server-->>-User: Return new Notices
    User->>-Tikua: Call unsubscribe()
    Tikua->>-User: void

addVouchersListener

Adds a listener for vouchers, polling for new vouchers at a specified interval and executing a callback function for each new voucher.

Returns a function that can be called to stop listening for vouchers.

sequenceDiagram
    User->>+Tikua: addVouchersListener
    Tikua->>+User: return unsubscribe()
    Tikua->>+GraphQL Server: Fetch new Vouchers(recurrent)
    GraphQL Server-->>-User: Return new Vouchers
    User->>-Tikua: Call unsubscribe()
    Tikua->>-User: void

checkVoucher

Checks if a voucher has been executed on the Cartesi DApp. It requires the voucher to have a proof to verify its execution status.

Returns a promise that resolves to a boolean indicating whether the voucher has been executed.

fetchVouchersFromInput

Fetches a voucher from a specific input index and voucher index within the Cartesi DApp.

Returns a promise that resolves to an array of vouchers fetched from the specified input index.

executeVoucher

Executes a voucher on the Cartesi DApp by simulating the transaction and writing it to the blockchain upon success. This function is essential for processing vouchers, which are tasks or commands issued to the DApp.

Returns a promise that resolves to the transaction hash of the executed voucher transaction.

const voucher = {
  destination: "0x...",
  payload: "...",
  proof: "...",
};
const txHash = await tikua.executeVoucher(voucher);
console.log(txHash);
sequenceDiagram
    User->>+Dapp Contract: executeVoucher
    Dapp Contract->>User: Transaction hash
    Dapp Contract->>-Dapp Contract: Execute voucher transactions

depositEther

Deposits Ether on the Ether Portal by simulating the deposit transaction and returning the transaction hash.

Returns a promise that resolves to the transaction hash of the simulated deposit transaction.

approveERC20

Approves ERC20 tokens for deposit on the ERC20 Portal, simulating the approval transaction and returning the transaction hash.

Returns a promise that resolves to the transaction hash of the simulated approval transaction.

depositERC20

Deposits ERC20 tokens on the ERC20 Portal, simulating the deposit transaction and returning the transaction hash.

Returns a promise that resolves to the transaction hash of the simulated deposit transaction.

sequenceDiagram
    User->>+ERC20 Portal: depositERC20
    ERC20 Portal-->>User: return hash
    ERC20 Portal->>+Dapp Contract: Transfer Token
    ERC20 Portal->>-Cartesi Machine: Input(payload)

approveERC721

Approves an ERC721 token for deposit on the ERC721 Portal, simulating the approval transaction and returning the transaction hash.

Returns a promise that resolves to the transaction hash of the simulated approval transaction.

depositERC721

Deposits an ERC721 token on the ERC721 Portal, simulating the deposit transaction and returning the transaction hash.

Returns a promise that resolves to the transaction hash of the simulated deposit transaction.

sequenceDiagram
    User->>+ERC721 Portal: depositERC721
    ERC721 Portal-->>User: return hash
    ERC721 Portal->>+Dapp Contract: Transfer Token
    ERC721 Portal->>-Cartesi Machine: Input(payload)

approveSingleERC1155

This function is used to set approval for the ERC1155 Single Portal contract to transfer your tokens.

Returns the transaction hash of the simulated transaction.

const tokenAddress = "0x1234567890";
const txHash = await tikua.approveSingleERC1155(tokenAddress, true);

approveBatchERC1155

This function is used to approve ERC1155 tokens to be sent to the ERC1155 Batch Portal. It approves the portal to spend all tokens of this type.

Returns the transaction hash of the simulated approval transaction.

const tokenAddress = "0x1234567890";
const txHash = await tikua.approveBatchERC1155(tokenAddress, true);

depositSingleERC1155

Deposits a single ERC1155 token into the ERC1155 Single Portal. This function prepares and simulates a transaction to deposit a specified amount of a single ERC1155 token. It is designed to interact with the Cartesi infrastructure on a specified blockchain network.

Returns Promise<string> - A promise that resolves to the transaction hash of the simulated deposit transaction.

const tokenAddress = "0x...";
const tokenId = BigInt(1);
const amount = BigInt(100);
const baseLayerData = "";
const execLayerData = "";

const txHash = await tikua.depositSingleERC1155(
  tokenAddress,
  tokenId,
  amount,
  baseLayerData,
  execLayerData
);
sequenceDiagram
    User->>+ERC1155 Single Portal: depositSingleERC1155
    ERC1155 Single Portal-->>User: return hash
    ERC1155 Single Portal->>+Dapp Contract: Transfer Token
    ERC1155 Single Portal->>-Cartesi Machine: Input(payload)

depositBatchERC1155

Deposits a batch of ERC1155 tokens into the ERC1155 Batch Portal on a specified blockchain network. This function is designed to handle multiple tokens and their respective amounts in a single transaction, streamlining the deposit process for users.

Returns Promise<string> - A promise that resolves to the transaction hash of the deposit operation. This hash can be used to track the transaction on the blockchain.

const tokenAddress = "0xYourTokenAddressHere";
const tokenIds = [1n, 2n, 3n];
const amounts = [100n, 200n, 300n];
const baseLayerData = "";
const execLayerData = "";

const txHash = await tikua.depositBatchERC1155(
  tokenAddress,
  tokenIds,
  amounts,
  baseLayerData,
  execLayerData
);
sequenceDiagram
    User->>+ERC1155 Batch Portal: depositBatchERC1155
    ERC1155 Batch Portal-->>User: return hash
    ERC1155 Batch Portal->>+Dapp Contract: Transfer Tokens
    ERC1155 Batch Portal->>-Cartesi Machine: Input(payload)

Utility Static Functions

getCartesiDeploymentAddress

Retrieves the deployment address for a given contract on a specified chain.

Returns the deployment address of the specified contract.

getCartesiContractAbi

Retrieves the ABI (Application Binary Interface) of a Cartesi contract based on the provided contract name.

Returns the ABI of the specified Cartesi contract.

decodeEtherDeposit (For Backend decoding)

Decodes the payload of an Ether deposit transaction into an object containing the deposit details.

Returns an object containing the decoded details of the Ether deposit.

Throws an error if the payload is invalid.

decodeERC20Deposit (For Backend decoding)

Decodes the payload of an ERC20 deposit transaction into an object containing the deposit details.

Returns an object containing the decoded details of the ERC20 deposit.

Throws an error if the payload is invalid or the ERC20 deposit transaction failed.

decodeERC721Deposit (For Backend decoding)

Decodes the payload of an ERC721 deposit transaction into an object containing the deposit details.

Returns an object containing the decoded details of the ERC721 deposit.

Throws an error if the payload is invalid.

decodeERC1155SingleDeposit (For Backend decoding)

Decodes the payload of an ERC1155 single deposit transaction into an object containing the deposit details.

Returns an object containing the decoded details of the ERC1155 single deposit.

Throws an error if the payload is invalid.

decodeERC1155BatchDeposit (For Backend decoding)

Decodes the payload of an ERC1155 batch deposit transaction into an object containing the deposit details.

Returns an object containing the decoded details of the ERC1155 batch deposit.

Throws an error if the payload is invalid.

Backend

For the backend we use a framework call Deroll. It uses a Typescript backend structure centralized in an ABI protocol same way Tikua. You can start from an example implementation on our Examples folder. There you will find a project using Deroll framework to talk with a frontend using Tikua. Deroll uses ABI for encode and decode function calls/responses, accelerating your development in multiple aspects. Both Deroll and Tikua are based on Viem library for encode and decode ABI calls.

In case you don't want to use Deroll. You can easily decode Tikua inputs using View with the following syntax:

Using payload decoding on Advance

import { decodeFunctionData, parseAbi } from "viem";

// define application ABI
const abi = parseAbi(["function attackDragon(uint256 dragonId)"]);

const handleAdvance: AdvanceRequestHandler = async (data) => {
  // functionName will be the name of the function called on Tikua.
  // args are the arguments passed using Tikua
  const { functionName, args } = decodeFunctionData({
    abi,
    data: data.payload,
  });
  // Execute calls you want based on functionName and args passed.
  return "accept";
};

Using payload decoding on Inspect

import { decodeFunctionData, parseAbi, hexToString } from "viem";

// define application ABI
const abi = parseAbi(["function heroLife(address)"]);

const handleInspect: InspectRequestHandler = async (data) => {
  // functionName will be the name of the function called on Tikua.
  // args are the arguments passed using Tikua
  const { functionName, args } = decodeFunctionData({
    abi,
    data: hexToString(data.payload) as `0x${string}`,
  });
  // Execute calls you want based on functionName and args passed.
};

References

Human Readable ABI definition Viem library

For Maintainers

To deploy a new version use:

npm run build
npm publish

To deploy a local version for tests use:

npm run build
npm pack