From cf15c01bb952f60699e67b6b08e37a3a11d08b68 Mon Sep 17 00:00:00 2001 From: Guilherme Dantas Date: Tue, 16 Jul 2024 15:48:28 -0300 Subject: [PATCH] Populate docs (#28) * Add "cmioc" to logo * Document CLI * Document TypeScript library --- 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/pages/docs/ts/api/decodeInput.mdx | 31 ++++ apps/site/pages/docs/ts/api/decodeOutput.mdx | 31 ++++ apps/site/pages/docs/ts/api/encodeInput.mdx | 34 ++++ apps/site/pages/docs/ts/api/encodeOutput.mdx | 41 ++++ apps/site/pages/docs/ts/glossary/types.mdx | 175 ++++++++++++++++++ apps/site/pages/docs/ts/installation.mdx | 2 +- apps/site/pages/index.mdx | 4 +- ...d-down-arrows-black.svg => icon-black.svg} | 0 ...d-down-arrows-white.svg => icon-white.svg} | 0 apps/site/public/logo-black.svg | 53 ++++++ apps/site/public/logo-white.svg | 55 ++++++ apps/site/vocs.config.ts | 75 ++++---- 19 files changed, 935 insertions(+), 53 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 create mode 100644 apps/site/pages/docs/ts/api/decodeInput.mdx create mode 100644 apps/site/pages/docs/ts/api/decodeOutput.mdx create mode 100644 apps/site/pages/docs/ts/api/encodeInput.mdx create mode 100644 apps/site/pages/docs/ts/api/encodeOutput.mdx create mode 100644 apps/site/pages/docs/ts/glossary/types.mdx rename apps/site/public/{up-and-down-arrows-black.svg => icon-black.svg} (100%) rename apps/site/public/{up-and-down-arrows-white.svg => icon-white.svg} (100%) create mode 100644 apps/site/public/logo-black.svg create mode 100644 apps/site/public/logo-white.svg 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/pages/docs/ts/api/decodeInput.mdx b/apps/site/pages/docs/ts/api/decodeInput.mdx new file mode 100644 index 0000000..4a7e11e --- /dev/null +++ b/apps/site/pages/docs/ts/api/decodeInput.mdx @@ -0,0 +1,31 @@ +# decodeInput + +Decodes an input according to the [`EvmAdvance`] function signature. + +```ts twoslash +// @filename: blob.ts +export const blob = + "0x415bf363000000000000000000000000000000000000000000000000000000000000000100000000000000000000000070ac08179605af2d9e75782b8decdd3c22aa4d0c000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266000000000000000000000000000000000000000000000000000000000000002a00000000000000000000000000000000000000000000000000000000000111705a41539c3688747a1a8c7811b98b0427331ff73aab018eb5c9921993d617f314000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000"; +// @filename: a.ts +// ---cut--- +import { blob } from "./blob"; +import { decodeInput } from "@guidanoli/cmioc"; + +const input = decodeInput(blob); // [!code focus] +``` + +## Returns + +[`Input`] + +The decoded input. + +## Parameters + +[`Hex`] + +The encoded input. + +[`Input`]: /docs/ts/glossary/types#input +[`Hex`]: /docs/ts/glossary/types#hex +[`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/ts/api/decodeOutput.mdx b/apps/site/pages/docs/ts/api/decodeOutput.mdx new file mode 100644 index 0000000..862bb83 --- /dev/null +++ b/apps/site/pages/docs/ts/api/decodeOutput.mdx @@ -0,0 +1,31 @@ +# decodeOutput + +Decodes an output according to the [`Outputs`] function signature. + +```ts twoslash +// @filename: blob.ts +export const blob = + "0xc258d6e500000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000"; +// @filename: a.ts +// ---cut--- +import { blob } from "./blob"; +import { decodeOutput } from "@guidanoli/cmioc"; + +const output = decodeOutput(blob); // [!code focus] +``` + +## Returns + +[`Output`] + +The decoded output. + +## Parameters + +[`Hex`] + +The encoded output. + +[`Hex`]: /docs/ts/glossary/types#hex +[`Output`]: /docs/ts/glossary/types#output +[`Outputs`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol diff --git a/apps/site/pages/docs/ts/api/encodeInput.mdx b/apps/site/pages/docs/ts/api/encodeInput.mdx new file mode 100644 index 0000000..8f3b61f --- /dev/null +++ b/apps/site/pages/docs/ts/api/encodeInput.mdx @@ -0,0 +1,34 @@ +# encodeInput + +Encodes an input according to the [`EvmAdvance`] function signature. + +```ts twoslash +import { encodeInput } from "@guidanoli/cmioc"; + +const blob = encodeInput({ + chainId: 1n, + appContract: "0x70ac08179605AF2D9e75782b8DEcDD3c22aA4D0C", + msgSender: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + blockNumber: 42n, + blockTimestamp: 70000n, + prevRandao: 123456789n, + index: 10n, + payload: "0xdeadbeef", +}); +``` + +## Returns + +[`Hex`] + +The encoded input. + +## Parameters + +[`Input`] + +The input to be encoded. + +[`Input`]: /docs/ts/glossary/types#input +[`Hex`]: /docs/ts/glossary/types#hex +[`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/ts/api/encodeOutput.mdx b/apps/site/pages/docs/ts/api/encodeOutput.mdx new file mode 100644 index 0000000..b2886a5 --- /dev/null +++ b/apps/site/pages/docs/ts/api/encodeOutput.mdx @@ -0,0 +1,41 @@ +# encodeOutput + +Encodes an output according to the [`Outputs`] interface. + +```ts twoslash +import { encodeOutput } from "@guidanoli/cmioc"; + +const noticeBlob = encodeOutput({ + type: "notice", + payload: "0xdeadbeef", +}); + +const voucherBlob = encodeOutput({ + type: "voucher", + destination: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + value: 1000000000000000000n, + payload: "0xdeadbeef", +}); + +const delegateCallVoucherBlob = encodeOutput({ + type: "delegatecallvoucher", + destination: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + payload: "0xdeadbeef", +}); +``` + +## Returns + +[`Hex`] + +The encoded output. + +## Parameters + +[`Output`] + +The output to be encoded. + +[`Hex`]: /docs/ts/glossary/types#hex +[`Output`]: /docs/ts/glossary/types#output +[`Outputs`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Outputs.sol diff --git a/apps/site/pages/docs/ts/glossary/types.mdx b/apps/site/pages/docs/ts/glossary/types.mdx new file mode 100644 index 0000000..d7b1df9 --- /dev/null +++ b/apps/site/pages/docs/ts/glossary/types.mdx @@ -0,0 +1,175 @@ +# Types + +## Address + +An Ethereum account address. + +Imported from [viem](https://viem.sh/docs/glossary/types#address). + +## DelegateCallVoucher + +A single-use permission to execute a [`DELEGATECALL`] instruction from the context of the [`Application`] contract. + +### type + +- **Value:** `"delegatecallvoucher"{:ts}` + +### destination + +- **Type:** [`Address`] + +The Ethereum address to be called, which is typically that of a smart contract. + +### payload + +- **Type**: [`Hex`] + +The data to be passed along the call, which typically encodes a [Solidity function call]. + +## Hex + +A "0x"-prefixed string. + +Imported from [viem](https://viem.sh/docs/glossary/types#hex). + +## Input + +An input added through the [`InputBox`] contract. + +### chainId + +- **Type:** `bigint` + +The [EIP-155] ID of the chain to which the [`InputBox`] contract was deployed. + +### appContract + +- **Type:** [`Address`] + +The address of the [`Application`] contract to which the input is destined. + +### msgSender + +- **Type:** [`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. + +### blockNumber + +- **Type:** `bigint` + +The number of the block in which the input was added. + +### blockTimestamp + +- **Type:** `bigint` + +The timestamp of the block in which the input was added. + +### prevRandao + +- **Type:** `bigint` + +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 + +- **Type:** `bigint` + +The zero-based index of the input in the input box of the application. + +### payload + +- **Type**: [`Hex`] + +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. + +## Notice + +A piece of verifiable information. + +### type + +- **Value:** `"notice"{:ts}` + +### payload + +- **Type**: [`Hex`] + +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. + +## Output + +A union type of [`Notice`], [`Voucher`] and [`DelegateCallVoucher`]. + +You can them apart through the `type` property. + +```ts twoslash +import { Output } from "@guidanoli/cmioc"; + +const handleOutput = (output: Output) => { + switch (output.type) { + case "notice": { + const { payload } = output; + break; + } + case "voucher": { + const { destination, value, payload } = output; + break; + } + case "delegatecallvoucher": { + const { destination, payload } = output; + break; + } + } +}; +``` + +## Voucher + +A single-use permission to execute a [`CALL`] instruction from the context of the [`Application`] contract. + +### type + +- **Value:** `"voucher"{:ts}` + +### destination + +- **Type:** [`Address`] + +The Ethereum address to be called. + +### value + +- **Type:** `bigint` + +The amount of [Wei] to be passed along to the call. + +### payload + +- **Type**: [`Hex`] + +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]. + +[EIP-155]: https://eips.ethereum.org/EIPS/eip-155 +[EIP-4399]: https://eips.ethereum.org/EIPS/eip-4399 +[Solidity function call]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding +[Wei]: https://ethereum.org/en/glossary/#wei +[`Address`]: #address +[`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 +[`DELEGATECALL`]: https://www.evm.codes/#f4?fork=cancun +[`DelegateCallVoucher`]: #delegatecallvoucher +[`EvmAdvance`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/common/Inputs.sol#L9-L28 +[`Hex`]: #hex +[`InputBox`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/inputs/InputBox.sol +[`Notice`]: #notice +[`Voucher`]: #voucher +[`addInput`]: https://github.com/cartesi/rollups-contracts/blob/v2.0.0-rc.4/contracts/inputs/IInputBox.sol#L32-L40 diff --git a/apps/site/pages/docs/ts/installation.mdx b/apps/site/pages/docs/ts/installation.mdx index f777819..eac3bea 100644 --- a/apps/site/pages/docs/ts/installation.mdx +++ b/apps/site/pages/docs/ts/installation.mdx @@ -23,5 +23,5 @@ yarn add @guidanoli/cmioc Once installed, you can import definitions from the package like so: ```ts twoslash -import { decodeOutputBlob } from "@guidanoli/cmioc"; +import { decodeOutput } from "@guidanoli/cmioc"; ``` diff --git a/apps/site/pages/index.mdx b/apps/site/pages/index.mdx index 1dd7bad..170537f 100644 --- a/apps/site/pages/index.mdx +++ b/apps/site/pages/index.mdx @@ -6,9 +6,7 @@ import { HomePage } from "vocs/components"; - - cmioc — Cartesi Machine Input/Output Codec - + Cartesi Machine Input/Output Codec Encode and decode, with ease, inputs and outputs for Cartesi Rollups SDK diff --git a/apps/site/public/up-and-down-arrows-black.svg b/apps/site/public/icon-black.svg similarity index 100% rename from apps/site/public/up-and-down-arrows-black.svg rename to apps/site/public/icon-black.svg diff --git a/apps/site/public/up-and-down-arrows-white.svg b/apps/site/public/icon-white.svg similarity index 100% rename from apps/site/public/up-and-down-arrows-white.svg rename to apps/site/public/icon-white.svg diff --git a/apps/site/public/logo-black.svg b/apps/site/public/logo-black.svg new file mode 100644 index 0000000..05000c1 --- /dev/null +++ b/apps/site/public/logo-black.svg @@ -0,0 +1,53 @@ + + + + + + + +cmioc diff --git a/apps/site/public/logo-white.svg b/apps/site/public/logo-white.svg new file mode 100644 index 0000000..1af8b0c --- /dev/null +++ b/apps/site/public/logo-white.svg @@ -0,0 +1,55 @@ + + + + + + + +cmioc diff --git a/apps/site/vocs.config.ts b/apps/site/vocs.config.ts index bca0906..5c49b29 100644 --- a/apps/site/vocs.config.ts +++ b/apps/site/vocs.config.ts @@ -10,86 +10,77 @@ export default defineConfig({ link: "/docs/getting-started", }, { - text: "CLI", + text: "TypeScript", items: [ { text: "Installation", - link: "/docs/cli/installation", + link: "/docs/ts/installation", }, { - text: "Encoding", + text: "API", items: [ { - text: "Inputs", - link: "/docs/cli/encoding/inputs", + text: "encodeInput", + link: "/docs/ts/api/encodeInput", }, { - text: "Notices", - link: "/docs/cli/encoding/notices", + text: "encodeOutput", + link: "/docs/ts/api/encodeOutput", }, { - text: "Vouchers", - link: "/docs/cli/encoding/vouchers", + text: "decodeInput", + link: "/docs/ts/api/decodeInput", }, { - text: "DELEGATECALL Vouchers", - link: "/docs/cli/encoding/delegatecall-vouchers", + text: "decodeOutput", + link: "/docs/ts/api/decodeOutput", }, ], }, { - text: "Decoding", + text: "Glossary", items: [ { - text: "Inputs", - link: "/docs/cli/decoding/inputs", - }, - { - text: "Outputs", - link: "/docs/cli/decoding/outputs", + text: "Types", + link: "/docs/ts/glossary/types", }, ], }, ], }, { - text: "TypeScript", + text: "CLI", items: [ { text: "Installation", - link: "/docs/ts/installation", + link: "/docs/cli/installation", }, { - text: "Encoding", + text: "Commands", items: [ { - text: "Inputs", - link: "/docs/ts/encoding/inputs", + text: "encode input", + link: "/docs/cli/cmd/encode/input", }, { - text: "Notices", - link: "/docs/ts/encoding/notices", + text: "encode notice", + link: "/docs/cli/cmd/encode/notice", }, { - text: "Vouchers", - link: "/docs/ts/encoding/vouchers", + text: "encode voucher", + link: "/docs/cli/cmd/encode/voucher", }, { - text: "DELEGATECALL Vouchers", - link: "/docs/ts/encoding/delegatecall-vouchers", + text: "encode delegatecallvoucher", + link: "/docs/cli/cmd/encode/delegatecallvoucher", }, - ], - }, - { - text: "Decoding", - items: [ { - text: "Inputs", - link: "/docs/ts/decoding/inputs", + text: "decode input", + link: "/docs/cli/cmd/decode/input", }, { - text: "Outputs", - link: "/docs/ts/decoding/outputs", + text: "decode output", + link: "/docs/cli/cmd/decode/output", }, ], }, @@ -120,11 +111,11 @@ export default defineConfig({ text: "Edit on GitHub", }, iconUrl: { - dark: "/up-and-down-arrows-white.svg", - light: "/up-and-down-arrows-black.svg", + dark: "/icon-white.svg", + light: "/icon-black.svg", }, logoUrl: { - dark: "/up-and-down-arrows-white.svg", - light: "/up-and-down-arrows-black.svg", + dark: "/logo-white.svg", + light: "/logo-black.svg", }, });