CKB Light Client

https://github.com/nervosnetwork/ckb-light-client
Admin
A reference implementation of a CKB light client based on RFC 44 and RFC 45, enabling interaction...
Tokens:3,434
Snippets:20
Trust Score:9.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initializing CKB LightClient with Custom Configuration in JavaScript

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/light-client-js/README.md

This JavaScript snippet demonstrates how to initialize the `LightClient` and start it with a custom configuration. It imports necessary modules, creates a client instance, defines a multi-line configuration string for the light client network and store settings, and then starts the client, logging the tip header.

```javascript
import { LightClient, randomSecretKey } from "light-client-js";

const client = new LightClient();

const config = `
chain = "dev"

[store]
path = "data/store"

[network]
path = "data/network"

listen_addresses = ["/ip4/0.0.0.0/tcp/8110"]
### Specify the public and routable network addresses
# public_addresses = []

# Node connects to nodes listed here to discovery other peers when there's no local stored peers.
# When chain.spec is changed, this usually should also be changed to the bootnodes in the new chain.
bootnodes = [
    "/ip4/18.167.71.41/tcp/8115/ws/p2p/QmZ3g4ikFdUijFyQdDsuxnvMwgC4uMU4Ux8siwPGPxLnRC",
    # "/ip4/18.167.71.41/tcp/8115/wss/p2p/QmZ3g4ikFdUijFyQdDsuxnvMwgC4uMU4Ux8siwPGPxLnRC"
]


max_peers = 125
max_outbound_peers = 2
# 2 minutes
ping_interval_secs = 120
# 20 minutes
ping_timeout_secs = 1200
connect_outbound_interval_secs = 15
# If set to true, try to register upnp
upnp = false
# If set to true, network service will add discovered local address to peer store, it's helpful for private net development
discovery_local_address = false
# If set to true, random cleanup when there are too many inbound nodes
# Ensure that itself can continue to serve as a bootnode node
bootnode_mode = false

`

await client.start({ type: "TestNet", config }, randomSecretKey(), "info");
console.log(await client.getTipHeader())
```

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

### Initializing and Running CKB Full Node - Shell

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Initializes a CKB full node configuration for mainnet and starts the node. This is an optional step for the light client, as public bootnodes can be used instead.

```Shell
ckb init -c mainnet
ckb run
```

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

### Installing ckb-light-client-js Package

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/light-client-js/README.md

This snippet shows the command to install the `ckb-light-client-js` package using npm, which is the standard package manager for Node.js and web projects.

```bash
npm install ckb-light-client-js
```

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

### Installing ckb-light-client-js npm package

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/README.md

This command demonstrates how to install the `ckb-light-client-js` package, which is the JavaScript output of the ckb-light-client-wasm build, into another project using `npm`. This allows other JavaScript applications to easily integrate the CKB light client functionality.

```Shell
npm install ckb-light-client-js
```

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

### Setting Scripts (Replace All) - cURL

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Demonstrates how to use the `set_scripts` RPC method to replace all existing filtered scripts with a new one. This example sets a specific lock script to be filtered starting from block number 0.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"set_scripts", "params": [[{"script": {"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x50878ce52a68feb47237c29574d82288f58b5d21"}, "script_type": "lock", "block_number": "0x0"}]], "id": 1}'
```

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

### Running CKB Light Client - Shell

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Starts the CKB light client with specified logging levels and a configuration file. The `mainnet.toml` file should be configured with appropriate bootnode information, potentially including a local full node's peer ID.

```Shell
RUST_LOG=info,ckb_light_client=info ./ckb-light-client run --config-file ./mainnet.toml
```

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

### Getting Genesis Block from CKB Light Client (cURL)

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

This cURL command fetches the genesis block from the CKB Light Client. It invokes the `get_genesis_block` RPC method, which requires no parameters. The command returns a `BlockView` object representing the very first block in the blockchain.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_genesis_block", "params": [], "id": 1}'
```

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

### Getting Transaction by Hash from CKB Light Client (cURL)

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

This cURL command retrieves detailed information about a transaction, including its status and the containing block header, from the CKB Light Client. It uses the `get_transaction` RPC method, passing the transaction hash as a parameter. The response includes a `TransactionWithStatus` struct, detailing the transaction view, optional cycles used, and its current status (pending, committed, or unknown).

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_transaction", "params": ["0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3"], "id": 1}'
```

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

### Getting Filtered Scripts Status - cURL

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Queries the light client for the current status of all filtered scripts. The response will include details such as the script, its type (lock or type), and the block number from which it is being filtered.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"get_scripts", "params": [], "id": 1}'
```

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

### Getting Tip Header from CKB Light Client (cURL)

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

This cURL command retrieves the header of the block with the highest block number in the canonical chain from the CKB Light Client. It uses the `get_tip_header` RPC method with no parameters. The expected output is a `HeaderView` object representing the tip header.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_tip_header", "params": [], "id": 1}'
```

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

### Getting Block Header by Hash from CKB Light Client (cURL)

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

This cURL command retrieves a specific block header from the CKB Light Client using its hash. It calls the `get_header` RPC method, providing the block hash as a parameter. The command returns a `HeaderView` object containing the requested block header information.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_header", "params": ["0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40"], "id": 1}'
```

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

### Building CKB Light Client - Shell

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Clones the CKB light client repository, switches to the `develop` branch, and builds the client in release mode using Cargo. This compiles the light client binary for execution.

```Shell
git clone https://github.com/nervosnetwork/ckb-light-client.git
git checkout develop
cargo build --release
```

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

### Building ckb-light-client-wasm with wasm-pack and npm

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/README.md

This snippet details the steps to build the ckb-light-client-wasm project. It requires `cargo` for Rust toolchain management and `clang` for compilation. The build process uses `wasm-pack` to compile Rust to WebAssembly and `npm` to manage JavaScript dependencies and run the build script, producing a JavaScript file ready for bundling or direct browser use.

```Shell
cargo install wasm-pack
npm install
npm run build -ws
```

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

### Setting Scripts (Add Partial) - cURL

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Illustrates adding a new script to the existing set of filtered scripts using the `partial` command. The light client will begin filtering for this specific lock script from block number 0x64.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"set_scripts", "params": [[{"script": {"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0xd7c521f77cae39e7083d1cd664a893395fe25fdb"}, "script_type": "lock", "block_number": "0x64"}], "partial"], "id": 1}'
```

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

### Configuring Webpack Dev Server for Cross-Origin Headers in JavaScript

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/light-client-js/README.md

This JavaScript snippet shows how to configure Webpack's `devServer` to include `Cross-Origin-Embedder-Policy` and `Cross-Origin-Opener-Policy` headers. This is essential for local development environments to meet browser security requirements for features like SharedArrayBuffer, which `ckb-light-client-js` might utilize.

```javascript
const path = require('path');

module.exports = {
  //...
  devServer: {
    headers: {
      "Cross-Origin-Embedder-Policy": "require-corp",
      "Cross-Origin-Opener-Policy": "same-origin"
    }
  },
};
```

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

### Sending Transaction with CKB Light Client (cURL)

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

This cURL command demonstrates how to send a complex transaction to the CKB Light Client using the `send_transaction` RPC method. It includes detailed transaction parameters such as cell dependencies, inputs, outputs with capacities and lock scripts, output data, version, and witnesses. The command sends a JSON-RPC request to the local light client endpoint.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "send_transaction", "params": [{"cell_deps":[{"dep_type":"dep_group","out_point":{"index":"0x0","tx_hash":"0xf8de3bb47d055cdf460d93a2a6e1b05f7432f9777c8c474abf4eec1d4aee5d37"}}],"header_deps":[],"inputs":[{"previous_output":{"index":"0x7","tx_hash":"0x8f8c79eb6671709633fe6a46de93c0fedc9c1b8a6527a18d3983879542635c9f"},"since":"0x0"}],"outputs":[{"capacity":"0x470de4df820000","lock":{"args":"0xff5094c2c5f476fc38510018609a3fd921dd28ad","code_hash":"0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8","hash_type":"type"},"type":null},{"capacity":"0xb61134e5a35e800","lock":{"args":"0x64257f00b6b63e987609fa9be2d0c86d351020fb","code_hash":"0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8","hash_type":"type"},"type":null}],"outputs_data":["0x","0x"],"version":"0x0","witnesses":["0x5500000010000000550000005500000041000000af34b54bebf8c5971da6a880f2df5a186c3f8d0b5c9a1fe1a90c95b8a4fb89ef3bab1ccec13797dcb3fee80400f953227dd7741227e08032e3598e16ccdaa49c00"]}], "id": 1}'
```

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

### Configuring Vercel for Cross-Origin Headers

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/light-client-js/README.md

This JSON snippet illustrates how to configure Vercel deployments to include `Cross-Origin-Embedder-Policy` and `Cross-Origin-Opener-Policy` headers for all routes. This ensures that web applications hosted on Vercel, particularly those using `ckb-light-client-js`, comply with browser security requirements for features like SharedArrayBuffer.

```json
{
    "headers": [
        {
            "source": "/(.*)",
            "headers": [
                {
                    "key": "Cross-Origin-Embedder-Policy",
                    "value": "require-corp"
                },
                {
                    "key": "Cross-Origin-Opener-Policy",
                    "value": "same-origin"
                }
            ]
        }
    ]
}
```

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

### Configuring Nginx for Cross-Origin Headers

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/wasm/light-client-js/README.md

This Nginx server block configuration demonstrates how to add `Cross-Origin-Embedder-Policy` and `Cross-Origin-Opener-Policy` headers to responses. These headers are crucial for enabling SharedArrayBuffer and other security-sensitive features in browsers, especially for web applications like `ckb-light-client-js`.

```nginx
    server {
        listen 5600;
        server_name localhost;
        root /root/ckb-light-client;
        location / {
            index index.html;
            add_header Cross-Origin-Embedder-Policy "require-corp" always;
            add_header Cross-Origin-Opener-Policy "same-origin" always;
        }
    }
```

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

### Setting Scripts (Delete) - cURL

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Shows how to delete a specific script from the light client's filter list using the `delete` command. The `block_number` field is ignored for delete operations, as the script is identified by its `script` and `script_type`.

```Shell
curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"set_scripts", "params": [[{"script": {"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0xd7c521f77cae39e7083d1cd664a893395fe25fdb"}, "script_type": "lock", "block_number": "0x0"}], "delete"], "id": 1}'
```

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

### Retrieving CKB Full Node Peer ID - cURL

Source: https://github.com/nervosnetwork/ckb-light-client/blob/develop/README.md

Sends an RPC request to the local CKB full node to retrieve its `local_node_info`, which includes the peer ID. This ID is necessary if the light client is configured to connect to a specific full node.

```Shell
curl http://localhost:8114/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"local_node_info", "params": [], "id": 1}'
```
Tokens:
Raw