CKB Bitcoin SPV Contracts

https://github.com/utxostack/ckb-bitcoin-spv-contracts
Admin
CKB Bitcoin SPV Contracts implements Bitcoin SPV clients within CKB contracts, enabling verification...
Tokens:1,282
Snippets:8
Trust Score:7.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create Bitcoin SPV Instance Transaction Structure

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

This operation initializes an SPV instance, including one SPV info cell and multiple SPV client cells, all within a single transaction. Cells must be consecutive and ordered by ID.

```yaml
Cell Deps:
- Type Lock
- ... ...
Inputs:
- Enough Capacity Cells
Outputs:
- SPV Info (tip_client_id=0)
- SPV Client (id=0)
- SPV Client (id=1)
- SPV Client (id=2)
- ... ...
- SPV Client (id=n-2)
- SPV Client (id=n-1)
- ... ...
Witnesses:
- SPV Bootstrap
- ... ...
```

--------------------------------

### Verify Transaction using SpvClient API

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

This API reference describes how to verify a transaction using the `SpvClient::verify_transaction` method. It requires an SPV client cell, MMR proof, TxOut proof, transaction index, and block header height.

```APIDOC
SpvClient::verify_transaction(mmr_proof, tx_out_proof, tx_index, block_height)
  Description: Verifies a transaction using the Bitcoin SPV Client cell.
  Parameters:
    mmr_proof: The MMR proof of the block header which contains this transaction.
    tx_out_proof: The TxOut proof of the transaction.
    tx_index: The index of the transaction.
    block_height: The height of the block header.
  Returns: Verification result (type not specified, but implied boolean or status)
```

--------------------------------

### SPV Info Cell Structure Definition

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

Defines the structure of the SPV info cell, which stores basic information for the current Bitcoin SPV instance, such as the `tip_client_id`. Each Bitcoin SPV instance contains exactly one SPV info cell, identified by its type script matching the SPV type script.

```yaml
Info Cell:
  Type Script:
    code hash: "..."
    hash type: "type"
    args: "typeid + clients count + flags"
  Data: 
    - tip client cell id
```

--------------------------------

### CKB Lock Script Success Conditions for "Can Update Without Ownership"

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/can-update-without-ownership-lock/README.md

This section outlines the two conditions that must be met for the "Can Update Without Ownership" CKB lock script to execute successfully. These conditions ensure either a specific witness-based authentication or a capacity preservation mechanism, allowing updates by non-owners under specific circumstances.

```APIDOC
CKB Lock Script Success Conditions:
This script returns success if ANY of the following conditions are met:

1. Witness Hash Match:
   - Condition: The 'args' for this lock script must be the result of calling 'ckb_hash::blake2b_256' on its 'witness'.
   - Reference: ckb_hash::blake2b_256

2. Capacity Preservation (No Witness):
   - Condition: There is no witness provided for this lock script AND the total capacity of cells using this lock script in the transaction's outputs is not greater than the total capacity of cells using this lock script in the transaction's inputs.
   - Implication: Allows updates by non-owners as long as the total capacity of affected cells does not decrease.
```

--------------------------------

### SPV Client Cell Structure Definition

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

Defines the structure of an SPV client cell, which stores the Bitcoin state. It includes the type script parameters (code hash, hash type, and args) and the data fields such as ID, Bitcoin tip block hash, Bitcoin headers MMR root, and target adjustment information. A minimum of three SPV client cells are required per Bitcoin SPV instance.

```yaml
Client Cell:  
  Type Script:
    code hash: "..."
    hash type: "type"
    args: "typeid + clients count + flags"
  Data:
    - id
    - btc tip block hash
    - btc headers mmr root
    - target adjust info
```

--------------------------------

### Update Bitcoin SPV Instance Transaction Structure

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

This operation updates an SPV instance by replacing the oldest data with new data in a client cell and updating the `tip_client_id` in the SPV info cell. This forms a ring-like update mechanism.

```yaml
Cell Deps:
- Type Lock
- SPV Client (id=k)
- ... ...
Inputs:
- SPV Info (tip_client_id=k)
- SPV Client (id=k+1)
- ... ...
Outputs:
- SPV Info (tip_client_id=k+1)
- SPV Client (id=k+1)
- ... ...
Witnesses:
- SPV Update
- ... ...
```

--------------------------------

### Reorg Bitcoin SPV Instance Transaction Structure

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

This operation handles blockchain reorganizations by updating client cells based on a common ancestor block. If no common ancestor is found, the instance fails and requires re-deployment.

```yaml
Cell Deps:
- Type Lock
- SPV Client (id=t)
- ... ...
Inputs:
- SPV Info (tip_client_id=k)
- SPV Client (id=t+1)
- SPV Client (id=t+2)
- SPV Client (id=...)
- SPV Client (id=k)
- ... ...
Outputs:
- SPV Info (tip_client_id=t+1)
- SPV Client (id=t+1)
- SPV Client (id=t+2)
- SPV Client (id=...)
- SPV Client (id=k)
- ... ...
Witnesses:
- SPV Update
- ... ...
```

--------------------------------

### Destroy Bitcoin SPV Instance Transaction Structure

Source: https://github.com/utxostack/ckb-bitcoin-spv-contracts/blob/master/contracts/ckb-bitcoin-spv-type-lock/README.md

This operation destroys all cells associated with a Bitcoin SPV instance in a single transaction.

```yaml
Cell Deps:
- Type Lock
- ... ...
Inputs:
- SPV Info (tip_client_id=0)
- SPV Client (id=0)
- SPV Client (id=1)
- SPV Client (id=2)
- ... ...
- SPV Client (id=n-2)
- SPV Client (id=n-1)
- ... ...
Outputs:
- Unrelated Cell
- ... ...
Witnesses:
- Unrelated Witness
- ... ...
```
Tokens:
Raw