feat: merge doc v2 version into production

.github/workflows/deploy.yaml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
-          node-version: 16.x
+          node-version: 18.x
           cache: yarn
           cache-dependency-path: website/yarn.lock
       - name: Build website

.github/workflows/test-deploy.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
-          node-version: 16.x
+          node-version: 18.x
           cache: yarn
           cache-dependency-path: website/yarn.lock
       - name: Test build

.gitignore

@@ -5,6 +5,8 @@ node_modules
 lib/core/metadata.js
 lib/core/MetadataBlog.js
 
+examples/**/config.json
+
 website/translated_docs
 website/build/
 website/node_modules

examples/README.md

@@ -0,0 +1,25 @@
+# Tutorial Dapp Templates
+
+The Dapp templates often involve interaction with some most useful smart contracts on CKB like xUDT/Spore/Omnilock. Not only can these templates run on CKB Testnet, but also can be initialized as development projects targeting local Blockchain with the help of our CLI tool [offckb](https://github.com/RetricSu/offckb). And the best thing is they come with full detailed tutorial documents!
+
+## Add Dapp templates
+
+Assuming you are trying to add a new template named `my-awesome-template`:
+
+1. add your typescript project to the docs site's example folder: `https://github.com/nervosnetwork/docs.nervos.org/tree/develop-v2/examples/my-awesome-template`
+2. copy `templates/ckb.ts` and `templates/config.json` from `offckb` Github repo into your project
+   - `cp offckb/templates/ckb.ts docs.nervos.org/examples/my-awesome-template`
+   - `cp offckb/templates/config.json docs.nervos.org/examples/my-awesome-template`
+3. finish your `my-awesome-template` with `ckb.ts`, use `offckb` to start a devnet
+4. once your project is ready on the local Blockchain, rewrite the `ckb.ts` file to support CKB Testnet
+5. update the `options.json` file: `https://github.com/nervosnetwork/docs.nervos.org/tree/develop-v2/examples/options.json`
+6. done
+
+## Template Pattern
+
+All Dapp templates must meet the requirements:
+
+- Dapp must be able to run on the CKB Testnet by default
+- Dapp must be able to be initialized with `offckb` to run on devnet
+  - place a `ckb.ts` file in your root folder to manage CKB chain config like RPC URLs.
+  - use `ckb.ts` to export the `lumosConfig`

examples/create-dob/.gitignore

@@ -0,0 +1,2 @@
+.parcel-cache
+dist

examples/create-dob/README.md

@@ -0,0 +1,35 @@
+# View & Transfer Balance
+
+This is a simple Dapp example to show how to create and view digital objects on the CKB blockchain. Read the step-by-step [tutorial](https://docs.nervos.org/docs/getting-started/create-dob) to understand how it works.
+
+## How to run
+
+### On Testnet
+
+By default, this example can be cloned and directly run on the [CKB Testnet](https://pudge.explorer.nervos.org/):
+
+```sh
+git clone https://github.com/nervosnetwork/docs.nervos.org.git
+cd docs.nervos.org.git/examples/create-dob
+yarn && yarn start
+```
+
+### On Devnet
+
+It can also run on the local Blockchain, aka a CKB Devnet. To do this, you need to update the Lumos config defined in the `ckb.ts` file and related codes. Another way to automatically cover these steps is to install and use a CLI tool [`offckb`](https://github.com/RetricSu/offckb).
+
+```sh
+npm install -g offckb
+
+# start the devnet
+offckb node 
+
+# init project
+offckb init my-dob
+# select the templates for create-on-chain-digital-objects to get initialized
+# ...
+
+# start the app
+cd my-dob
+yarn && yarn start
+```

examples/create-dob/ckb.ts

@@ -0,0 +1,11 @@
+import { Indexer, RPC, config } from "@ckb-lumos/lumos";
+//import devConfig from './config.json';
+
+//export const lumosConfig: config.Config = devConfig as config.Config;
+export const lumosConfig = config.predefined.AGGRON4 as config.Config;
+
+//export const CKB_RPC_URL = 'http://localhost:8114';
+export const CKB_RPC_URL = "https://testnet.ckb.dev/rpc";
+
+export const rpc = new RPC(CKB_RPC_URL);
+export const indexer = new Indexer(CKB_RPC_URL);

examples/create-dob/helper.ts

@@ -0,0 +1,131 @@
+import {
+  defaultEmptyWitnessArgs,
+  updateWitnessArgs,
+  isScriptValueEquals,
+  getSporeConfig,
+} from "@spore-sdk/core";
+import {
+  hd,
+  helpers,
+  RPC,
+  Address,
+  Hash,
+  Script,
+  HexString,
+  commons,
+} from "@ckb-lumos/lumos";
+
+export interface Wallet {
+  lock: Script;
+  address: Address;
+  signMessage(message: HexString): Hash;
+  signTransaction(
+    txSkeleton: helpers.TransactionSkeletonType
+  ): helpers.TransactionSkeletonType;
+  signAndSendTransaction(
+    txSkeleton: helpers.TransactionSkeletonType
+  ): Promise<Hash>;
+}
+
+/**
+ * Create a CKB Default Lock (Secp256k1Blake160 Sign-all) Wallet by a private-key and a SporeConfig,
+ * providing lock/address, and functions to sign message/transaction and send the transaction on-chain.
+ */
+export function createDefaultLockWallet(privateKey: HexString): Wallet {
+  const config = getSporeConfig();
+
+  // Generate a lock script from the private key
+  const defaultLock = config.lumos.SCRIPTS.SECP256K1_BLAKE160!;
+  const lock: Script = {
+    codeHash: defaultLock.CODE_HASH,
+    hashType: defaultLock.HASH_TYPE,
+    args: hd.key.privateKeyToBlake160(privateKey),
+  };
+
+  // Generate address from the lock script
+  const address = helpers.encodeToAddress(lock, {
+    config: config.lumos,
+  });
+
+  // Sign for a message
+  function signMessage(message: HexString): Hash {
+    return hd.key.signRecoverable(message, privateKey);
+  }
+
+  // Sign prepared signing entries,
+  // and then fill signatures into Transaction.witnesses
+  function signTransaction(
+    txSkeleton: helpers.TransactionSkeletonType
+  ): helpers.TransactionSkeletonType {
+    const signingEntries = txSkeleton.get("signingEntries");
+    const signatures = new Map<HexString, Hash>();
+    const inputs = txSkeleton.get("inputs");
+
+    let witnesses = txSkeleton.get("witnesses");
+    for (let i = 0; i < signingEntries.size; i++) {
+      const entry = signingEntries.get(i)!;
+      if (entry.type === "witness_args_lock") {
+        // Skip if the input's lock does not match to the wallet's lock
+        const input = inputs.get(entry.index);
+        if (!input || !isScriptValueEquals(input.cellOutput.lock, lock)) {
+          continue;
+        }
+
+        // Sign message
+        if (!signatures.has(entry.message)) {
+          const sig = signMessage(entry.message);
+          signatures.set(entry.message, sig);
+        }
+
+        // Update signature to Transaction.witnesses
+        const signature = signatures.get(entry.message)!;
+        const witness = witnesses.get(entry.index, defaultEmptyWitnessArgs);
+        witnesses = witnesses.set(
+          entry.index,
+          updateWitnessArgs(witness, "lock", signature)
+        );
+      }
+    }
+
+    return txSkeleton.set("witnesses", witnesses);
+  }
+
+  // Sign the transaction and send it via RPC
+  async function signAndSendTransaction(
+    txSkeleton: helpers.TransactionSkeletonType
+  ): Promise<Hash> {
+    // 1. Sign transaction
+    txSkeleton = commons.common.prepareSigningEntries(txSkeleton, {
+      config: config.lumos,
+    });
+    txSkeleton = signTransaction(txSkeleton);
+
+    // 2. Convert TransactionSkeleton to Transaction
+    const tx = helpers.createTransactionFromSkeleton(txSkeleton);
+
+    console.log("tx", tx);
+
+    // 3. Send transaction
+    const rpc = new RPC(config.ckbNodeUrl);
+    return await rpc.sendTransaction(tx, "passthrough");
+  }
+
+  return {
+    lock,
+    address,
+    signMessage,
+    signTransaction,
+    signAndSendTransaction,
+  };
+}
+
+export function hexStringToUint8Array(hexString: string): Uint8Array {
+  const len = hexString.length;
+  const buffer = new Uint8Array(len / 2);
+
+  for (let i = 0; i < len; i += 2) {
+    buffer[i / 2] = parseInt(hexString.substr(i, 2), 16);
+  }
+
+  return buffer;
+}

examples/create-dob/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>View and Transfer Balance</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="index.tsx" type="module"></script>
+  </body>
+</html>