From 399b517f416b3a7f78918f1ab3c2265f2763cc49 Mon Sep 17 00:00:00 2001 From: Guilherme Dantas Date: Sat, 13 Jul 2024 22:57:55 -0300 Subject: [PATCH] Document CLI --- apps/site/pages/docs/cli/cmd/decode/input.mdx | 97 ++++++++++++ .../site/pages/docs/cli/cmd/decode/output.mdx | 140 ++++++++++++++++++ .../cli/cmd/encode/delegatecallvoucher.mdx | 48 ++++++ apps/site/pages/docs/cli/cmd/encode/input.mdx | 94 ++++++++++++ .../site/pages/docs/cli/cmd/encode/notice.mdx | 38 +++++ .../pages/docs/cli/cmd/encode/voucher.mdx | 56 +++++++ apps/site/pages/docs/cli/installation.mdx | 14 +- apps/site/vocs.config.ts | 62 +++----- 8 files changed, 498 insertions(+), 51 deletions(-) create mode 100644 apps/site/pages/docs/cli/cmd/decode/input.mdx create mode 100644 apps/site/pages/docs/cli/cmd/decode/output.mdx create mode 100644 apps/site/pages/docs/cli/cmd/encode/delegatecallvoucher.mdx create mode 100644 apps/site/pages/docs/cli/cmd/encode/input.mdx create mode 100644 apps/site/pages/docs/cli/cmd/encode/notice.mdx create mode 100644 apps/site/pages/docs/cli/cmd/encode/voucher.mdx diff --git a/apps/site/pages/docs/cli/cmd/decode/input.mdx b/apps/site/pages/docs/cli/cmd/decode/input.mdx new file mode 100644 index 0000000..74d6798 --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/decode/input.mdx @@ -0,0 +1,97 @@ +# cmioc decode input + +Decodes an input blob according to the [`EvmAdvance`] function signature. + +:::code-group + +```bash [Command] +cmioc decode input +``` + +```json [Output JSON Schema] +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Input", + "definitions": { + "Hex": { + "type": "string", + "pattern": "^0x([0-9A-Fa-f]{2})*$" + }, + "Address": { + "type": "string", + "pattern": "^0x[0-9A-Fa-f]{40}$" + }, + "bigint": { + "type": "string", + "pattern": "^[0-9]+$" + } + }, + "type": "object", + "properties": { + "chainId": { "$ref": "#/definitions/bigint" }, + "appContract": { "$ref": "#/definitions/Address" }, + "msgSender": { "$ref": "#/definitions/Address" }, + "blockNumber": { "$ref": "#/definitions/bigint" }, + "blockTimestamp": { "$ref": "#/definitions/bigint" }, + "prevRandao": { "$ref": "#/definitions/bigint" }, + "index": { "$ref": "#/definitions/bigint" }, + "payload": { "$ref": "#/definitions/Hex" } + }, + "required": [ + "chainId", + "appContract", + "msgSender", + "blockNumber", + "blockTimestamp", + "prevRandao", + "index", + "payload" + ], + "additionalProperties": false +} +``` + +::: + +## Example + +:::code-group + +```txt [Input] +0x415bf363000000000000000000000000000000000000000000000000000000000000000100000000000000000000000070ac08179605af2d9e75782b8decdd3c22aa4d0c000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266000000000000000000000000000000000000000000000000000000000000002a00000000000000000000000000000000000000000000000000000000000111705a41539c3688747a1a8c7811b98b0427331ff73aab018eb5c9921993d617f314000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000 +``` + +```json [Output] +{ + "chainId": "1", + "appContract": "0x70ac08179605AF2D9e75782b8DEcDD3c22aA4D0C", + "msgSender": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + "blockNumber": "42", + "blockTimestamp": "70000", + "prevRandao": "40823578488146031703637781058841789769586951870728503003341100870835983872788", + "index": "10", + "payload": "0xdeadbeef" +} +``` + +::: + +## Positional arguments + +### [blob] + +`bytes` + +The input blob. If absent, reads from standard input. + +## Options + +### -b, --binary + +If a blob is not provided as argument, read from standard input in binary format. + +### -h, --help + +Display help for command. + +[`EvmAdvance`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Inputs.sol#L9-L28 diff --git a/apps/site/pages/docs/cli/cmd/decode/output.mdx b/apps/site/pages/docs/cli/cmd/decode/output.mdx new file mode 100644 index 0000000..5788864 --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/decode/output.mdx @@ -0,0 +1,140 @@ +# cmioc decode output + +Decodes an output blob according to the [`Outputs`] interface. + +:::code-group + +```bash [Command] +cmioc decode output +``` + +```json [Output JSON Schema] +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Output", + "definitions": { + "Hex": { + "type": "string", + "pattern": "^0x([0-9A-Fa-f]{2})*$" + }, + "Address": { + "type": "string", + "pattern": "^0x[0-9A-Fa-f]{40}$" + }, + "bigint": { + "type": "string", + "pattern": "^[0-9]+$" + } + }, + "oneOf": [ + { + "type": "object", + "properties": { + "type": { "const": "notice" }, + "payload": { "$ref": "#/definitions/Hex" } + }, + "required": ["type", "payload"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { "const": "voucher" }, + "destination": { "$ref": "#/definitions/Address" }, + "value": { "$ref": "#/definitions/bigint" }, + "payload": { "$ref": "#/definitions/Hex" } + }, + "required": ["type", "destination", "value", "payload"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { "const": "delegatecallvoucher" }, + "destination": { "$ref": "#/definitions/Address" }, + "payload": { "$ref": "#/definitions/Hex" } + }, + "required": ["type", "destination", "payload"], + "additionalProperties": false + } + ] +} +``` + +::: + +## Examples + +### Notice + +:::code-group + +```txt [Input] +0xc258d6e500000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000 +``` + +```json [Output] +{ + "type": "notice", + "payload": "0xdeadbeef" +} +``` + +::: + +### Voucher + +:::code-group + +```txt [Input] +0x237a816f000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb922660000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000003fafafa0000000000000000000000000000000000000000000000000000000000 +``` + +```json [Output] +{ + "type": "voucher", + "destination": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + "value": "1000000000000000000", + "payload": "0xfafafa" +} +``` + +::: + +### Delegate Call Voucher + +:::code-group + +```txt [Input] +0x10321e8b000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb9226600000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003fafafa0000000000000000000000000000000000000000000000000000000000 +``` + +```json [Output] +{ + "type": "delegatecallvoucher", + "destination": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + "payload": "0xfafafa" +} +``` + +::: + +## Positional arguments + +### [blob] + +`bytes` + +The output blob. If absent, reads from standard input. + +## Options + +### -b, --binary + +If a blob is not provided as argument, read from standard input in binary format. + +### -h, --help + +Display help for command. + +[`Outputs`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol diff --git a/apps/site/pages/docs/cli/cmd/encode/delegatecallvoucher.mdx b/apps/site/pages/docs/cli/cmd/encode/delegatecallvoucher.mdx new file mode 100644 index 0000000..80755f6 --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/encode/delegatecallvoucher.mdx @@ -0,0 +1,48 @@ +# cmioc encode delegatecallvoucher + +Encodes a delegate call voucher according to the [`DelegateCallVoucher`] function signature. +A delegate call voucher represents a [`DELEGATECALL`] instruction to be performed in the context of the [`Application`] contract. + +:::code-group + +```bash [Command] +cmioc encode delegatecallvoucher \ + --destination 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \ + --payload 0xfafafa +``` + +```txt [Output] +0x10321e8b000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb9226600000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003fafafa0000000000000000000000000000000000000000000000000000000000 +``` + +::: + +## Required options + +### --destination \ + +`address` + +The Ethereum address to be called, which is typically that of a smart contract. + +### --payload \ + +`bytes` + +The data to be passed along the call, which typically encodes a [Solidity function call]. + +## Other options + +### -b, --binary + +Write the blob to standard output in binary format. + +### -h, --help + +Display help for command. + +[Solidity function call]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding +[Wei]: https://ethereum.org/en/glossary/#wei +[`Application`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/dapp/Application.sol +[`DELEGATECALL`]: https://www.evm.codes/#f4?fork=cancun +[`DelegateCallVoucher`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol#L26-L34 diff --git a/apps/site/pages/docs/cli/cmd/encode/input.mdx b/apps/site/pages/docs/cli/cmd/encode/input.mdx new file mode 100644 index 0000000..36134bd --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/encode/input.mdx @@ -0,0 +1,94 @@ +# cmioc encode input + +Encodes an input according to the [`EvmAdvance`] function signature. + +:::code-group + +```bash [Command] +cmioc encode input \ + --chain-id 1 \ + --app-contract 0x70ac08179605AF2D9e75782b8DEcDD3c22aA4D0C \ + --msg-sender 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \ + --block-number 42 \ + --block-timestamp 70000 \ + --prev-randao 123456789 \ + --index 10 \ + --payload 0xdeadbeef +``` + +```txt [Output] +0x415bf363000000000000000000000000000000000000000000000000000000000000000100000000000000000000000070ac08179605af2d9e75782b8decdd3c22aa4d0c000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266000000000000000000000000000000000000000000000000000000000000002a000000000000000000000000000000000000000000000000000000000001117000000000000000000000000000000000000000000000000000000000075bcd15000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000 +``` + +::: + +## Required options + +### --chain-id \ + +`uint256` + +The [EIP-155] ID of the chain to which the [`InputBox`] contract was deployed. + +### --app-contract \ + +`address` + +The address of the [`Application`] contract to which the input is destined. + +### --msg-sender \ + +`address` + +The address of the account that called the [`addInput`] function on the [`InputBox`] contract. +In the case of a deposit input, this should be the address of the appropriate portal contract. + +### --block-number \ + +`uint256` + +The number of the block in which the input was added. + +### --block-timestamp \ + +`uint256` + +The timestamp of the block in which the input was added. + +### --prev-randao \ + +`uint256` + +The latest RANDAO mix of the post beacon state of the previous block. +See [EIP-4399] for notes on how to safely use this value as a source of randomness. + +### --index \ + +`uint256` + +The zero-based index of the input in the input box of the application. + +### --payload \ + +`bytes` + +The actual data being transmitted to the application. +From the perspective of the smart contracts and the node, this is an opaque blob. +The application is free to specify any encoding for input payloads. + +## Other options + +### -b, --binary + +Write the blob to standard output in binary format. + +### -h, --help + +Display help for command. + +[`addInput`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/inputs/IInputBox.sol#L32-L40 +[`Application`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/dapp/Application.sol +[`EvmAdvance`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Inputs.sol#L9-L28 +[`InputBox`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/inputs/InputBox.sol +[EIP-4399]: https://eips.ethereum.org/EIPS/eip-4399 +[EIP-155]: https://eips.ethereum.org/EIPS/eip-155 diff --git a/apps/site/pages/docs/cli/cmd/encode/notice.mdx b/apps/site/pages/docs/cli/cmd/encode/notice.mdx new file mode 100644 index 0000000..b5399de --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/encode/notice.mdx @@ -0,0 +1,38 @@ +# cmioc encode notice + +Encodes a notice according to the [`Notice`] function signature. + +:::code-group + +```bash [Command] +cmioc encode notice \ + --payload 0xdeadbeef +``` + +```txt [Output] +0xc258d6e500000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000 +``` + +::: + +## Required options + +### --payload \ + +`bytes` + +The actual data being notified by the application. +From the perspective of the smart contracts and the node, this is an opaque blob. +The application is free to specify any encoding for notice payloads. + +## Other options + +### -b, --binary + +Write the blob to standard output in binary format. + +### -h, --help + +Display help for command. + +[`Notice`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol#L10-L12 diff --git a/apps/site/pages/docs/cli/cmd/encode/voucher.mdx b/apps/site/pages/docs/cli/cmd/encode/voucher.mdx new file mode 100644 index 0000000..84cea66 --- /dev/null +++ b/apps/site/pages/docs/cli/cmd/encode/voucher.mdx @@ -0,0 +1,56 @@ +# cmioc encode voucher + +Encodes a voucher according to the [`Voucher`] function signature. +A voucher represents a [`CALL`] instruction to be performed in the context of the [`Application`] contract. + +:::code-group + +```bash [Command] +cmioc encode voucher \ + --destination 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \ + --value 1000000000000000000 \ + --payload 0xfafafa +``` + +```txt [Output] +0x237a816f000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb922660000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000003fafafa0000000000000000000000000000000000000000000000000000000000 +``` + +::: + +## Required options + +### --destination \ + +`address` + +The Ethereum address to be called. + +### --value \ + +`uint256` + +The amount of [Wei] to be passed along to the call. + +### --payload \ + +`bytes` + +The data to be passed along the call. +If the destination address is that of a Solidity smart contract, this data generally encodes a [Solidity function call]. + +## Other options + +### -b, --binary + +Write the blob to standard output in binary format. + +### -h, --help + +Display help for command. + +[Solidity function call]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding +[Wei]: https://ethereum.org/en/glossary/#wei +[`Application`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/dapp/Application.sol +[`CALL`]: https://www.evm.codes/#f1?fork=cancun +[`Voucher`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol#L14-L24 diff --git a/apps/site/pages/docs/cli/installation.mdx b/apps/site/pages/docs/cli/installation.mdx index 9f23b0a..baf2930 100644 --- a/apps/site/pages/docs/cli/installation.mdx +++ b/apps/site/pages/docs/cli/installation.mdx @@ -7,22 +7,22 @@ You can install the CLI globally on your machine with your favorite package mana :::code-group ```bash [npm] -npm install -g @guidanoli/cmioc +npm install -g @guidanoli/cmioc-cli ``` ```bash [pnpm] -pnpm add -g @guidanoli/cmioc +pnpm add -g @guidanoli/cmioc-cli ``` ```bash [yarn] -yarn global add @guidanoli/cmioc +yarn global add @guidanoli/cmioc-cli ``` ::: Once installed, you can execute the CLI directly, like so: -```sh +```bash [Terminal] cmioc [args...] ``` @@ -30,19 +30,19 @@ cmioc [args...] Alternatively, you can also pull the CLI image from the [GitHub Container Registry]. -```sh +```bash [Terminal] docker pull ghcr.io/guidanoli/cmioc ``` Once pulled, you can execute the CLI through Docker, like so: -```sh +```bash [Terminal] docker run ghcr.io/guidanoli/cmioc [args...] ``` If you want to pipe data into the CLI through `stdin`, don't forget the `-i` option. -```sh +```bash [Terminal] cat input.txt | docker run -i ghcr.io/guidanoli/cmioc [args...] ``` diff --git a/apps/site/vocs.config.ts b/apps/site/vocs.config.ts index dc01383..4bd5597 100644 --- a/apps/site/vocs.config.ts +++ b/apps/site/vocs.config.ts @@ -17,36 +17,31 @@ export default defineConfig({ link: "/docs/cli/installation", }, { - text: "Encoding", + text: "Commands", items: [ { - text: "Inputs", - link: "/docs/cli/encoding/inputs", + text: "encode input", + link: "/docs/cli/cmd/encode/input", }, { - text: "Notices", - link: "/docs/cli/encoding/notices", + text: "encode notice", + link: "/docs/cli/cmd/encode/notice", }, { - text: "Vouchers", - link: "/docs/cli/encoding/vouchers", + text: "encode voucher", + link: "/docs/cli/cmd/encode/voucher", }, { - text: "DELEGATECALL Vouchers", - link: "/docs/cli/encoding/delegatecall-vouchers", + text: "encode delegatecallvoucher", + link: "/docs/cli/cmd/encode/delegatecallvoucher", }, - ], - }, - { - text: "Decoding", - items: [ { - text: "Inputs", - link: "/docs/cli/decoding/inputs", + text: "decode input", + link: "/docs/cli/cmd/decode/input", }, { - text: "Outputs", - link: "/docs/cli/decoding/outputs", + text: "decode output", + link: "/docs/cli/cmd/decode/output", }, ], }, @@ -60,36 +55,15 @@ export default defineConfig({ link: "/docs/ts/installation", }, { - text: "Encoding", - items: [ - { - text: "Inputs", - link: "/docs/ts/encoding/inputs", - }, - { - text: "Notices", - link: "/docs/ts/encoding/notices", - }, - { - text: "Vouchers", - link: "/docs/ts/encoding/vouchers", - }, - { - text: "DELEGATECALL Vouchers", - link: "/docs/ts/encoding/delegatecall-vouchers", - }, - ], - }, - { - text: "Decoding", + text: "Types", items: [ { - text: "Inputs", - link: "/docs/ts/decoding/inputs", + text: "Input", + link: "/docs/ts/types/input", }, { - text: "Outputs", - link: "/docs/ts/decoding/outputs", + text: "Output", + link: "/docs/ts/types/output", }, ], },