Skip to main content

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:

img

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.

img

ABI encoding for deposits

AssetPacked ABI-encoded payload fieldsStandard 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 duration

By default, Cartesi nodes close one epoch every couple of days. You can manually set the epoch duration to facilitate quicker asset-handling methods.

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

AssetDestinationFunction signature
EtherdApp contractwithdrawEther(address,uint256) 📄
ERC-20Token contracttransfer(address,uint256) 📄
ERC-20Token contracttransferFrom(address,address,uint256) 📄
ERC-721Token contractsafeTransferFrom(address,address,uint256) 📄
ERC-721Token contractsafeTransferFrom(address,address,uint256,bytes) 📄
ERC-1155Token contractsafeTransferFrom(address,address,uint256,uint256,data) 📄
ERC-1155Token contractsafeBatchTransferFrom(address,address,uint256[],uint256[],data) 📄

© 2024 Cartesi Foundation Ltd. All rights reserved.

The Cartesi Project is commissioned by the Cartesi Foundation.

We use cookies to ensure that we give you the best experience on our website. By using the website, you agree to the use of cookies.