@offckb/cli 0.3.0-canary-34f0d45.0 → 0.3.0-canary-5f5a3b5.0

package/README.md

@@ -9,10 +9,10 @@
 **CKB local development network for your first try.**
 
 - One-line command to start a devnet
-- no docker required
-- pre-funded test accounts
-- built-in scripts like [Omnilock](https://github.com/cryptape/omnilock) and [Spore-contract](https://github.com/sporeprotocol/spore-contract)
-- multiple minimal dApp templates to learn and get your hands dirty
+- No docker required
+- Pre-funded test accounts
+- Built-in scripts like [Omnilock](https://github.com/cryptape/omnilock) and [Spore-contract](https://github.com/sporeprotocol/spore-contract)
+- Multiple minimal dApp templates to learn and get your hands dirty
 
 Start building on CKB blockchain, right now, right away!
 
@@ -23,8 +23,14 @@ Start building on CKB blockchain, right now, right away!
 - [Install](#install)
 - [Usage](#usage)
 - [Get started](#get-started)
+  - [Running CKB](#running-ckb)
+  - [List scripts info](#list-scripts-info)
   - [Create a full-stack Project](#create-a-full-stack-project)
   - [Create a script-only Project](#create-a-script-only-project)
+  - [Build and Deploy a script](#build-and-deploy-a-script)
+  - [Start the frontend project](#start-the-frontend-project)
+  - [Debug a transaction](#debug-a-transaction)
+  - [Generate Moleculec bindings](#generate-moleculec-bindings)
 - [Config Setting](#config-setting)
   - [List All Settings](#list-all-settings)
   - [Set CKB version](#set-ckb-version)
@@ -61,8 +67,8 @@ Commands:
   clean                                             Clean the devnet data, need to stop running the chain first
   accounts                                          Print account list info
   list-hashes [CKB-Version]                         Use the CKB to list blockchain scripts hashes
-  inject-config                                     Add offckb.config.ts to your workspace
-  sync-config                                       Sync offckb.config.ts in your workspace
+  inject-config                                     Add offckb.config.ts to your frontend workspace
+  sync-scripts                                      Sync scripts json file in your frontend workspace
   deposit [options] [toAddress] [amountInShannon]   Deposit CKB tokens to address, only devnet and testnet
   transfer [options] [toAddress] [amountInShannon]  Transfer CKB tokens to address, only devnet and testnet
   balance [options] [toAddress]                     Check account balance, only devnet and testnet
@@ -79,6 +85,61 @@ Commands:
 
 ## Get started
 
+### Running CKB
+
+Start a local blockchain with the default CKB version:
+
+```sh
+offckb node
+```
+
+Or specify a CKB version:
+
+```sh
+offckb node 0.117.0 
+```
+
+Or set the default CKB version:
+
+```sh
+offckb config set ckb-version 0.117.0
+offckb node
+```
+
+Once you start the devnet, there is a RPC server running at `http://localhost:8114`. There is also a RPC proxy server running at `http://localhost:9000` which will proxy all the requests to the RPC server. The meaning of using a proxy RPC server is to record request and automatically dump failed transactions so you can debug them easily later.
+
+The proxy server is optional, you can use the RPC server directly if you don't need a proxy:
+
+```sh
+offckb node --no-proxy
+```
+
+Or start the proxy server in a standalone terminal to better monitor the logs:
+
+```sh
+offckb proxy-rpc --ckb-rpc http://localhost:8114 --port 9000 --network devnet
+```
+
+### List scripts info
+
+List all the predefined scripts for the local blockchain:
+
+```sh
+offckb system-scripts
+```
+
+Or export the scripts info to a lumos JSON file:
+
+```sh
+offckb system-scripts --export-style lumos
+```
+
+Or print the scripts info in a CCC style:
+
+```sh
+offckb system-scripts --export-style ccc
+```
+
 ### Create a full-stack Project
 
 Create a new project from predefined boilerplates.
@@ -99,6 +160,86 @@ offckb create <your-project-name> --script
 
 Note: you need to have rust/cargo/cargo-generate/clang 16+ installed in your environment to use this command. offckb doesn't do anything really, it just call [ckb-script-template](https://github.com/cryptape/ckb-script-tempaltes) to do all the magic.
 
+### Build and Deploy a script
+
+The fullstack boilerplate project is a monorepo, which contains a script project and a frontend project.
+
+To build the script, in the root of the project, run: 
+
+```sh
+make build
+```
+
+To deploy the script, cd into the frontend folder and run:
+
+```sh
+cd frontend && offckb deploy --network <devnet/testnet>
+```
+
+Once the deployment is done, you can use the following command to check the deployed scripts:
+
+```sh
+offckb my-scripts --network <devnet/testnet>
+```
+
+Your deployed scripts will be also be listed in the `frontend/offckb/my-scripts` folder in your frontend project.
+
+### Start the frontend project
+
+To start the frontend project, cd into the frontend folder and run:
+
+```sh
+npm i & npm run dev
+```
+
+### Debug a transaction
+
+If you are using the proxy RPC server, all the failed transactions will be dumped and recorded so you can debug them later.
+
+Everytime you run a transaction, you can debug it with the transaction hash:
+
+```sh
+offckb debug <transaction-hash>
+```
+
+If you want to debug a single cell script in the transaction, you can use the following command:
+
+```sh
+offckb debug <transaction-hash> --single-script <single-cell-script-option>
+```
+
+The `single-cell-script-option` format is `<cell-type>[<cell-index>].<script-type>`, eg: `"input[0].lock"`
+
+- `cell-type` could be `input` or `output`, refers to the cell type
+- `cell-index` is the index of the cell in the transaction
+- `script-type` could be `lock` or `type`, refers to the script type
+
+Or you can replace the script with a binary file in your single cell script debug session:
+
+```sh
+offckb debug <transaction-hash> --single-script <single-cell-script-option> --bin <path/to/binary/file>
+```
+
+All the debug utils are borrowed from [ckb-debugger](https://github.com/nervosnetwork/ckb-debugger).
+
+### Generate Moleculec bindings
+
+[Moleculec](https://github.com/nervosnetwork/molecule) is the official Serialization/Deserialization system for CKB smart contracts.
+
+You will define your data structure in `.mol` file(schema), and generate the bindings for different programming languages to use in your development.
+
+```sh
+offckb mol --schema <path/to/mol/file> --output <path/to/output/file> --lang <lang>
+```
+
+The `lang` could be `ts`, `js`, `c`, `rs` and `go`.
+
+If you have multiple `.mol` files, you can use a folder as the input and specify an output folder:
+
+```sh
+offckb mol --schema <path/to/mol/folder> --output-folder <path/to/output/folder> --lang <lang>
+```
+
 ## Config Setting
 
 ### List All Settings

package/dist/cli.js

@@ -42,7 +42,7 @@ const encoding_1 = require("./util/encoding");
 const inject_config_1 = require("./cmd/inject-config");
 const deposit_1 = require("./cmd/deposit");
 const deploy_1 = require("./cmd/deploy");
-const sync_config_1 = require("./cmd/sync-config");
+const sync_scripts_1 = require("./cmd/sync-scripts");
 const transfer_1 = require("./cmd/transfer");
 const balance_1 = require("./cmd/balance");
 const create_1 = require("./cmd/create");
@@ -94,8 +94,8 @@ program
     .command('list-hashes [CKB-Version]')
     .description('Use the CKB to list blockchain scripts hashes')
     .action(list_hashes_1.listHashes);
-program.command('inject-config').description('Add offckb.config.ts to your workspace').action(inject_config_1.injectConfig);
-program.command('sync-config').description('Sync offckb.config.ts in your workspace').action(sync_config_1.syncConfig);
+program.command('inject-config').description('Add offckb.config.ts to your frontend workspace').action(inject_config_1.injectConfig);
+program.command('sync-scripts').description('Sync scripts json files in your frontend workspace').action(sync_scripts_1.syncScripts);
 program
     .command('deposit [toAddress] [amountInShannon]')
     .description('Deposit CKB tokens to address, only devnet and testnet')

package/dist/cmd/config.js

@@ -70,11 +70,12 @@ function Config(action, item, value) {
                     const settings = (0, setting_1.readSettings)();
                     try {
                         if ((0, validator_1.isValidVersion)(value)) {
-                            settings.bins.defaultCKBVersion = value;
+                            const version = extractVersion(value);
+                            settings.bins.defaultCKBVersion = version;
                             return (0, setting_1.writeSettings)(settings);
                         }
                         else {
-                            return console.error(`invalid version value, `, value);
+                            return console.error(`invalid version value, ${value}. Check available versions on https://github.com/nervosnetwork/ckb/tags`);
                         }
                     }
                     catch (error) {
@@ -100,3 +101,7 @@ function Config(action, item, value) {
     });
 }
 exports.Config = Config;
+function extractVersion(version) {
+    // If the version starts with 'v', remove it
+    return version.startsWith('v') ? version.slice(1) : version;
+}

package/dist/cmd/sync-scripts.d.ts

@@ -0,0 +1 @@
+export declare function syncScripts(): void;

package/dist/cmd/{sync-config.js → sync-scripts.js}

@@ -3,12 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.syncConfig = void 0;
+exports.syncScripts = void 0;
 const path_1 = __importDefault(require("path"));
 const validator_1 = require("../util/validator");
 const gen_1 = require("../scripts/gen");
 const offckb_config_1 = require("../template/offckb-config");
-function syncConfig() {
+function syncScripts() {
     (0, validator_1.validateExecDappEnvironment)();
     const userOffCKBConfigPath = path_1.default.resolve(process.cwd(), 'offckb.config.ts');
     const contractInfoFolder = offckb_config_1.OffCKBConfigFile.readContractInfoFolder(userOffCKBConfigPath);
@@ -21,4 +21,4 @@ function syncConfig() {
     (0, gen_1.genMyScriptsJsonFile)(myScriptsJsonFilePath);
     console.log('scripts json config updated.');
 }
-exports.syncConfig = syncConfig;
+exports.syncScripts = syncScripts;

package/dist/util/validator.js

@@ -60,8 +60,8 @@ function isValidVersion(version) {
     if (typeof version !== 'string') {
         return false;
     }
-    // Regular expression to match version strings like X.Y.Z
-    const versionRegex = /^\d+\.\d+\.\d+$/;
+    // Regular expression to match version strings like X.Y.Z or vX.Y.Z-rcN
+    const versionRegex = /^v?\d+\.\d+\.\d+(-rc\d+)?$/;
     // Test the version against the regex
     return versionRegex.test(version);
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@offckb/cli",
-  "version": "0.3.0-canary-34f0d45.0",
+  "version": "0.3.0-canary-5f5a3b5.0",
   "description": "ckb development network for your first try",
-  "author": "Retric Su <retric@cryptape.com>",
+  "author": "CKB EcoFund",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/retricsu/offckb.git"
+    "url": "git+https://github.com/ckb-ecofund/offckb.git"
   },
   "main": "dist/cli.js",
   "bin": {

package/dist/cmd/sync-config.d.ts

@@ -1 +0,0 @@
-export declare function syncConfig(): void;