From fa294e473af8c9a63d607f3c4f7c4caeac147872 Mon Sep 17 00:00:00 2001 From: yfeng2824 <140578792+yfeng2824@users.noreply.github.com> Date: Thu, 16 May 2024 11:00:03 +0800 Subject: [PATCH] add files to tech explanation (#339) * add files to tech explanation * fmt * update links * rename to script-args --- website/docs/dapp/write-message.mdx | 2 +- .../docs/getting-started/how-ckb-works.mdx | 4 +- website/docs/getting-started/quick-start.mdx | 2 +- website/docs/script/ScriptHeaders.tsx | 4 +- website/docs/script/intro-to-script.mdx | 2 +- website/docs/tech-explanation/args.md | 10 +++++ website/docs/tech-explanation/capacity.md | 18 ++++++++ website/docs/tech-explanation/cell-model.md | 14 ------- website/docs/tech-explanation/cell.md | 42 +++++++++++++++++++ website/docs/tech-explanation/code-hash.md | 6 +++ website/docs/tech-explanation/hash-type.md | 9 ++++ website/docs/tech-explanation/script.md | 35 ++++++++++++++++ website/sidebars.js | 6 +++ website/src/css/customTheme.css | 5 +++ 14 files changed, 138 insertions(+), 21 deletions(-) create mode 100644 website/docs/tech-explanation/args.md create mode 100644 website/docs/tech-explanation/capacity.md create mode 100644 website/docs/tech-explanation/cell.md create mode 100644 website/docs/tech-explanation/code-hash.md create mode 100644 website/docs/tech-explanation/hash-type.md create mode 100644 website/docs/tech-explanation/script.md diff --git a/website/docs/dapp/write-message.mdx b/website/docs/dapp/write-message.mdx index 21a48d11f..a7cae7b9c 100644 --- a/website/docs/dapp/write-message.mdx +++ b/website/docs/dapp/write-message.mdx @@ -20,7 +20,7 @@ import SwitchToTestnet from "./_SwitchToTestnet.mdx"; ## Store & Retrieve Cell Data -In this tutorial, you'll learn how to tuck a nifty message - "**Hello CKB!**" - into a [Cell](/docs/tech-explanation/cell-model#cell) on the CKB blockchain. Imagine it as sending a message in a bottle, but the ocean is digital, and the bottle is a super secure, tamper-proof CKB Cell! +In this tutorial, you'll learn how to tuck a nifty message - "**Hello CKB!**" - into a [Cell](/docs/tech-explanation/cell) on the CKB blockchain. Imagine it as sending a message in a bottle, but the ocean is digital, and the bottle is a super secure, tamper-proof CKB Cell! As you have learned from the first tutorial [Transfer CKB](/docs/dapp/transfer-ckb), the Cell can store any type of data in the data field of Cell structure. Here we will put a text message encoding in hex string format and store it in the data field. Once your words are encoded and inscribed into the blockchain, we'll then get the hex string from the same Cell back and then decode them to the original text message. the method of encoding and decoding is totally up to your favorite, we use the `TextDecoder` for simplicity through the tutorial. diff --git a/website/docs/getting-started/how-ckb-works.mdx b/website/docs/getting-started/how-ckb-works.mdx index 20b6e5ff6..b2b116564 100644 --- a/website/docs/getting-started/how-ckb-works.mdx +++ b/website/docs/getting-started/how-ckb-works.mdx @@ -22,7 +22,7 @@ BTC works just like cash. To know how much money you have, you simply count the - **Monetary value display:** Each UTXO box records the monetary value on its surface much like the denomination on the cash. - **Divisibility of value:** The value of UTXO boxes can be small or large. Larger value boxes can be split into multiple smaller one, allowing for precise value transactions similar to making change in cash dealings. -Now you understand the 80% of CKB, the rest 20% difference is that CKB uses generalized UTXOs called [Cell](/docs/tech-explanation/cell-model). A Cell is the basic unit of CKB, just like UTXOs to BTC. +Now you understand the 80% of CKB, the rest 20% difference is that CKB uses generalized UTXOs called Cell. A Cell is the basic unit of CKB, just like UTXOs to BTC. But what exactly are generalized UTXOs? @@ -42,7 +42,7 @@ Cell boxes can store any data types, as long as there is enough space to fit the ### Advanced Coding Capabilities -Unlike the simple and limited code that UTXOs can carry, Cells can use complex, Turing-complete codes akin to the normal software runing on your computer. You can learn the difference of [limited scripts](https://en.bitcoin.it/wiki/Script) and [Turing-complete scripts](/docs/tech-explanation/glossary/#script) further. +Unlike the simple and limited code that UTXOs can carry, Cells can use complex, Turing-complete codes akin to the normal software runing on your computer. You can learn the difference of [limited scripts](https://en.bitcoin.it/wiki/Script) and [Turing-complete scripts](/docs/tech-explanation/script) further. ### Dual Lock System diff --git a/website/docs/getting-started/quick-start.mdx b/website/docs/getting-started/quick-start.mdx index 41bd90cbd..9e8ded489 100644 --- a/website/docs/getting-started/quick-start.mdx +++ b/website/docs/getting-started/quick-start.mdx @@ -13,7 +13,7 @@ We recommend using [offCKB](https://www.npmjs.com/package/@offckb/cli) to quickl ## Install OffCKB -OffCKB provides a one-line command to start a local blockchain (CKB Devnet) with pre-funded test accounts and built-in [Scripts](/docs/tech-explanation/glossary#script) like [Omnilock](https://github.com/cryptape/omnilock) and [Spore-contract](https://github.com/sporeprotocol/spore-contract). +OffCKB provides a one-line command to start a local blockchain (CKB Devnet) with pre-funded test accounts and built-in [Scripts](/docs/tech-explanation/script) like [Omnilock](https://github.com/cryptape/omnilock) and [Spore-contract](https://github.com/sporeprotocol/spore-contract). ```bash npm install -g @offckb/cli diff --git a/website/docs/script/ScriptHeaders.tsx b/website/docs/script/ScriptHeaders.tsx index 8677127cf..cb55c51f3 100644 --- a/website/docs/script/ScriptHeaders.tsx +++ b/website/docs/script/ScriptHeaders.tsx @@ -8,10 +8,10 @@ export const ScriptHeaders: ScriptHeadersType = { basic: { time: "5 - 7 min", topics: [ - { label: "Script", link: "/docs/tech-explanation/glossary#script" }, + { label: "Script", link: "/docs/tech-explanation/script" }, { label: "CKB-VM", - link: "/docs/tech-explanation/glossary#ckb-vm", + link: "/docs/tech-explanation/ckb-vm", }, { label: "Cell Model", link: "/docs/tech-explanation/cell-model" }, { diff --git a/website/docs/script/intro-to-script.mdx b/website/docs/script/intro-to-script.mdx index d71a85ade..74cafede7 100644 --- a/website/docs/script/intro-to-script.mdx +++ b/website/docs/script/intro-to-script.mdx @@ -5,7 +5,7 @@ title: "Intro to Script" # Intro to Script -A [Script](/docs/tech-explanation/glossary#script) in Nervos CKB is a binary executable that can be executed on-chain. It is Turing-complete and can perform arbitray logic to guard and protect your on-chain assets. You can think of it as smart contract. +A [Script](/docs/tech-explanation/script) in Nervos CKB is a binary executable that can be executed on-chain. It is Turing-complete and can perform arbitray logic to guard and protect your on-chain assets. You can think of it as smart contract. ## How a Script Work diff --git a/website/docs/tech-explanation/args.md b/website/docs/tech-explanation/args.md new file mode 100644 index 000000000..a6ae0fc06 --- /dev/null +++ b/website/docs/tech-explanation/args.md @@ -0,0 +1,10 @@ +--- +id: script-args +title: script_args +--- + +`script_args` refers to the arguments imported into the CKB-VM instance as input for the Scripts. In CKB, public key information is conventionally stored in `script_args`, while signature information is in `witnesses`, though it's not mandatory. + +:::note +When a Script is validated, CKB runs it in a RISC-V VM, and `script_args` must be loaded via special CKB syscalls. The UNIX standard `argc`/`argv` convention is NOT used in CKB. For more information on CKB-VM, please refer to [RFC003: CKB-VM](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0003-ckb-vm/0003-ckb-vm.md). +::: diff --git a/website/docs/tech-explanation/capacity.md b/website/docs/tech-explanation/capacity.md new file mode 100644 index 000000000..f72aca23e --- /dev/null +++ b/website/docs/tech-explanation/capacity.md @@ -0,0 +1,18 @@ +--- +id: capacity +title: Capacity +--- + +Capacity is the storage limit of a Cell in a transaction. Capacity refers to both the quantity of stored tokens and the maximum amount of data the Cell can hold. The capacity of a Cell determines its ability to store various fields, including data, lock, type, and its own capacity. + +Transactions must create an output Cell whose occupied capacity is less than the capacity of the referenced Cell. + +``` +Occupied (Cell) ≤ Cell's capacity +``` + +When a new Cell is generated via a transaction, one of the validation rules is `capacity_in_bytes >= len(capacity) + len(data) + len(type) + len(lock)`. This value also represents the balance of CKB tokens, similar to the [`nValue` field in Bitcoin's CTxOut](https://www.bitcoinabc.org/doc/dev/class_c_tx_out.html). For instance, if Alice owns 100 CKB, she can unlock a group of Cells with a total quantity of 100 bytes. + +:::note +For Lock Script, another arg is appended to the array of CellInput to form a complete list of input parameters. +::: diff --git a/website/docs/tech-explanation/cell-model.md b/website/docs/tech-explanation/cell-model.md index d36085c18..aa4a49cf0 100644 --- a/website/docs/tech-explanation/cell-model.md +++ b/website/docs/tech-explanation/cell-model.md @@ -7,20 +7,6 @@ title: Cell Model > This approach maintains Bitcoin's simplicity and consistency. > In CKB, all states are stored in Cells, computation is done off-chain, and nodes handle all verification. -## Cell - -A **Cell** represents the fundamental data storage unit in Nervos. It can encompass various data types, such as CKBytes, tokens, JavaScript code, or serialized data like JSON strings, offering extensive flexibility in data storage. - -Cell Data - -Each Cell contains a small program known as a Lock Script that determines the owner of the Cell. While typically assigning ownership to a single user, Lock Script can also handle complex operations, such as having multiple owners (multi-sig) or conditional usage within specific timeframes. - -A Cell may include a **Type Script** to execute specific rules governing its usage. This empowers developers to customize smart contracts across diverse use-cases, such as issuing Non-Fungible Tokens, limiting the supply of fungible tokens, and implementing custom functionalities to suit unique requirements. - -The collection of Cells constitutes the **state** of CKB. A state verified and held by CKB is any data considered valuable and universally recognized. - -CKB State - ## Cell Model Inspired by Bitcoin's UTXO model, Cell Model defines the behavior of individual Cells within Nervos, as well as the process for updating their contained data. diff --git a/website/docs/tech-explanation/cell.md b/website/docs/tech-explanation/cell.md new file mode 100644 index 000000000..62d62988d --- /dev/null +++ b/website/docs/tech-explanation/cell.md @@ -0,0 +1,42 @@ +--- +id: cell +title: Cell +--- + +# Cell + +## Structure + +A Cell is the smallest and fundamental unit in Nervos CKB, used for storing states. + +```bash +Cell: { + capacity: HexString; + lock: Script; + type: Script; + data: HexString; +} +``` + +## Fields & Description{#fields-and-description} + +| Name | Type | Description | +| ---------- | ------------------------------------------------- | -------------------------------------------------------------- | +| `capacity` | Uint64 | Size of the Cell in shannon. 1 CKB = 100,000,000 shannons.  | +| `lock` | [Script](/docs/tech-explanation/script#structure) | See [Lock Script](/docs/tech-explanation/glossary#lock-script) | +| `type` | [Script](/docs/tech-explanation/script#structure) | See [Type Script](/docs/tech-explanation/glossary#type-script) | +| `data` | Bytes | Used for storing states. | + +## Example + +```json +{ + "capacity": "0x19995d0ccf", + "lock": { + "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", + "args": "0x0a486fb8f6fe60f76f001d6372da41be91172259", + "hash_type": "type" + }, + "type": null +} +``` diff --git a/website/docs/tech-explanation/code-hash.md b/website/docs/tech-explanation/code-hash.md new file mode 100644 index 000000000..2058bcfc2 --- /dev/null +++ b/website/docs/tech-explanation/code-hash.md @@ -0,0 +1,6 @@ +--- +id: code-hash +title: code_hash +--- + +`code_hash` represents the hash of the ELF-formatted RISC-V binary that contains a CKB Script. For efficiency, the Script itself is stored in a dep Cell attached to the current transaction. Depending on the `hash_type` value, the `code_hash` should either match the hash of the Cell data, or that of the Type Script in the dep Cell. During transaction verification, the actual binary is loaded into a CKB-VM instance when specified. diff --git a/website/docs/tech-explanation/hash-type.md b/website/docs/tech-explanation/hash-type.md new file mode 100644 index 000000000..451018e91 --- /dev/null +++ b/website/docs/tech-explanation/hash-type.md @@ -0,0 +1,9 @@ +--- +id: hash-type +title: hash_type +--- + +`hash_type` defines the interpretation of the `code_hash` when looking for matching dep Cells. + +- If it is 0, i.e., data, `code_hash` should match the blake2b hash of data in a dep Cell; +- if it is 1, i.e., type, `code_hash` should match the Type Script hash of a dep Cell. diff --git a/website/docs/tech-explanation/script.md b/website/docs/tech-explanation/script.md new file mode 100644 index 000000000..b9ba3a0e5 --- /dev/null +++ b/website/docs/tech-explanation/script.md @@ -0,0 +1,35 @@ +--- +id: script +title: Script +--- + +# Script + +## Structure + +In addition to the rules defined by the CKB protocol, verification based on the Scripts in the input and output Cells of the transaction is also required. + +```bash +Script: { + code_hash: HexString + args: HexString + hash_type: Uint8, there are 4 allowed values: {0: "data", 1: "type", 2: "data1", 3: "data2"} +} +``` + +## Fields & Description{#fields-and-description} + +| Name | Type | Description | +| ----------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `code_hash` | H256 | Hash of the ELF formatted RISC-V binary that contains a CKB Script. For more, see [`code_hash`](/docs/tech-explanation/code-hash) | +| `hash_type` | Uint8, one of the 4 values: \{0: "data", 1: "type", 2: "data1", 3: "data2"\} | Interpretation of the code hash when looking for matching dep cells. For more, see [`hash_type`](/docs/tech-explanation/hash-type) | +| `args` | H256 | Arguments as the Script input. For more, see [`script_args`](/docs/tech-explanation/script-args) | + +## Script vs. Code + +We differentiate the terms Script and Code as follows: + +- Script is a data structure referencing to runnable on-chain code. +- Code refers to the RISC-V binary, runnable in CKB-VM and can be referenced to by the Script structure. +- A code Cell is a Cell containing RISC-V binary code. +- Script does not directly include code; it simply stores a pointer to reference the code. diff --git a/website/sidebars.js b/website/sidebars.js index 157009915..d8ee6d99e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -78,7 +78,13 @@ export default { collapsible: false, items: [ "tech-explanation/nervos-blockchain", + "tech-explanation/cell", "tech-explanation/cell-model", + "tech-explanation/capacity", + "tech-explanation/script", + "tech-explanation/code-hash", + "tech-explanation/hash-type", + "tech-explanation/script-args", "tech-explanation/ckb-vm", "tech-explanation/consensus", "tech-explanation/economics", diff --git a/website/src/css/customTheme.css b/website/src/css/customTheme.css index 48a057f1c..9c7743cf8 100644 --- a/website/src/css/customTheme.css +++ b/website/src/css/customTheme.css @@ -299,6 +299,11 @@ font-size: 0.875rem; } +/* Table */ +table tr:nth-child(2n) { + background-color: var(--ifm-table-background); +} + /* Containers */ .container { padding-bottom: 7.5rem !important;