Codec

The @cartesi/codec package provides isomorphic utility functions to decode (and encode, for testing) data compliant with the Cartesi Rollups Inputs and Outputs interfaces, as well as the portal deposit input payloads packed-encoded by the InputEncoding library.

Inputs delivered to a Cartesi application and outputs produced by it are ABI-encoded as calls to the functions of those interfaces:

• inputs are encoded as EvmAdvance(uint256,address,address,uint256,uint256,uint256,uint256,bytes) calls;
• outputs are encoded as Notice(bytes), Voucher(address,uint256,bytes) or DelegateCallVoucher(address,bytes) calls.

The package decodes those blobs into friendly typed objects, and encodes typed objects back into blobs. The Input and Output TypeScript types are inferred directly from the Inputs and Outputs ABIs, so they always match the rollups-contracts release the package is built against. It works in browsers and Node.js, and depends only on viem and abitype.

Installation

Hex strings and byte arrays

Every decode function accepts the encoded data as a Hex string or as a Uint8Array (including subclasses like the Node.js Buffer), and the variable-size byte fields of the result follow the representation of the input: hex in, hex out; bytes in, bytes out. When decoding from a Uint8Array the byte fields are returned as zero-copy subarrays of the input, so low-level bindings that already hold binary data (e.g. machine I/O) can decode without hex conversions or copies:

import { decodeInput } from "@cartesi/codec";
 
declare const blob: Uint8Array; // e.g. straight from machine I/O
 
const input = decodeInput(blob);
input.payload; // Uint8Array, zero-copy view of `blob`

Every encode function takes an optional to parameter selecting the representation of the encoded data — "hex" (the default) or "bytes" — and accepts its byte fields in either representation:

import { encodeInput, decodeInput } from "@cartesi/codec";
 
declare const blob: Uint8Array;
 
const data = encodeInput(decodeInput(blob), "bytes"); // Uint8Array

Decode functions

• decodeInput — decode an EvmAdvance input blob
• decodeOutput — decode a Notice, Voucher or DelegateCallVoucher output blob

Encode functions

Each decode function has an encoding counterpart, useful for producing test fixtures:

• encodeInput
• encodeOutput
• encodeNotice
• encodeVoucher
• encodeDelegateCallVoucher

Portal deposit functions

Deposits made through the rollups portals arrive as inputs whose msgSender is the portal and whose payload is packed-encoded (abi.encodePacked) by the rollups contracts InputEncoding library. These functions decode (and encode, for testing) those payloads:

• decodeDeposit — decode any deposit, dispatching on the input's msgSender against the portal deployment addresses
• decodeEtherDeposit / encodeEtherDeposit
• decodeErc20Deposit / encodeErc20Deposit
• decodeErc721Deposit / encodeErc721Deposit
• decodeErc1155SingleDeposit / encodeErc1155SingleDeposit
• decodeErc1155BatchDeposit / encodeErc1155BatchDeposit

ABIs

The Inputs and Outputs ABIs used by the codec are also exported, both from the main entrypoint and from @cartesi/codec/abi:

import { inputsAbi, outputsAbi } from "@cartesi/codec/abi";