Cartesi Curl

CLI to send inputs/inspects to a Cartesi Rollups DApp, both running locally and deployed on remote testnet networks. It's implemented in Typescript and uses the ethers library to communicate with the rollups smart contracts.

Requirements

node.js
yarn

Building

To build the console application, first clone. Then, build the application by executing the following commands:

yarn
yarn build

Running

The console application can be used to perform several operations. The available commands can be queried as follows:

$ cartesi-curl --help

Commands:
  cartesi-curl erc20 <command>    Operations with ERC-20 tokens
  cartesi-curl erc721 <command>   Operations with ERC-721 tokens
  cartesi-curl input <command>    Operations with inputs
  cartesi-curl inspect            Inspect the state of the DApp
  cartesi-curl notice <command>   Operations with notices
  cartesi-curl report <command>   Operations with reports
  cartesi-curl voucher <command>  Operations with vouchers

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

In general terms, the application communicates with a Cartesi DApp through two different endpoints, one for layer-1 communication (underlying blockchain) and another for layer-2 communication (Cartesi Node). Layer-1 communication is used for sending data to the DApp, including depositing assets. On the other hand, communication through the layer-2 node is used when querying DApp information such as provable outputs (notices, vouchers) and application logs (reports), or when performing generic application-level queries (inspect).

Sending inputs

The input send command adds inputs to a Cartesi Rollups DApp and has the following format:

cartesi-curl input send --payload [message] <options>

Examples:

Send an input to the current locally deployed DApp using Hardhat's default funded account:
```
cartesi-curl input send --payload "my message"
```

Send an input to an instance of the echo-python DApp already deployed to the Ethereum Sepolia testnet, using a user's account and a user's gateway RPC on Alchemy:

export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

cartesi-curl input send --payload "my message" --dapp echo-python

Options

When sending data to a DApp, the console application needs to communicate with the underlying layer-1 blockchain. In order to do that, it needs the URL of a blockchain RPC gateway, the address of the DApp's Rollups smart contract on that blockchain, and an appropriate account with sufficient funds for submitting transactions to the network.

The following parameters are available to specify this configuration, with some default behaviors and values to make it convenient to the user, especially for a local development environment:

--rpc: provides the RPC URL of the remote blockchain gateway; if absent, its default value is "http://localhost:8545", which provides connectivity to the Hardhat node used for local development; it may also be specified by setting a value for the environment variable RPC_URL;
--address: represents an explicit definition for the address of the DApp's Rollups smart contract, given as a hex string; if absent, the console application will look for other ways to determine this address, as explained below
--addressFile: provides a path to a file containing the address as a hex string, and is only used if address is absent
--dapp: specifies the name of the DApp, with a default value of "dapp"; if both address and addressFile are absent, the console application will query the given RPC instance to infer the network being used, and will extract the DApp's address from file ../deployments/<network>/<dapp>.json; as such, if none of the above parameters are specified, the DApp address will be determined by looking for the file ../deployments/localhost/dapp.json;
--mnemonic: determines an account for submitting transactions; when using the localhost network, the application will use the default mnemonic for the local Hardhat node, which is already funded; otherwise, you must define a mnemonic for an account that has funds in the specified network; you can also define this parameter by setting the MNEMONIC environment variable;
--accountIndex: specifies an account index to use from the provided mnemonic; if absent, index 0 is used;

Listing notices, vouchers and reports

The notice list, voucher list and report list commands display DApp notices, vouchers and reports associated with the given epoch and input.

cartesi-curl notice list <options>

cartesi-curl voucher list <options>

cartesi-curl report list <options>

Examples:

List all notices ever emitted for the current locally deployed DApp:
```
cartesi-curl notice list
```
List all vouchers emitted for input 1 of the current locally deployed DApp:
```
cartesi-curl voucher list --input 1
```

List notices for input 3 of an echo-python DApp instance already deployed remotely:

cartesi-curl notice list --url https://<dapp-cartesi-node-url>/graphql --input 3

Options are:

--url      Reader URL
--input    Input index

If the url parameter is absent, the console application will use a default value of "http://localhost:4000/graphql", which provides connectivity to the local Cartesi Node.

Validating notices and executing vouchers

The notice validate command can be used to check if a given notice is authentic, meaning that its associated proof can be successfully verified by the Cartesi Rollups framework. In a similar way, the voucher execute command can be used to submit a transaction on layer-1 as an output of a Cartesi DApp (e.g., to withdraw funds back from the Rollups framework).

Both commands can only be executed if a proof is available for the specified notice or voucher. Proofs are only effectively produced when its associated epoch finishes, which happens after the DApp's configured epoch period elapses (e.g., after one week). In a local development environment, it is possible to explicitly advance time in order to finish an epoch and have proofs be generated by the framework.

cartesi-curl notice validate --index [index] --input [input] <options>

cartesi-curl voucher execute --index [index] --input [input] <options>

Examples:

Validate notice with index 0 of input 1 for the current locally deployed DApp, using Hardhat's default funded account:
```
cartesi-curl notice validate --index 0 --input 1
```
Execute voucher with index 1 of input 3 for the current locally deployed DApp, using Hardhat's default funded account:
```
cartesi-curl voucher execute --index 1 --input 3
```

Validate notice with index 0 of input 5 for an echo-python DApp already deployed to the Ethereum Sepolia testnet, using a user's account and a user's gateway RPC on Alchemy:

export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

cartesi-curl notice validate --index 0 --input 5 --dapp echo-python --url https://<dapp-cartesi-node-url>/graphql

Options are:

--index         Notice or Voucher index within its associated Input
--input         Input index
--rpc           URL of the RPC gateway to use
--address       DApp Rollups contract address
--addressFile   Path to a file containing the DApp Rollups contract address
--dapp          DApp name
--mnemonic      Wallet mnemonic
--accountIndex  Account index from mnemonic
--url           Reader URL

The url parameter has the same behavior as described for the notice/voucher list commands, whereas the other parameters behave as in the input send command.

Inspecting DApp state

The inspect command directly queries the DApp state within the Cartesi Machine. It can be used to send DApp-specific payloads that are interpreted by the application logic to yield a synchronous response. In practice, this command simply sends an HTTP GET request to the specified inspect URL, and does a little bit of parsing on the response.

cartesi-curl inspect --payload [payload] <options>

Examples:

Inspect the state of the locally deployed DApp using a REST-like query:
```
cartesi-curl inspect --payload "myresource?attr1=value1&attr2=value2"
```

Inspect the state of the echo-python DApp instance already deployed remotely:

cartesi-curl inspect --payload "mypayload" --url https://<dapp-cartesi-node-url>/inspect

Options are:

--url      Reader inspect URL

If the url parameter is absent, the console application will use a default value of "http://localhost:5005/inspect", which provides connectivity to the local Cartesi Node.

Depositing tokens

Deposits of both ERC-20 and ERC-721 tokens are supported via similar commands. Aside from what is described in the sections below, the commands parameters behave as described for the input send command.

Depositing ERC-20 tokens

The erc20 deposit command deposits ERC-20 tokens in the DApp.

cartesi-curl erc20 deposit --amount [amount] <options>

Examples:

Deposit 10 CTSI in the locally deployed DApp:

cartesi-curl erc20 deposit --amount 10000000000000000000

Deposit 10 CTSI in the echo-python DApp instance already deployed to the Ethereum Sepolia testnet, using a user's account and a user's gateway RPC on Alchemy:

export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

cartesi-curl erc20 deposit --amount 10000000000000000000 --dapp echo-python

Options are:

--erc20         ERC-20 address
--rpc           URL of the RPC gateway to use
--address       DApp Rollups contract address
--addressFile   Path to a file containing the DApp Rollups contract address
--dapp          DApp name
--mnemonic      Wallet mnemonic
--accountIndex  Account index from mnemonic

If the erc20 address is unspecified, the appropriate address for the SimpleERC20 token will be used for the target blockchain being specified.

Depositing ERC-721 tokens

The erc721 deposit command deposits ERC-721 tokens in the DApp.

cartesi-curl erc721 deposit --tokenId [token_id] <options>

Examples:

Deposit token with id 1 in the locally deployed DApp:
```
cartesi-curl erc721 deposit --tokenId 1
```

Deposit token with id 1 in the echo-python DApp instance already deployed to the Ethereum Sepolia testnet, using a user's account and a user's gateway RPC on Alchemy:

export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

cartesi-curl erc721 deposit --tokenId 1 --dapp echo-python

Options are:

--rpc           URL of the RPC gateway to use
--mnemonic      Wallet mnemonic
--accountIndex  Account index from mnemonic
--address       DApp Rollups contract address
--addressFile   Path to a file containing the DApp Rollups contract address
--dapp          DApp name
--erc721        ERC-721 contract address
--tokenId       The ID of the token being transfered

If the erc721 address is left unspecified, the address for the SimpleERC721 contract will be used for the target blockchain being specified.