From d1ede9e373eadb89044ca734ddd5c9fa47e36dd0 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Fri, 7 Jun 2024 15:50:04 +0800 Subject: [PATCH 01/26] Update README.md --- contracts/ckb-bitcoin-spv-type-lock/README.md | 160 +++++++----------- 1 file changed, 63 insertions(+), 97 deletions(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index abe43c5..8f22ef3 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -1,26 +1,21 @@ # CKB Bitcoin SPV Type Lock -A type script for Bitcoin SPV clients which synchronize [Bitcoin] state into [CKB]. +A type script designed for Bitcoin SPV clients synchronizes the [Bitcoin] blockchain state into the Nervos [CKB] network. ## Brief Introduction -A [Bitcoin] SPV in [CKB] contains a set of cells, this type script is used -to manage them. - -The set is identified by the script [`args`]. The number of live cells with this -specific `args` script is fixed once created, and all cells in the set are -destroyed together. +A Bitcoin  SPV on CKB consists of cells that are managed by the CKB Bitcoin SPV Type Lock and identified by the script args. The number of live cells with the script args remains fixed once created, and these cells will be destroyed collectively as a group. ### Cells -There are 2 kinds of cells in a Bitcoin SPV instance: +A Bitcoin SPV instance contains two types of cells: **SPV info cell** and **SPV client cell**. -- Client Cell +- **SPV Client Cell** - This cell is used to store the Bitcoin state. + A cell is identified as an SPV client cell if its type script matches the SPV type script. - Each Bitcoin SPV instance should contain at least 3 client cells. + SPV client cells store the Bitcoin state. Each Bitcoin SPV instance includes a minimum of three SPV client cells. ```yaml Client Cell: @@ -35,12 +30,10 @@ There are 2 kinds of cells in a Bitcoin SPV instance: - target adjust info ``` -- Info Cell - - This cell is used to store the basic information of current Bitcoin SPV - instance. Such as the ID of the tip client cell. +- **SPV Info Cell** - Each Bitcoin SPV instance should contain only 1 info cell. + The SPV info cell stores the basic information of the current Bitcoin SPV instance, such as `tip_ client_cell_id`. Each Bitcoin SPV + instance contains only one SPV info cell. ```yaml Info Cell: @@ -54,26 +47,16 @@ There are 2 kinds of cells in a Bitcoin SPV instance: ### Operations -There are 4 kinds of operations: - -- Create +There are 4 kinds of operations in the Bitcoin SPV type script: - Create all cells for a Bitcoin SPV instance in one transaction. +- **Create** - The outputs of this transaction should contain 1 info cell and at least 1 client cell. + This operation initiates all necessary cells for a Bitcoin SPV instance in a single transaction. - In the follow part of this document, we denoted the number of client cells - as `n`. + The `outputs` include one SPV info cell and at least one SPV client cell. Cells should be consecutive, with the SPV info cell first, + followed by N SPV client cells ordered by their ID from smallest to largest. - In current implementation, it requires that cells must be continuous and - in specified order: - - - The client info cell should be at the first. - - - Immediately followed by `n` client cells, and these cells should be - ordered by their ID from smallest to largest. - - The structure of this kind of transaction is as follows: + Let's denote the number of SPV client cells as `n`. The structure of this transaction is as follows: ```yaml Cell Deps: @@ -95,10 +78,9 @@ There are 4 kinds of operations: - ... ... ``` -- Destroy +- **Destroy** - All cells that use the same instance of this type lock should be destroyed - together in one transaction. + Cells within a single Bitcoin SPV instance should be destroyed in one transaction.. The structure of this kind of transaction is as follows: @@ -123,22 +105,15 @@ There are 4 kinds of operations: - ... ... ``` -- Update - - After creation, the `n` client cells should have same data. - - The client cell who has the same ID as the `tip_client_id` in the info cell, - we consider that it has the latest data. +- **Update** - The client cell who has the next ID of the `tip_client_id` in the info cell, - we consider that it has the oldest data. These client cells form a ring, where - the next ID after `n-1` is `0`. + The SPV client cell which ID matches the `tip_client_id` of the SPV info cell contains the most recent data, the SPV client cell next + in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a loop + where after the last cell (`ID = n`), it wraps around back to the first cell (`ID = 0`). - Once we update the Bitcoin SPV instance, we put the new data into the client - cell which has the oldest data, and update the `tip_client_id` in the client - info cell to its ID. - - Do the above step in repetition. + Once the Bitcoin SPV instance is updated, the new data will be put into the client cell that currently has the oldest data. Also, + the `tip_client_id` in the SPV info cell will be replaced by the `ID` of the SPV client cell that just received the new data. This SPV + info cell now becomes the new "latest data" holder. The structure of this kind of transaction is as follows: @@ -160,18 +135,14 @@ There are 4 kinds of operations: - ... ... ``` -- Reorg - - When receives blocks from a new longer chain, and there has at least one - client cell whose tip block is the common ancestor block of both the old - chain and the new chain, then a chain reorganization will be required. +- **Reorg** - **If no common ancestor block was found, then the Bitcoin SPV instance - will be broken, and it requires re-deployment.** + When receiving blocks from a new, longer chain, if the last common ancestor of both the old and new chains is identified by the [tip] + of client cell, a reorg is triggered. This reorg starts from this last common ancestor and rearranges the client cells accordingly. - let's denote the client ID of the best common ancestor to be `t`. + **If no common ancestor block is identified, the Bitcoin SPV instance will fail and require re-deployment.** - The structure of this kind of transaction is as follows: + Let's denote the client ID of the best common ancestor as `t`. The structure of this transaction is as follows: ```yaml Cell Deps: @@ -203,65 +174,55 @@ index of the output SPV info cell, and the proof should be set in ### Usages -When you want to verify a transaction with Bitcoin SPV Client cell: +To verify a transaction using the Bitcoin SPV Client cell, follow these steps: -- Choose any client cell which contains the block that transaction in. +- Select an SPV client cell that contains the block where the transaction is; - Create a transaction proof, with the following data: - - The MMR proof of the header which contains this transaction. - - - The TxOut proof of that transaction. + - The MMR proof of the block header which contains this transaction; - - The index of that transaction. + - The TxOut proof of the transaction; - - The height of that header. + - The index of the transaction; -- Use [the API `SpvClient::verify_transaction(..)`](https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/verifier/src/types/extension/packed.rs#L275-L292) to verify the transaction. + - The height of the block header. - A simple example could be found in [this test](https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181). +- Use the SpvClient::verify_transaction(..) for the verification. For detailed guidance, please refer to the [API example]. ### Limits -- The lower limit of SPV client cells count is 3. - -- The upper limit of SPV client cells count is not set, but base on the data type, `u8`, - any number larger than `250` is not recommended. - -### Known Issues - -- `VM Internal Error: MemWriteOnExecutablePage` - - Don't set hash type[^1] to be `Data`. +- The minimum count of SPV client cells is 3; + +- While there is no fixed maximum count of SPV client cells; it is advisable not to exceed `250` given the **`u8`** data type. - `Data1` is introduced from [CKB RFC 0032], and `Data2` is introduced from [CKB RFC 0051]. +### Known Issues and Solutions -- Failed to reorg when there is only 1 stale SPV client. +- **Issue #2**: `VM Internal Error: MemWriteOnExecutablePage` - When only 1 SPV client is stale, in the normal case, the reorg transaction - contains 1 input SPV client cell and 1 output SPV client cell is enough. + **Solution**: Don't set hash type[^1] to be `Data`. - But, the structure of this transaction is totally the same as an update - transaction, this leads to ambiguity. + For the appropriate use of hash type, refer to the "Code Locating" section in [CKB RFC 0022]. `Data1` is + introduced in [CKB RFC 0032], and `Data2` is introduced in [CKB RFC 0051]. - So, we define a rule to resolve this case: +- **Issue #2**: Failed to reorg when there is only 1 stale SPV client. - - When there is only 1 SPV client is stale, the reorg transaction has to - rebuild 2 SPV client. + **Solution**: When only one SPV client cell is stale, a typical reorg transaction has the same structure as an update transaction, + consisting of one SPV client cell in the inputs and one SPV client cell in the outputs. This similarity can lead to ambiguity. - That means, the reorg transaction for 1 stale SPV client should contain 2 - output SPV client cells and 2 output SPV client cells. + To address this issue, the following rules have been set: - Since the reorg rarely happens in Bitcoin mainnet, the cost is acceptable. - -- Throw "arithmetic operation overflow" when update a Bitcoin SPV instance for - a Bitcoin dev chain. - - The bitcoin dev chain doesn't follow the rule of difficulty change. - - So, calculate the next target and partial chain work may lead to an - arithmetic operation overflow. + - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one separate SPV clients; + - Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client + cell in the `outputs` ; + - Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. +- **Issue #3**: Throw **"Arithmetic Operation Overflow"** when updating a Bitcoin SPV instance for a Bitcoin dev chain. + + **Solution**: As the Bitcoin dev chain does not adhere to Bitcoin difficulty adjustment, calculations for the next target and the + partial chain work could result in an arithmetic overflow. + + [^1]: [Section "Code Locating"] in "CKB RFC 0022: CKB Transaction Structure". [Bitcoin]: https://bitcoin.org/ @@ -270,6 +231,11 @@ When you want to verify a transaction with Bitcoin SPV Client cell: [`args`]: https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0019-data-structures/0019-data-structures.md#description-1 [the field `output_type` of `WitnessArgs`]: https://github.com/nervosnetwork/ckb/blob/v0.114.0/util/gen-types/schemas/blockchain.mol#L117 +[API example]:https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181 + +[tip]:https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0004-ckb-block-sync/0004-ckb-block-sync.md + +[CKB RFC 0022]:https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating [Section "Code Locating"]: https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating [CKB RFC 0032]: https://github.com/nervosnetwork/rfcs/blob/dff5235616e5c7aec706326494dce1c54163c4be/rfcs/0032-ckb-vm-version-selection/0032-ckb-vm-version-selection.md#specification [CKB RFC 0051]: https://github.com/nervosnetwork/rfcs/blob/dff5235616e5c7aec706326494dce1c54163c4be/rfcs/0051-ckb2023/0051-ckb2023.md#ckb-vm-v2 From 95b17e1db4bff34401faa9298c6649e47c201e52 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:54:17 +0800 Subject: [PATCH 02/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 8f22ef3..e389cf4 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -233,7 +233,6 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: [API example]:https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181 -[tip]:https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0004-ckb-block-sync/0004-ckb-block-sync.md [CKB RFC 0022]:https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating [Section "Code Locating"]: https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating From 42d2f805412861fd3925e5666e002df8c8a1544d Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:54:23 +0800 Subject: [PATCH 03/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index e389cf4..57da833 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -231,7 +231,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: [`args`]: https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0019-data-structures/0019-data-structures.md#description-1 [the field `output_type` of `WitnessArgs`]: https://github.com/nervosnetwork/ckb/blob/v0.114.0/util/gen-types/schemas/blockchain.mol#L117 -[API example]:https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181 +[API example]: https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181 [CKB RFC 0022]:https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating From ea38dc7cdaa941d8b584c10361022f00358b2b5f Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:54:54 +0800 Subject: [PATCH 04/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 57da833..ce96422 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -1,7 +1,7 @@ # CKB Bitcoin SPV Type Lock -A type script designed for Bitcoin SPV clients synchronizes the [Bitcoin] blockchain state into the Nervos [CKB] network. +A type script designed for Bitcoin SPV clients ensures the valid synchronization of the [Bitcoin] blockchain state into the Nervos [CKB] network. ## Brief Introduction From 7fd61c297df78705f0d69737d171e66640ddd256 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:55:26 +0800 Subject: [PATCH 05/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index ce96422..0768050 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -109,7 +109,7 @@ There are 4 kinds of operations in the Bitcoin SPV type script: The SPV client cell which ID matches the `tip_client_id` of the SPV info cell contains the most recent data, the SPV client cell next in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a loop - where after the last cell (`ID = n`), it wraps around back to the first cell (`ID = 0`). + where after the last cell (`ID = n-1`), it wraps around back to the first cell (`ID = 0`). Once the Bitcoin SPV instance is updated, the new data will be put into the client cell that currently has the oldest data. Also, the `tip_client_id` in the SPV info cell will be replaced by the `ID` of the SPV client cell that just received the new data. This SPV From d46b741ce539428d7330ffcf4dd0887308769632 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:56:06 +0800 Subject: [PATCH 06/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 0768050..0d57a07 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -208,7 +208,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - **Issue #2**: Failed to reorg when there is only 1 stale SPV client. **Solution**: When only one SPV client cell is stale, a typical reorg transaction has the same structure as an update transaction, - consisting of one SPV client cell in the inputs and one SPV client cell in the outputs. This similarity can lead to ambiguity. + consisting of one SPV client cell in the inputs and one SPV client cell in the outputs. However, this similarity can lead to ambiguity. To address this issue, the following rules have been set: From d7f825d371f72b101aab9d5ca22ed8cbb87d4fc3 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:56:25 +0800 Subject: [PATCH 07/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 0d57a07..ec95bd2 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -108,7 +108,7 @@ There are 4 kinds of operations in the Bitcoin SPV type script: - **Update** The SPV client cell which ID matches the `tip_client_id` of the SPV info cell contains the most recent data, the SPV client cell next - in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a loop + in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a ring where after the last cell (`ID = n-1`), it wraps around back to the first cell (`ID = 0`). Once the Bitcoin SPV instance is updated, the new data will be put into the client cell that currently has the oldest data. Also, From 88f51112a2ec852464c2d97b240c86f1d566ceca Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:56:48 +0800 Subject: [PATCH 08/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index ec95bd2..2823cc2 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -111,7 +111,7 @@ There are 4 kinds of operations in the Bitcoin SPV type script: in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a ring where after the last cell (`ID = n-1`), it wraps around back to the first cell (`ID = 0`). - Once the Bitcoin SPV instance is updated, the new data will be put into the client cell that currently has the oldest data. Also, + When the Bitcoin SPV instance is updated, the new data will be put into the client cell that currently has the oldest data. Also, the `tip_client_id` in the SPV info cell will be replaced by the `ID` of the SPV client cell that just received the new data. This SPV info cell now becomes the new "latest data" holder. From fa72e4e477b44d7b7b56df3b364a9adc0b7bb2d5 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:57:03 +0800 Subject: [PATCH 09/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 2823cc2..0fc8633 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -212,7 +212,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: To address this issue, the following rules have been set: - - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one separate SPV clients; + - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one additional SPV client; - Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client cell in the `outputs` ; - Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. From c0adc3a780092b6b9ff4612474a5bd313f114a21 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:57:34 +0800 Subject: [PATCH 10/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 0fc8633..9a41267 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -202,8 +202,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: **Solution**: Don't set hash type[^1] to be `Data`. - For the appropriate use of hash type, refer to the "Code Locating" section in [CKB RFC 0022]. `Data1` is - introduced in [CKB RFC 0032], and `Data2` is introduced in [CKB RFC 0051]. + `Data1` is introduced in [CKB RFC 0032], and `Data2` is introduced in [CKB RFC 0051]. - **Issue #2**: Failed to reorg when there is only 1 stale SPV client. From 726e3e5b9e639bfe04fc2c07c467f072929eb176 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:57:43 +0800 Subject: [PATCH 11/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 9a41267..1302587 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -212,7 +212,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: To address this issue, the following rules have been set: - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one additional SPV client; - - Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client + Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client cell in the `outputs` ; - Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. From bdf2b2ff82bb1c9132c7289741396f0310657e67 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:57:51 +0800 Subject: [PATCH 12/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 1302587..957fab8 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -214,7 +214,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one additional SPV client; Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client cell in the `outputs` ; - - Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. + Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. - **Issue #3**: Throw **"Arithmetic Operation Overflow"** when updating a Bitcoin SPV instance for a Bitcoin dev chain. From ff4c1112b379332fb89afa199ba0db5e68c14067 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:59:22 +0800 Subject: [PATCH 13/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 957fab8..304d881 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -137,8 +137,9 @@ There are 4 kinds of operations in the Bitcoin SPV type script: - **Reorg** - When receiving blocks from a new, longer chain, if the last common ancestor of both the old and new chains is identified by the [tip] - of client cell, a reorg is triggered. This reorg starts from this last common ancestor and rearranges the client cells accordingly. + When receiving blocks from a new, longer chain, if there is at least one client cell whose tip block is the + common ancestor block of both the old chain and the new chain, a reorg is triggered. The reorg will be based + on this common ancestor, and all client cells with a tip higher than it will be updated accordingly. **If no common ancestor block is identified, the Bitcoin SPV instance will fail and require re-deployment.** From ddd673db84ef827570bc29005c6e3170e01d1e41 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 09:59:51 +0800 Subject: [PATCH 14/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 304d881..17dfa56 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -189,7 +189,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - The height of the block header. -- Use the SpvClient::verify_transaction(..) for the verification. For detailed guidance, please refer to the [API example]. +- Use the [`SpvClient::verify_transaction(..)`](https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/verifier/src/types/extension/packed.rs#L275-L292) for the verification. For detailed guidance, please refer to the [API example]. ### Limits From 1cd23bf0c357bf1929e751a5fa0abd457c6dcbdd Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:00:11 +0800 Subject: [PATCH 15/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 17dfa56..0f0619e 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -234,7 +234,6 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: [API example]: https://github.com/ckb-cell/ckb-bitcoin-spv/blob/2464c8f/prover/src/tests/service.rs#L132-L181 -[CKB RFC 0022]:https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating [Section "Code Locating"]: https://github.com/nervosnetwork/rfcs/blob/v2020.01.15/rfcs/0022-transaction-structure/0022-transaction-structure.md#code-locating [CKB RFC 0032]: https://github.com/nervosnetwork/rfcs/blob/dff5235616e5c7aec706326494dce1c54163c4be/rfcs/0032-ckb-vm-version-selection/0032-ckb-vm-version-selection.md#specification [CKB RFC 0051]: https://github.com/nervosnetwork/rfcs/blob/dff5235616e5c7aec706326494dce1c54163c4be/rfcs/0051-ckb2023/0051-ckb2023.md#ckb-vm-v2 From 2bf0c027852198401d9b9acc2d3d75a71893bf45 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:00:27 +0800 Subject: [PATCH 16/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 0f0619e..5f14ece 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -199,7 +199,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: ### Known Issues and Solutions -- **Issue #2**: `VM Internal Error: MemWriteOnExecutablePage` +- **Issue #1**: `VM Internal Error: MemWriteOnExecutablePage` **Solution**: Don't set hash type[^1] to be `Data`. From 477eff08fa0eaa0912ba8682132051216eab3b65 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:00:59 +0800 Subject: [PATCH 17/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 5f14ece..d4d675c 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -207,7 +207,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - **Issue #2**: Failed to reorg when there is only 1 stale SPV client. - **Solution**: When only one SPV client cell is stale, a typical reorg transaction has the same structure as an update transaction, + When only one SPV client cell is stale, a typical reorg transaction has the same structure as an update transaction, consisting of one SPV client cell in the inputs and one SPV client cell in the outputs. However, this similarity can lead to ambiguity. To address this issue, the following rules have been set: From 4186a18d6c44cfe006b884f2c33f5a07178f466b Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:01:15 +0800 Subject: [PATCH 18/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index d4d675c..a2fb974 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -219,7 +219,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - **Issue #3**: Throw **"Arithmetic Operation Overflow"** when updating a Bitcoin SPV instance for a Bitcoin dev chain. - **Solution**: As the Bitcoin dev chain does not adhere to Bitcoin difficulty adjustment, calculations for the next target and the + As the Bitcoin dev chain does not adhere to Bitcoin difficulty adjustment, calculations for the next target and the partial chain work could result in an arithmetic overflow. From 840e7b547a446648b3bea0c1d2a4f3c8177f940f Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:01:26 +0800 Subject: [PATCH 19/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Chengxing Yuan --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index a2fb974..174a5fc 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -210,7 +210,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: When only one SPV client cell is stale, a typical reorg transaction has the same structure as an update transaction, consisting of one SPV client cell in the inputs and one SPV client cell in the outputs. However, this similarity can lead to ambiguity. - To address this issue, the following rules have been set: + **Solution**: To address this issue, the following rule has been set: - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one additional SPV client; Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client From a106d3f9444e62696388c9b0cfbdd7762eba7241 Mon Sep 17 00:00:00 2001 From: KK11 <79199535+KryStar11@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:03:51 +0800 Subject: [PATCH 20/26] Update README.md --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 174a5fc..b8373ef 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -107,6 +107,8 @@ There are 4 kinds of operations in the Bitcoin SPV type script: - **Update** + After creation, the `n` client cells should have same data. + The SPV client cell which ID matches the `tip_client_id` of the SPV info cell contains the most recent data, the SPV client cell next in the sequence after the `tip_client_id` of the info cell holds the oldest data. This sequence arrangement of cells forms a ring where after the last cell (`ID = n-1`), it wraps around back to the first cell (`ID = 0`). From 770049914b6818f51b53c11be434a43876b87c45 Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 13:15:06 +0800 Subject: [PATCH 21/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index b8373ef..9f13126 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -1,5 +1,5 @@ -# CKB Bitcoin SPV Type Lock +# CKB Bitcoin SPV Type Script A type script designed for Bitcoin SPV clients ensures the valid synchronization of the [Bitcoin] blockchain state into the Nervos [CKB] network. From b5a31f7b3b7580eb2a6463ed3107795143095c25 Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 13:49:03 +0800 Subject: [PATCH 22/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Flouse <1297478+Flouse@users.noreply.github.com> --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 9f13126..20037cc 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -5,7 +5,7 @@ A type script designed for Bitcoin SPV clients ensures the valid synchronization ## Brief Introduction -A Bitcoin  SPV on CKB consists of cells that are managed by the CKB Bitcoin SPV Type Lock and identified by the script args. The number of live cells with the script args remains fixed once created, and these cells will be destroyed collectively as a group. +A Bitcoin  SPV on CKB consists of cells that are managed by the CKB Bitcoin SPV Type Script and identified by the script args. The number of live cells with the script args remains fixed once created, and these cells will be destroyed collectively as a group. ### Cells From 86b2e59f51402af4e4537d846e570dcd73e6d789 Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 13:49:09 +0800 Subject: [PATCH 23/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Flouse <1297478+Flouse@users.noreply.github.com> --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 20037cc..28e0b4e 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -32,7 +32,7 @@ A Bitcoin SPV instance contains two types of cells: **SPV info cell** and **SPV - **SPV Info Cell** - The SPV info cell stores the basic information of the current Bitcoin SPV instance, such as `tip_ client_cell_id`. Each Bitcoin SPV + The SPV info cell stores the basic information of the current Bitcoin SPV instance, such as `tip_client_id`. Each Bitcoin SPV instance contains only one SPV info cell. ```yaml From a0cb1b45bbd31a8fe8cf410a4d61a5bda8a61a6d Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 14:06:32 +0800 Subject: [PATCH 24/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Flouse <1297478+Flouse@users.noreply.github.com> --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 28e0b4e..32ad59b 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -216,7 +216,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - In cases where only one SPV client has failed, the reorg transaction must involve the reconstruction of one additional SPV client; Specifically, the reorg transaction for one stale SPV client should include two SPV client cell in the `inputs` and two SPV client - cell in the `outputs` ; + cells in the `outputs` ; Considering that reorgs are a rare occurrence on the Bitcoin mainnet, the cost incurred by this approach is considered manageable. - **Issue #3**: Throw **"Arithmetic Operation Overflow"** when updating a Bitcoin SPV instance for a Bitcoin dev chain. From 8fd4da89c7bc059b194d67d5230011fc2b441821 Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 14:06:39 +0800 Subject: [PATCH 25/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Flouse <1297478+Flouse@users.noreply.github.com> --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 32ad59b..64c3014 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -53,7 +53,7 @@ There are 4 kinds of operations in the Bitcoin SPV type script: This operation initiates all necessary cells for a Bitcoin SPV instance in a single transaction. - The `outputs` include one SPV info cell and at least one SPV client cell. Cells should be consecutive, with the SPV info cell first, + The `outputs` include one SPV info cell and at least three SPV client cell. Cells should be consecutive, with the SPV info cell first, followed by N SPV client cells ordered by their ID from smallest to largest. Let's denote the number of SPV client cells as `n`. The structure of this transaction is as follows: From 724d043be3c87eee095fa16247df3ed550dcf65f Mon Sep 17 00:00:00 2001 From: Chengxing Yuan Date: Wed, 12 Jun 2024 14:06:54 +0800 Subject: [PATCH 26/26] Update contracts/ckb-bitcoin-spv-type-lock/README.md Co-authored-by: Flouse <1297478+Flouse@users.noreply.github.com> --- contracts/ckb-bitcoin-spv-type-lock/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/ckb-bitcoin-spv-type-lock/README.md b/contracts/ckb-bitcoin-spv-type-lock/README.md index 64c3014..6c304d7 100644 --- a/contracts/ckb-bitcoin-spv-type-lock/README.md +++ b/contracts/ckb-bitcoin-spv-type-lock/README.md @@ -197,7 +197,7 @@ To verify a transaction using the Bitcoin SPV Client cell, follow these steps: - The minimum count of SPV client cells is 3; -- While there is no fixed maximum count of SPV client cells; it is advisable not to exceed `250` given the **`u8`** data type. +- The maximum count of SPV client cells is advisable not to exceed `250` given the **`u8`** data type. ### Known Issues and Solutions