Document TypeScript library

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

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

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

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

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

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";
 ```

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: [
         {