Asset handling

Assets exist on the base layer, where they have actual meaning and value.

As with any execution layer solution, a Cartesi dApp that wants to manipulate assets needs a secure way of "teleporting" the assets from the base layer to the execution layer and then a way to "teleport" them back to the base layer.

Currently, Cartesi Rollups support the following types of assets:

• Ether (ETH)
• ERC-20
• ERC-721
• ERC-1155 Single
• ERC-1155 Batch

Deposits

Portals enable the safe transfer of assets from the base layer to the execution layer. Users authorize portals to deduct assets from their accounts and initiate transfers to dApps.

When an asset is deposited, it is on the base layer but gains a representation in the execution layer. The corresponding Portal contract sends an input via the InputBox contract describing the type of asset, amount, and some data the depositor might want the dApp to read. The off-chain machine will then interpret and validate the input payload.

Deposit input payloads are always specified as packed ABI-encoded parameters, as detailed below.

ABI encoding for deposits

Asset	Packed ABI-encoded payload fields	Standard ABI-encoded payload fields
Ether	address sender, uint256 value, bytes execLayerData	none
ERC-20	bool success, address token, address sender, uint256 amount, bytes execLayerData	none
ERC-721	address token, address sender, uint256 tokenId, standard ABI-encoded fields...	bytes baseLayerData, bytes execLayerData
ERC-1155 (single)	address token, address sender, uint256 tokenId, uint256 value, standard ABI-encoded fields...	bytes baseLayerData, bytes execLayerData
ERC-1155 (batch)	address token, address sender, standard ABI-encoded fields...	uint256[] tokenIds, uint256[] values, bytes baseLayerData, bytes execLayerData

Withdrawing assets

Users can deposit assets to a Cartesi dApp, but only the dApp can initiate withdrawals. When a withdrawal request is made, it’s processed and interpreted off-chain by the Cartesi Machine running the dApp’s code. Subsequently, the Cartesi Machine creates a voucher containing the necessary instructions for withdrawal, which is executable when an epoch has settled.

Vouchers are crucial in allowing dApps in the execution layer to interact with contracts in the base layer through message calls. They are emitted by the off-chain machine and executed by any participant in the base layer. Each voucher includes a destination address and a payload, typically encoding a function call for Solidity contracts.

The dApp’s off-chain layer often requires knowledge of its address to facilitate on-chain interactions for withdrawals, for example: transferFrom(sender, recipient, amount). In this case, the sender is the dApp itself.

By calling relayDAppAddress(), function of the DAppAddressRelay contract, it adds the dApp’s address as a new input for the Cartesi dApp to process. Next, the off-chain machine uses this address to generate a voucher for execution at the executeVoucher() function of the CartesiDApp contract.

epoch length

By default, Cartesi nodes close one epoch every 7200 blocks. You can manually set the epoch length to facilitate quicker asset-handling methods.

Here are the function signatures used by vouchers to withdraw the different types of assets:

Asset	Destination	Function signature
Ether	dApp contract	withdrawEther(address,uint256) 📄
ERC-20	Token contract	transfer(address,uint256) 📄
ERC-20	Token contract	transferFrom(address,address,uint256) 📄
ERC-721	Token contract	safeTransferFrom(address,address,uint256) 📄
ERC-721	Token contract	safeTransferFrom(address,address,uint256,bytes) 📄
ERC-1155	Token contract	safeTransferFrom(address,address,uint256,uint256,data) 📄
ERC-1155	Token contract	safeBatchTransferFrom(address,address,uint256[],uint256[],data) 📄