From 9c1d188c24cc3012151cbb9ebc27f49d3c0afd32 Mon Sep 17 00:00:00 2001 From: Guilherme Dantas Date: Sun, 14 Jul 2024 23:16:23 -0300 Subject: [PATCH] Document TypeScript library --- 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/vocs.config.ts | 61 ++++--- 7 files changed, 352 insertions(+), 23 deletions(-) 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 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/vocs.config.ts b/apps/site/vocs.config.ts index 4bd5597..5c49b29 100644 --- a/apps/site/vocs.config.ts +++ b/apps/site/vocs.config.ts @@ -9,6 +9,45 @@ export default defineConfig({ text: "Getting Started", link: "/docs/getting-started", }, + { + text: "TypeScript", + items: [ + { + text: "Installation", + link: "/docs/ts/installation", + }, + { + text: "API", + items: [ + { + text: "encodeInput", + link: "/docs/ts/api/encodeInput", + }, + { + text: "encodeOutput", + link: "/docs/ts/api/encodeOutput", + }, + { + text: "decodeInput", + link: "/docs/ts/api/decodeInput", + }, + { + text: "decodeOutput", + link: "/docs/ts/api/decodeOutput", + }, + ], + }, + { + text: "Glossary", + items: [ + { + text: "Types", + link: "/docs/ts/glossary/types", + }, + ], + }, + ], + }, { text: "CLI", items: [ @@ -47,28 +86,6 @@ export default defineConfig({ }, ], }, - { - text: "TypeScript", - items: [ - { - text: "Installation", - link: "/docs/ts/installation", - }, - { - text: "Types", - items: [ - { - text: "Input", - link: "/docs/ts/types/input", - }, - { - text: "Output", - link: "/docs/ts/types/output", - }, - ], - }, - ], - }, ], socials: [ {