You might noticed that I call the code running on CKB as script, not smart contract. This is because smart contract is quite a confusing term to me, and I want to use a different word here to indicate CKB's unique programmability. A script in CKB's sense need not be just a script we see in scripting languages such as Ruby, JS, it actually refers to the RISC-V format binary you run on CKB VM.

This first post here, is dedicated to the brand new verification model introduced in CKB v0.14.0. It might sound boring but I promise you this is the last post without actual examples to play with :P

Note even though I believe CKB's programming model is quite stable now, development is still happening so there might be changes. I will try my best to make sure this post is updated but if anything confuses you, this post is describing CKB's Lina mainnet version now.

Below illustrates a real transaction on CKB:

There are a lot of things going on in this graph, and we will come back to this graph again in later posts. Today, we will just focus on 2 entities in the cell data structure: lock and type.

pub struct CellOutput {
    pub capacity: Capacity,
    pub lock: Script,
    #[serde(rename = "type")]
    pub type_: Option<Script>,
}

From the data structure we can see that lock and type shared the same structure, later we can show that they are also executed in the same environment, the differences between them are just in a few tiny bits:

• lock is required, while type is optional
• Mentally, they are used to capture different use cases.

We will first start with type script here.

Type Script

Note the name here is just a lucky accident, it is not related to the beloved programming language.

If you think about it, a transaction on CKB(or most UTXO-based blockchains) just transforms one set of cells(or UTXOs) to another set of cells. What's interesting, is the actual transformation here. That's where we start to design CKB's verification model: how can we build a model to better validate the cell transformations?

That's where a type script comes in play: a type script is used to validate certain rules in the cell transformation phase. Some examples here include:

• Validating UDT(user defined token) balances to ensure no new token is invalidly issued.
• Ensuring a unique name is assigned to a cell that might be mutated. Note this is a fun one, please expect a future article dedicated entirely to this topic.
• Implementing economic constructs. In fact NervosDAO is completely implemented as a type script with minimal support from the consensus layer.
• A bitcoin VM can be compiled to RISC-V binary, which can transform CKB into an alternative bitcoin implementation :)
• Keep in mind that in addition to data, cell can be used to store code as well, hence a type script can also be used to run tests on the code in cell to ensure certain behavior.

In a nutshell, type script can be used to capture any validation logic you need in the cell transformation. Combined with CKB's flexible virtual machine, I believe this will provide endless potentials.

Lock Script

Type script captures the cell transformation logic, but there's still one thing missing from the picture: how can I guard my own cell from someone else? In other words, how can I ensure my tokens stay mine in an ever-changing world?

This is why we designed the always required lock script. A cell can only be consumed when the lock script can be executed sucessfully. This is different from type script, which might be totally optional. A lock script is always there to guard the security of a cell.

Typically, you would expect that a lock script contains a signature verification phase, like all the other blockchains do, but there are also brand new use cases unlocked by CKB:

• The actual signature algorithm is totally determined by the lock script, and you are free to use any lock script. That means you are free to incorporate any signature algorithms that suit your need. In the official CKB distribution we are including secp256k1 algorithm as the default lock script. But you don't have to use this, if someone implements a lock script using schnorr signature, you are more than welcome to use that one.
• In addition to signature verification, a lock script can also include other rules to unlock the cell as well. For example, I can configure my lock script to pass if the transaction contains an output cell that uses my lock script, but has more capacity than my consumed cell. This way when someone sends me capacity, they can consume my existing cell and create a new cell for me. They don't have to create a new cell for me like bitcoin requires.

In my personal opinion, the best part of CKB, is that a lock script created by the community is treated exactly the same way as the official default one. No priviledge is granted to the official scripts. Unlike some other blockchains, CKB provides the freedom to develop CKB scripts back to the whole community.

Execution Model

Now let's see when lock and type scripts are executed.

Back to the Example​

Here's the transaction we see earlier again:

For this example, the execution flow is as follows:

1. Lock Script 1 is executed once.
2. Lock Script 2 is executed once.
3. Type Script 1 is executed once.
4. Type Script 2 is executed once.

In later posts we can see both lock and type scripts are executed in the same environment, and both have access to the whole transaction. If any of the script fails, the whole transaction fails. Only when all the scripts succeed, the transaction is considered validated.

There're couple of points worth mentioning:

• Even though there are 2 input cells with Lock Script 1, it is only executed once, it's up to the actual lock script to locate all the input cells with the same lock script and validate both signature.
• Only lock scripts in input cells are executed in this transaction, for example, Lock Script 3 is not executed here.
• Even though an input cell and an output cell both contain Type Script 1, it is only executed once.
• Type scripts in both input and output cells are executed, which include Type Script 1 and Type Script 2.
• Some cells do not have type scripts, in this case we just omit the execution.

Rules​

Now to summary the rules:

• Lock scripts in input cells are collected and deduped, each unique lock script is executed and only executed once.
• Type scripts in input and output cells(if existed) are collected together and deduped, each unique type script is executed and only executed once.
• If any script fails, the whole transaction validation fails.

What's Next

Now that cell model is covered, we will look at how to actual write a CKB VM script in the next post. The default secp256k1 lock script will be examined to show the life of a CKB VM script.

This post is written based on current CKB Lina mainnet version now.

A warning here: this will be a long post, since I want to fill in enough for the more interesting topic next week. So you don't have to finish it at once if you don't have enough time. I've tried to split it into individual sections, so you can try each one at a time.

Before we continue, let's distinguish between 2 terms: script, and script code.

In this post and hopefully the whole series, we will distinguish between script, and script code. Script code actually refers to the program you write and compile to use on CKB. Script, on the other hand, actually refers to the script data structure used in CKB, which is a little more than just the script code:

pub struct Script {
    pub code_hash: H256,
    pub hash_type: ScriptHashType,
    pub args: JsonBytes,
}

We can ignore hash_type for now, a future post will explain what it is and it's interesting usage. Later in this post, we will show that code_hash actually just identifies a script code, so for now we can just think of it as script code. What script also includes, is the args part, which distinguishes script from script code. args can be used here to provide additional arguments for a CKB script, for example, while people might all be using the same default lock script code, each of them might have their own pubkey hash, args is exact the place to hold pubkey hash. This way each user of CKB can have different lock script, while sharing the same lock script code.

Note that in most cases, script and script code can be used interchangably, but if you are confused at some places, it might be worthwhile to think of the difference between the 2.

A Minimal CKB Script Code

As you might have already heard, CKB is based on the open source RISC-V ISA. But what does that even mean? In my words, it means we are (sort of) embedding a real mini computer in CKB, instead of a virtual machine. The benefit of a real computer, is that you can write any logic you want in any language you want. The first few examples we show here will be written in C for simplicity(well I mean simplicity in the toolchain, not the language), but later we will switch to JavaScript based script code, and hopefully show more languages in the series. On CKB there's endless possibilities.

As we mentioned about, CKB VM is more like a real mini computer. CKB script code also looks like a normal Unix style executable program we run on a computer:

int main(int argc, char* argv[])
{
  return 0;
}

When compiled via a C compiler, this will become a script code that is runnable on CKB. In other words, CKB just take plain old Unix style executables(but in RISC-V architecture instead of the popular x86 architecture), and run it in a virtual machine environment. If the program returns with 0 as the return code, we consider the script succeeds, all non-zero return codes will be considered script faliures.

In the example above, we are showing a script code that always succeeds, since the return code will always be zero. Please don't use this as your lock script code, otherwise your token can be taken away by anyone.

But the example above won't be interesting, here we will start with an interesting idea: personally I dislike carrot. I do know that carrot is great from a nutritional point of view, but I still want to avoid it due to the taste. Now what if I want to set a rule, that none of my cells on CKB has data that begin with carrot? Let's write a script code to ensure this.

In order to ensure none of the cells can have carrot in cell data, we need a way to first read cell data in the script. CKB provides syscalls to help with this.

To ensure the security of CKB script, each script has to run in an isolated environment that is totally separated from the main computer you are running CKB. This way it won't be able to access data it doesn't need, such as your private keys or passwords. However, for a script to be useful, there must be certain data it want to access, such as the cell a script guards, or a transaction a script validates. CKB provides syscalls to ensure this, syscalls are defined in RISC-V standard, they provide a way to access certain resources provided by the environment. In a normal situation, the environment here means the operating system, but in the case of CKB VM, the environment refers to the actual CKB process. With syscalls, a CKB script can access the whole transaction containing itself, including inputs, outputs, witnesses, and deps.

The good news, is that we have encapsulated syscalls in an easy to use header file, you are very welcome to poke around this file to see how syscalls are implemented. The bottomline is you can just grab this header file and use the wrapped functions to make syscalls as you want.

Now with the syscalls at hand, we can start with our carrot-forbidden script:

#include <memory.h>
#include "ckb_syscalls.h"

int main(int argc, char* argv[]) {
  int ret;
  size_t index = 0;
  uint64_t len = 0; /* (1) */
  unsigned char buffer[6];

  while (1) {
    len = 6;
    memset(buffer, 0, 6);
    ret = ckb_load_cell_data(buffer, &len, 0, index, CKB_SOURCE_OUTPUT); /* (2) */
    if (ret == CKB_INDEX_OUT_OF_BOUND) {               /* (3) */
      break;
    }

    if (memcmp(buffer, "carrot", 6) == 0) {
      return -1;
    }

    index++;
  }

  return 0;
}

Several points worth explaining here:

1. We will use len field both as an input and output parameter, hence it is passed as a pointer here.
2. When making a syscall, we need to provide the following: a buffer to hold the data provided by the syscall; a len field denoting both the buffer length, and available data length returned by the syscall; an offset into the input data buffer, and several parameters denoting the exact field we are fetching in the transaction. For more details, please refer to our RFC.
3. For maximum flexibility, CKB uses the return value of the syscall to represent data fetching status: 0(or CKB_SUCCESS) means success, 1(or CKB_INDEX_OUT_OF_BOUND) means you have finished fetching all indices in a kind, 2(or CKB_ITEM_MISSING) means an entity is not present, such as fetching a type script from a cell that doesn't have one.

So to recap, this script would loop through all output cells in the transaction, load the first 6 bytes of each cell data and test if those bytes match carrot. If we found a match, the script would return -1, denoting an error status, if no match is found, the script exits with 0, meaning execution success.

To perform the loop, the script would keep an index variable, in each loop iteration, it would tries to make the syscall to fetch the cell denoted by current index value, if the syscall returns CKB_INDEX_OUT_OF_BOUND, it means the script has iterated through all the cells, hence it just exits the loop, otherwise, the loop would continue, the cell data is tested, then index variable is incremented for the next iteration.

This concludes your first useful CKB script code! In the next section, we will see how we can deploy it to CKB and run it.

Deploying a Script to CKB

First, we need to compile the carrot source code written above. Since GCC already has upstream RISC-V support, you can of course use the official GCC to build your script code. Or you can use the docker image we have prepared to save the trouble of compiling GCC:

$ ls
carrot.c  ckb_consts.h  ckb_syscalls.h
$ sudo docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
root@dc2c0c209dcd:/# cd /code
root@dc2c0c209dcd:/code# riscv64-unknown-elf-gcc -Os carrot.c -o carrot
root@dc2c0c209dcd:/code# exit
exit
$ ls
carrot*  carrot.c  ckb_consts.h  ckb_syscalls.h

And that's it, CKB can use the compiled executable from GCC directly as scripts on chain, there's no way for further processing. We can now deploy it on chain. Note that I will use CKB's Node.js SDK Lumos. Please refer to the official Docs for how to set it up. Across the serial posts, there are some common codes to set up in the Repl environment with Lumos packages, we won't repeat these codes for simplicity, but you can take the following as a reference:

$ node
Welcome to Node.js v20.12.0.
Type ".help" for more information.
>
> const lumos = require("@ckb-lumos/lumos");
> const indexer = new lumos.Indexer("https://testnet.ckb.dev/rpc");
> const rpc = new lumos.RPC("https://testnet.ckb.dev/rpc");
> lumos.config.initializeConfig(lumos.config.TESTNET);
> const wallet = {
  address:
    "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqvwg2cen8extgq8s5puft8vf40px3f599cytcyd8",
  privkey: "0x6109170b275a09ad54877b82f7d9930f88cab5717d484fb4741ae9d1dd078cd6",
};
> const wallet2 = {
  address: "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq2prryvze6fhufxkgjx35psh7w70k3hz7c3mtl4d",
  privkey: "0xace08599f3174f4376ae51fdc30950d4f2d731440382bb0aa1b6b0bd3a9728cd"
}

To deploy the script to CKB, we can just create a new cell, with the script code as cell data part:

> const fs = require("fs");
> const data = fs.readFileSync("carrot");
> data.byteLength
7744
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address], wallet2.address, "8000" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.data = "0x" + data.toString("hex");
  return outputs;
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address], 1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const carrotTxHash = await rpc.sendTransaction(signedTx)

Here I simply create a new cell with enough capacity by sending tokens to another wallet. Now we can create the type script containing the carrot script code:

> const bytes = require("@ckb-lumos/lumos/codec").bytes;
> const carrotDataHash = lumos.utils.ckbHash(bytes.bytify("0x" + data.toString("hex")));
> const carrotTypeScript =  {
  codeHash: carrotDataHash,
  hashType: "data",
  args: "0x"
};

Recall the Script data structure:

pub struct Script {
    pub code_hash: H256,
    pub hash_type: ScriptHashType,
    pub args: JsonBytes,
}

We can see that instead of embedding the script code directly in the script data structure, we are only including the code hash, which is a Blake2b hash of the actual script binary code. Since carrot script doesn't use an argument, we can use empty bytes for args part.

Note I'm still ignoring hash_type here, we will leave to a future post to see a different way of specifying code hash. For now, let's keep it simple here.

To run the carrot script, we need to create a new transaction, and set carrot type script as the type script of one of the output cells:

> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address], wallet2.address,"100" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = carrotTypeScript;
  return outputs;
});

There's one more step needed: in order for CKB to locate the carrot script, we need to reference the cell containing carrot script in one of transaction deps:

> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: carrotTxHash,
    index: "0x0"
  },
  depType: "code"
})

Now we are ready to sign and send the transaction:

> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const txHash = await rpc.sendTransaction(signedTx)
> txHash
0xd7b0fea7c1527cde27cc4e7a2e055e494690a384db14cc35cd2e51ec6f078163

Since this transaction does not have any cell containing carrot in the cell data, the type script validates successfully. Now let's try a different transaction that does have a cell that begins with carrot:

> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address],wallet2.address,"400" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = carrotTypeScript;
  cell.data = "0x" + Buffer.from("carrot123", "utf8").toString("hex");
  return outputs;
});
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: carrotTxHash,
    index: "0x0",
  },
  depType: "code",
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures);
> await rpc.sendTransaction(signedTx);
Uncaught:
ResponseException [Error]: {"code":-302,"message":"TransactionFailedToVerify: Verification failed Script(TransactionScriptError { source: Outputs[0].Type, cause: ValidationFailure: see error code -1 on page.."}

We can see our carrot script rejects a transaction that generates a cell with carrot. Now I can use this script to make sure all my cells are free from carrots!

So to recap, to deploy and run a script as type script, what we need to do is:

1. Compile the script to RISC-V executable binary
2. Deploy the binary in a cell's data part
3. Create a type script data structure with the blake2b hash of the binary as code hash, any required arguments of the script code in the args part
4. Create a new transaction with the type script set in one of the generated cells
5. Include the outpoint to the cell containing the script code as one of the transaction deps

That's really all you need! If your script has run into problems, those are the points you need to check.

Although we only talk about type scripts here, lock script works exactly the same way. The only quirk you need to keep in mind, is that when you create a cell with a specificed lock script, the lock script won't run here. It only runs when you are consuming the cell. So while type script can be used to create the logic that runs when you create the cell, lock script is used to create the logic that runs when you consume the cell. Given this consideration, please make sure your lock script is correct, otherwise you might be losing the tokens in the following scenarios:

• Your lock script has a bug that someone else can unlock your cell.
• Your lock script has a bug that no one(including you) can unlock your cell.

One tip we can provide here, is always test your script as a type script attached to an output cell in your transaction, this way when error happens, you will know immediately, your tokens can stay safe.

Introducing Duktape

I'm sure you feel the same way as I do now: it's good we can write contracts in C, but C always feels a bit tedious and, let's face it, dangerous. Is there a better way?

Yes of course! We mentioned above CKB VM is essentially a mini computer, and there are tons of solutions we can explore. One thing we have prepared here, is that we can write CKB script codes in JavaScript. Yes you got it right, plain ES5(yes I know, but this is just one example, and you can use a transpiler) JavaScript.

How this is possible? Since we have C compiler available, all we did is just take a JavaScript implementation for the embeded system, in our case, duktape, compile it from C to RISC-V binary, put it on chain, then boom, we can run JavaScript in CKB! Since we are working with a real mini computer here, there's no stopping us from embeding another VM as CKB script to CKB VM, and exploring this VM on top of VM path.

And we can actually expand from this path, we can have JavaScript on CKB via duktape, we can also have Ruby on CKB via mruby, we can even have Bitcoin Script or EVM on chain if we just compile their VM and put it on chain. This ensures CKB VM can both help us preserve legacy and build a diversified ecosystem. All languages should be and are treated equal on CKB, the freedom should be in the hands of blockchain contract developers.

At this stage you might want to ask: yes this is possible, but won't VM on top of VM be slow? I believe it really depends on your use case to say if this is gonna be slow. I'm a firm believer that benchmarks make no sense unless we put it in a real use case with standard hardware requirements. So wait to see if this is really gonna be an issue. In my opinion, higher languages are more likely to be used in type scripts to guard cell transformation, in this case, I doubt it's gonna be slow. Besides, we are also working on this field to optimize both CKB VM and the VMs on top of CKB VM to make it faster and faster :P

To use duktape on CKB, first you need to compile duktape itself into a RISC-V executable binary:

$ git clone https://github.com/xxuejie/ckb-duktape.git
$ cd ckb-duktape
$ git submodule init
$ git submodule update
$ sudo docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
root@0d31cad7a539:~# cd /code
root@0d31cad7a539:/code# make
riscv64-unknown-elf-gcc -Os -DCKB_NO_MMU -D__riscv_soft_float -D__riscv_float_abi_soft -Iduktape -Ic -Ischema -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/molecule -Wall -Werror c/entry.c -c -o build/entry.o
riscv64-unknown-elf-gcc -Os -DCKB_NO_MMU -D__riscv_soft_float -D__riscv_float_abi_soft -Iduktape -Ic -Ischema -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/molecule -Wall -Werror duktape/duktape.c -c -o build/duktape.o
riscv64-unknown-elf-gcc build/entry.o build/duktape.o -o build/duktape -lm -Wl,-static -fdata-sections -ffunction-sections -Wl,--gc-sections -Wl,-s
riscv64-unknown-elf-gcc -Os -DCKB_NO_MMU -D__riscv_soft_float -D__riscv_float_abi_soft -Iduktape -Ic -Ischema -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/molecule -Wall -Werror c/repl.c -c -o build/repl.o
riscv64-unknown-elf-gcc build/repl.o build/duktape.o -o build/repl -lm -Wl,-static -fdata-sections -ffunction-sections -Wl,--gc-sections -Wl,-s
riscv64-unknown-elf-gcc -Os -DCKB_NO_MMU -D__riscv_soft_float -D__riscv_float_abi_soft -Iduktape -Ic -Ischema -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/molecule -Wall -Werror c/dump_load.c -c -o build/dump_load.o
riscv64-unknown-elf-gcc build/dump_load.o build/duktape.o -o build/dump_load -lm -Wl,-static -fdata-sections -ffunction-sections -Wl,--gc-sections -Wl,-s
gcc -Wall -Werror -Iduktape -O3 c/native_dump_bytecode.c duktape/duktape.c -o build/native_dump_bytecode -lm
riscv64-unknown-elf-gcc -Os -DCKB_NO_MMU -D__riscv_soft_float -D__riscv_float_abi_soft -Iduktape -Ic -Ischema -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/molecule -Wall -Werror c/dump_load_nocleanup.c -c -o build/dump_load_nocleanup.o
riscv64-unknown-elf-gcc build/dump_load_nocleanup.o build/duktape.o -o build/dump_load_nocleanup -lm -Wl,-static -fdata-sections -ffunction-sections -Wl,--gc-sections -Wl,-s
gcc -Wall -Werror -Ischema -Ideps/ckb-c-stdlib/molecule -O3 c/native_args_assembler.c -o build/native_args_assembler
root@0d31cad7a539:/code# exit
exit
$ ls build/
duktape               dump_load             dump_load_nocleanup   entry.o               native_dump_bytecode  repl.o
duktape.o             dump_load.o           dump_load_nocleanup.o native_args_assembler repl

Like the carrot example, the first step here is to deploy duktape script code in a CKB cell:

> const data = fs.readFileSync("../ckb-duktape/build/duktape");
> data.byteLength
291440
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address],wallet2.address,"292000" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.data = "0x" + data.toString("hex");
  return outputs;
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const duktapeTxHash = await rpc.sendTransaction(signedTx)
> const duktapeCodeHash = lumos.utils.ckbHash(bytes.bytify("0x" + data.toString("hex")));

Unlike the carrot example, duktape script code now requires one argument: the JavaScript source you want to execute and the arguments to pass to the JavaScript source code. ckb-duktape provides a small binary tool called native_args_assembler to help us provide the script args from the js file and the js arguments.

First, let's create the script args:

> docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
> cd /code
> echo "CKB.debug(\"I'm running in JS\")" > test.js
> ./build/native_args_assembler -f test.js
370000000c00000033000000000000001f000000434b422e6465627567282249276d2072756e6e696e6720696e204a5322290a04000000

Next, copy the script args and build the script:

> const duktapeTypeScript =  {
  codeHash: duktapeCodeHash,
  hashType: "data",
  args: "0x370000000c00000033000000000000001f000000434b422e6465627567282249276d2072756e6e696e6720696e204a5322290a04000000"
};

Notice that with a different argument, you can create a different duktape powered type script for different use case:

> docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
> cd /code
> echo "var a = 1;var b = a + 2;" >> test.js
> ./build/native_args_assembler -f test.js
330000000c0000002f000000000000001b0000007661722061203d20313b5c6e7661722062203d2061202b20323b0a04000000

> const duktapeTypeScript =  {
  codeHash: duktapeCodeHash,
  hashType: "data",
  args: "0x330000000c0000002f000000000000001b0000007661722061203d20313b5c6e7661722062203d2061202b20323b0a04000000"
};

This echos the differences mentioned above on script code vs script: here duktape serves as a script code providing a JavaScript engine, while different script leveraging duktape script code serves different functionalities on chain.

Now we can create a cell with the duktape type script attached:

> const duktapeTypeScript =  {
  codeHash: duktapeCodeHash,
  hashType: "data",
  args: "0x370000000c00000033000000000000001f000000434b422e6465627567282249276d2072756e6e696e6720696e204a5322290a04000000"
};
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address],wallet2.address,"200" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = duktapeTypeScript;
  return outputs;
});
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: duktapeTxHash,
    index: "0x0"
  },
  depType: "code"
})
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const txHash = await rpc.sendTransaction(signedTx)

We can see that the script executes successfully, and if you have ckb-script module's log level set to debug in your ckb.toml file, you can also notice the following log:

2019-07-15 05:59:13.551 +00:00 http.worker8 DEBUG ckb-script  script group: c35b9fed5fc0dd6eaef5a918cd7a4e4b77ea93398bece4d4572b67a474874641 DEBUG OUTPUT: I'm running in JS!

Now you have successfully deploy a JavaScript engine on CKB, and run JavaScript based script on CKB! Feel free to try any JavaScript code you want here.

A Thought Exercise

Now you are familiar with CKB script basics, here's one thought exercise: in this post you've seen what an always-success script looks like, but what about an always-failure script? How small an always-faliure script(and script code) can be?

A hint: this is NOT a gcc flag-tweaking optimization contest, this is merely a thought exercise.

Next

I know this is a long post, I hope you have tried this and successfully deployed a script to CKB. In the next post, we will introduce an important topic: how to issue your own user defined tokens(UDT) on CKB. The best part of UDTs on CKB, is that each user can store their UDTs in their own cells, which is different from ERC20 tokens on Ethereum, where everyone's token will have to live in the token issuer's single address. All of this can be achieved by using type scripts alone. If you are interested please stay tuned :)

This post is written based on current CKB Lina mainnet version now.

While Ethereum has a unique storage space for each contract account, CKB spreads data among multiple cells. A cell's lock & type script then tells which account the cell belongs to, as well as how you can interact with the cell. The consequence of this, is that unlike ERC20 which stores all token users' balances in the ERC20 contract's storage space, in CKB we will need a new design to store the balances of UDT users.

We could, of course, designate a special cell to keep the balances of all UDT users. This solution would look a lot like Ethereum's ERC20 design. But several problems arise:

• The token issuer would have to provide storage space for keeping all the users' balances. As the number of user grows, the storage space would also grow, in CKB's economic model, this won't be an effective design.
• Consider that updating a cell in CKB is essentially destroying the old cell and re-create a new one, having a single cell with all balances would create a bottleneck: every action which needs to update UDT balance would have to update the one and only cell. People will compete on using the cell.

While there are solutions which can mitigate or even solve the above problems, we started to question the basic design here: does it really make sense to keep all UDTs in a single place? Once transferred, the UDTs really should belong to the receiver, why should the balance still be kept in a central place?

That leads to our proposed design here:

1. A special type script denotes that the cell stores UDTs.
2. The first 4 bytes of the cell data contains the amount of UDTs in current cell.

This design has several implications:

• The storage cost for a UDT cell is always constant, it is irrelevant to the amount of UDTs stored in the cell.
• A user can transfer either all or part of the UDTs in a cell to others
• In practice, there might be numerous cells containing the same UDTs.
• The lock script used to guard a UDT is decoupled from the UDT itself.

Each token user then keeps their UDTs in their own cells. They are responsible for providing the storage space for the UDTs, and ensure their own tokens are secure. This way UDTs can truly belong to each individual UDT user.

One question remains here: if tokens are stored in numerous cells belonging to each user instead of a single place, how can we ensure the tokens are indeed created by token issuer? What if someone forges tokens on their own? In Ethereum, this is probably a problem, but as we shall see in this post, a type script in CKB can prevent all those attacks, ensuring your token is safe.

Writing the UDT Script

Given the above design, a minimal UDT type script should guard the following rules:

• In a UDT transfer transaction, the sum of UDTs in the output cells should equal the sum of UDTs in the input cells.
• Only the token issuer can generate new tokens in the initial token creation process.

This might sound a little ambitious, but we will see that with a type script and some CKB's unique design patterns, the eagle can be landed :P

For simplicity, we will write the UDT script here in pure JavaScript, while a C version might help in saving cycles, the functionality will be the same.

First, we will need to loop through all input cells and gather the sum of UDTs:

diff --git a/udt.js b/udt.js
index e69de29..4a20bd0 100644
--- a/udt.js
+++ b/udt.js
@@ -0,0 +1,17 @@
+var input_index = 0;
+var input_coins = 0;
+var buffer = new ArrayBuffer(4);
+var ret = CKB.CODE.INDEX_OUT_OF_BOUND;
+
+while (true) {
+  ret = CKB.raw_load_cell_data(buffer, 0, input_index, CKB.SOURCE.GROUP_INPUT);
+  if (ret === CKB.CODE.INDEX_OUT_OF_BOUND) {
+    break;
+  }
+  if (ret !== 4) {
+    throw "Invalid input cell!";
+  }
+  var view = new DataView(buffer);
+  input_coins += view.getUint32(0, true);
+  input_index += 1;
+}

As explained in the previous post, CKB requires us to use a loop to iterate through all inputs in the same group and fetch the data. In C we would use ckb_load_cell_data, which is wrapped into a JS function CKB.raw_load_cell_data. As indicated by the ArrayBuffer, we are only interested in the first 4 bytes of the cell data, since those 4 bytes will contain the amount of UDTs.

Note that here we perform a simple add operation on input_coins, this is very dangerous. We are doing it just for simplicity, in a production setting, you should check if the value will hold in a 32-bit integer value. Higher precision number types should be used if needed.

Similarly, we can fetch the sum of output coins and do the comparision:

diff --git a/udt.js b/udt.js
index 4a20bd0..e02b993 100644
--- a/udt.js
+++ b/udt.js
@@ -15,3 +15,23 @@ while (true) {
   input_coins += view.getUint32(0);
   input_index += 1;
 }
+
+var output_index = 0;
+var output_coins = 0;
+
+while (true) {
+  ret = CKB.raw_load_cell_data(buffer, 0, output_index, CKB.SOURCE.GROUP_OUTPUT);
+  if (ret === CKB.CODE.INDEX_OUT_OF_BOUND) {
+    break;
+  }
+  if (ret !== 4) {
+    throw "Invalid output cell!";
+  }
+  var view = new DataView(buffer);
+  output_coins += view.getUint32(0, true);
+  output_index += 1;
+}
+
+if (input_coins !== output_coins) {
+  throw "Input coins do not equal output coins!";
+}

This is almost all we need to validate the first rule: the sum of UDTs in the output cells should equal the sum of UDTs in the input cells. In other words, with this type script now, no one will be able to forge new tokens. Isn't that wonderful?

But there's one quirk: when we say no one will be able to forge new tokens, we really mean no one, including the token issuer! This is no good, we need to add an exception so the token issuer can create the tokens first, but no one will be able to do that after. Is there a way to do that?

Yes there is! But the answer reads like a riddle, so please read this paragraph carefully if I lost you the first time: a type script consist of 2 parts: a code hash denoting the actual code, and args used by the type script. 2 type scripts with different args will be treated 2 different type scripts. The trick here, is to allow the token issuer to create a cell with a new type script, that no one will be able to create again, so if we put something in the args part that is not be able to included again, the problem will be solved.

Now think about this problem: what cannot be included in a blockchain twice? An OutPoint in a transaction input! The first time we include an OutPoint as a transaction input, the referenced cell will be consumed, if someone later include it again, it will create a double-spending error, which is exactly what we use blockchain for.

And we have the answer now! The full validation flow of a minimal UDT type script in CKB, is as follows:

1. First gather the sum of all UDTs in the input cells and the sum of all UDTs in the output cells, if they are equaled, the type script exits with a success status.
2. Check if the first argument of the type script matches the first OutPoint in current transaction, if they match, exit with a success status.
3. Otherwise exit with a failure status

If you are still with me here, you will see that step 1 corresponds to a normal UDT transfer, while step 2 corresponds to the initial token creation process.

This is what we mean by CKB's unique design pattern: by using an input OutPoint as a script argument, we can create a unique script that cannot be forged again:

1. If an attacker tries to use the same argument, the script will validate that the first input OutPoint in the transaction does not match the argument, hence invalidates the transaction;
2. If the attacker tries to use the same argument and fill in the argument as the first input OutPoint, it will create a double-spent error, also invalidates the transaction;
3. If the attacker tries to use a different argument, CKB will recognize that the different argument leads to a different type script, hence generating a different UDT.

This simple yet powerful pattern thus ensures the UDTs stay safe while enjoying the benefits that they can be transferred freely among many different cells. To the best of our knowledge, this pattern is not possible yet in many other blockchains which claim to be flexible or programmable.

Now we can finally complete the UDT script:

diff --git a/contract.js b/contract.js
deleted file mode 100644
index e69de29..0000000
diff --git a/udt.js b/udt.js
index e02b993..cd443bf 100644
--- a/udt.js
+++ b/udt.js
@@ -1,3 +1,7 @@
+if (CKB.ARGV.length !== 1) {
+  throw "Requires only one argument!";
+}
+
 var input_index = 0;
 var input_coins = 0;
 var buffer = new ArrayBuffer(4);
@@ -33,5 +37,17 @@ while (true) {
 }

 if (input_coins !== output_coins) {
-  throw "Input coins do not equal output coins!";
+  if (!((input_index === 0) && (output_index === 1))) {
+    throw "Invalid token issuing mode!";
+  }
+  var first_input = CKB.load_input(0, 0, CKB.SOURCE.INPUT);
+  if (typeof first_input === "number") {
+    throw "Cannot fetch the first input";
+  }
+  var hex_input_outpoint = Array.prototype.map
+   .call(new Uint8Array(first_input), function (x) {
+     return ("00" + x.toString(16)).slice(-2);
+   })
+   .join("")
+   .slice(16); // remove the first 8 bytes of since
+  var outpoint_arg = new TextDecoder().decode(CKB.ARGV[0]);
+  if (outpoint_arg != hex_input_outpoint) {
+    throw "Invalid creation argument!";
+  }
 }

And that's it, with 53 lines of code or 1372 bytes, we've completed a minimal UDT type script in CKB. Notice I don't even use a minimizer here, with any decent JS minimizer, we should be able to get a much more compact type script. Of course this is a production ready script, but it suffices to show a simple script is enough to handle important tasks in CKB.

Deploying to CKB

I'm not like some other organizations who prefer to only show you a video and a provocative post which hide how they did it and the accompanying problems. I believe no post is fun without actual code and steps to play with it. And here's how you can use the above UDT script on CKB:

In case you might need it, here's the full UDT script without diff format:

$ cat udt.js
if (CKB.ARGV.length !== 1) {
  throw "Requires only one argument!";
}

var input_index = 0;
var input_coins = 0;
var buffer = new ArrayBuffer(4);
var ret = CKB.CODE.INDEX_OUT_OF_BOUND;

while (true) {
  ret = CKB.raw_load_cell_data(buffer, 0, input_index, CKB.SOURCE.GROUP_INPUT);
  if (ret === CKB.CODE.INDEX_OUT_OF_BOUND) {
    break;
  }
  if (ret !== 4) {
    throw "Invalid input cell!";
  }
  var view = new DataView(buffer);
  input_coins += view.getUint32(0, true);
  input_index += 1;
}

var output_index = 0;
var output_coins = 0;

while (true) {
  ret = CKB.raw_load_cell_data(buffer, 0, output_index, CKB.SOURCE.GROUP_OUTPUT);
  if (ret === CKB.CODE.INDEX_OUT_OF_BOUND) {
    break;
  }
  if (ret !== 4) {
    throw "Invalid output cell!";
  }
  var view = new DataView(buffer);
  output_coins += view.getUint32(0, true);
  output_index += 1;
}

if (input_coins !== output_coins) {
  if (!((input_index === 0) && (output_index === 1))) {
    throw "Invalid token issuing mode!";
  }
  var first_input = CKB.load_input(0, 0, CKB.SOURCE.INPUT);
  if (typeof first_input === "number") {
    throw "Cannot fetch the first input";
  }
  var hex_input_outpoint = Array.prototype.map
    .call(new Uint8Array(first_input), function (x) {
      return ("00" + x.toString(16)).slice(-2);
    })
    .join("")
    .slice(16); // remove the first 8 bytes of since
  var outpoint_arg = new TextDecoder().decode(CKB.ARGV[0]);
  if (outpoint_arg != hex_input_outpoint) {
    throw "Invalid creation argument!";
  }
}

In order to run JavaScript, let's first deploy duktape on CKB:

> const fs = require("fs");
> const data = fs.readFileSync("../ckb-duktape/build/duktape");
> data.byteLength
291440
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton, [wallet.address], wallet2.address, "292000" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.data = "0x" + data.toString("hex");
  return outputs;
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton, [wallet.address], 1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const duktapeTxHash = await rpc.sendTransaction(signedTx)
> const duktapeCodeHash = lumos.utils.ckbHash(bytes.bytify("0x" + data.toString("hex")));

First, let's create a UDT with 1000000 tokens

> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton, [wallet.address], wallet2.address, "1820" + "00000000");
> const blockchain = require("@ckb-lumos/base").blockchain;
> const outPointBuf = blockchain.OutPoint.pack(txSkeleton.get("inputs").first().outPoint);
> const outPointHex = Buffer.from(outPointBuf).toString("hex");
> outPointHex
6a5f904a6f6ec270b6dde3add221aa8a82120e2e98ea6dac59160dd09359084201000000

outPointHex is part of the args in the Script, we will use a small tool to build the whole js Script args:

cd ckb-duktape
docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
root@0d31cad7a539:~# cd /code
root@0d31cad7a539:/code# ./build/native_args_assembler -f udt.js -t 6a5f904a6f6ec270b6dde3add221aa8a82120e2e98ea6dac59160dd09359084201000000
b50600000c00000061060000000000004d06000069662028434b422e415247562e6c656e67746820213d3d203129207b0a20207468726f7720225265717569726573206f6e6c79206f6e6520617267756d656e7421223b0a7d0a0a76617220696e7075745f696e646578203d20303b0a76617220696e7075745f636f696e73203d20303b0a76617220627566666572203d206e65772041727261794275666665722834293b0a76617220726574203d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e443b0a0a7768696c6520287472756529207b0a2020726574203d20434b422e7261775f6c6f61645f63656c6c5f64617461286275666665722c20302c20696e7075745f696e6465782c20434b422e534f555243452e47524f55505f494e505554293b0a202069662028726574203d3d3d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e4429207b0a20202020627265616b3b0a20207d0a20206966202872657420213d3d203429207b0a202020207468726f772022496e76616c696420696e7075742063656c6c21223b0a20207d0a20207661722076696577203d206e657720446174615669657728627566666572293b0a2020696e7075745f636f696e73202b3d20766965772e67657455696e74333228302c2074727565293b0a2020696e7075745f696e646578202b3d20313b0a7d0a0a766172206f75747075745f696e646578203d20303b0a766172206f75747075745f636f696e73203d20303b0a0a7768696c6520287472756529207b0a2020726574203d20434b422e7261775f6c6f61645f63656c6c5f64617461280a202020206275666665722c0a20202020302c0a202020206f75747075745f696e6465782c0a20202020434b422e534f555243452e47524f55505f4f55545055540a2020293b0a202069662028726574203d3d3d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e4429207b0a20202020627265616b3b0a20207d0a20206966202872657420213d3d203429207b0a20202020434b422e646562756728726574293b0a202020207468726f772022496e76616c6964206f75747075742063656c6c21223b0a20207d0a20207661722076696577203d206e657720446174615669657728627566666572293b0a20206f75747075745f636f696e73202b3d20766965772e67657455696e74333228302c2074727565293b0a20206f75747075745f696e646578202b3d20313b0a7d0a0a69662028696e7075745f636f696e7320213d3d206f75747075745f636f696e7329207b0a2020696620282128696e7075745f696e646578203d3d3d2030202626206f75747075745f696e646578203d3d3d20312929207b0a202020207468726f772022496e76616c696420746f6b656e2069737375696e67206d6f646521223b0a20207d0a20207661722066697273745f696e707574203d20434b422e6c6f61645f696e70757428302c20302c20434b422e534f555243452e494e505554293b0a202069662028747970656f662066697273745f696e707574203d3d3d20226e756d6265722229207b0a202020207468726f77202243616e6e6f742066657463682074686520666972737420696e707574223b0a20207d0a2020766172206865785f696e7075745f6f7574706f696e74203d2041727261792e70726f746f747970652e6d61700a202020202e63616c6c286e65772055696e743841727261792866697273745f696e707574292c2066756e6374696f6e20287829207b0a20202020202072657475726e202822303022202b20782e746f537472696e6728313629292e736c696365282d32293b0a202020207d290a202020202e6a6f696e282222290a202020202e736c696365283136293b202f2f2072656d6f7665207468652066697273742038206279746573206f662073696e63650a2020766172206f7574706f696e745f617267203d206e657720546578744465636f64657228292e6465636f646528434b422e415247565b305d293b0a2020696620286f7574706f696e745f61726720213d206865785f696e7075745f6f7574706f696e7429207b0a20202020434b422e6465627567286f7574706f696e745f617267290a20202020434b422e6465627567286865785f696e7075745f6f7574706f696e74290a202020207468726f772022496e76616c6964206372656174696f6e20617267756d656e7421223b0a20207d0a7d0a540000000800000048000000366135663930346136663665633237306236646465336164643232316161386138323132306532653938656136646163353931363064643039333539303834323031303030303030

Copy this args to the Script args:

> let duktapeUdtTypeScript = {
    codeHash: duktapeCodeHash,
    hashType: "data",
    args: "0xb50600000c00000061060000000000004d06000069662028434b422e415247562e6c656e67746820213d3d203129207b0a20207468726f7720225265717569726573206f6e6c79206f6e6520617267756d656e7421223b0a7d0a0a76617220696e7075745f696e646578203d20303b0a76617220696e7075745f636f696e73203d20303b0a76617220627566666572203d206e65772041727261794275666665722834293b0a76617220726574203d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e443b0a0a7768696c6520287472756529207b0a2020726574203d20434b422e7261775f6c6f61645f63656c6c5f64617461286275666665722c20302c20696e7075745f696e6465782c20434b422e534f555243452e47524f55505f494e505554293b0a202069662028726574203d3d3d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e4429207b0a20202020627265616b3b0a20207d0a20206966202872657420213d3d203429207b0a202020207468726f772022496e76616c696420696e7075742063656c6c21223b0a20207d0a20207661722076696577203d206e657720446174615669657728627566666572293b0a2020696e7075745f636f696e73202b3d20766965772e67657455696e74333228302c2074727565293b0a2020696e7075745f696e646578202b3d20313b0a7d0a0a766172206f75747075745f696e646578203d20303b0a766172206f75747075745f636f696e73203d20303b0a0a7768696c6520287472756529207b0a2020726574203d20434b422e7261775f6c6f61645f63656c6c5f64617461280a202020206275666665722c0a20202020302c0a202020206f75747075745f696e6465782c0a20202020434b422e534f555243452e47524f55505f4f55545055540a2020293b0a202069662028726574203d3d3d20434b422e434f44452e494e4445585f4f55545f4f465f424f554e4429207b0a20202020627265616b3b0a20207d0a20206966202872657420213d3d203429207b0a20202020434b422e646562756728726574293b0a202020207468726f772022496e76616c6964206f75747075742063656c6c21223b0a20207d0a20207661722076696577203d206e657720446174615669657728627566666572293b0a20206f75747075745f636f696e73202b3d20766965772e67657455696e74333228302c2074727565293b0a20206f75747075745f696e646578202b3d20313b0a7d0a0a69662028696e7075745f636f696e7320213d3d206f75747075745f636f696e7329207b0a2020696620282128696e7075745f696e646578203d3d3d2030202626206f75747075745f696e646578203d3d3d20312929207b0a202020207468726f772022496e76616c696420746f6b656e2069737375696e67206d6f646521223b0a20207d0a20207661722066697273745f696e707574203d20434b422e6c6f61645f696e70757428302c20302c20434b422e534f555243452e494e505554293b0a202069662028747970656f662066697273745f696e707574203d3d3d20226e756d6265722229207b0a202020207468726f77202243616e6e6f742066657463682074686520666972737420696e707574223b0a20207d0a2020766172206865785f696e7075745f6f7574706f696e74203d2041727261792e70726f746f747970652e6d61700a202020202e63616c6c286e65772055696e743841727261792866697273745f696e707574292c2066756e6374696f6e20287829207b0a20202020202072657475726e202822303022202b20782e746f537472696e6728313629292e736c696365282d32293b0a202020207d290a202020202e6a6f696e282222290a202020202e736c696365283136293b202f2f2072656d6f7665207468652066697273742038206279746573206f662073696e63650a2020766172206f7574706f696e745f617267203d206e657720546578744465636f64657228292e6465636f646528434b422e415247565b305d293b0a2020696620286f7574706f696e745f61726720213d206865785f696e7075745f6f7574706f696e7429207b0a20202020434b422e6465627567286f7574706f696e745f617267290a20202020434b422e6465627567286865785f696e7075745f6f7574706f696e74290a202020207468726f772022496e76616c6964206372656174696f6e20617267756d656e7421223b0a20207d0a7d0a540000000800000048000000366135663930346136663665633237306236646465336164643232316161386138323132306532653938656136646163353931363064643039333539303834323031303030303030"
  };
> const bytes = require("@ckb-lumos/lumos/codec").bytes;
> const Uint32LE = require("@ckb-lumos/codec").number.Uint32LE;
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = duktapeUdtTypeScript;
  cell.data = bytes.hexify(Uint32LE.pack(1000000));
  return outputs;
});
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: duktapeTxHash,
    index: "0x0"
  },
  depType: "code"
})
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton, [wallet.address], 3000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const rootUdtTxHash = await rpc.sendTransaction(signedTx)

If we tried to submit the same transaction again, double-spent error will prevent us from forging the same token:

await rpc.sendTransaction(signedTx)
CKB::RPCError: jsonrpc error: {:code=>-3, :message=>"UnresolvableTransaction(Dead(OutPoint(0x0b607e9599f23a8140d428bd24880e5079de1f0ee931618b2f84decf2600383601000000)))"}

And no matter how we tried, we cannot create another cell which forges the same UDT token.

Now we can try transfering UDTs to another account. First let's try creating one which has more output UDTs than input UDTs

> let inputOutpoint = {
  txHash: rootUdtTxHash,
  index: "0x0"
}
> let udtCellWithStatus = await rpc.getLiveCell(inputOutpoint, true);
> let blockHash = (await rpc.getTransaction(rootUdtTxHash)).txStatus.blockHash;
> let blockNumber = (await rpc.getHeader(blockHash)).number;
> let input = {
    outPoint: inputOutpoint,
    data: udtCellWithStatus.cell.data.content,
    cellOutput: udtCellWithStatus.cell.output,
    blockNumber
  }
> let output = {
  data: bytes.hexify(Uint32LE.pack(2000000)),
  cellOutput: udtCellWithStatus.cell.output,
}
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = txSkeleton.update("inputs", (inputs) => inputs.push(input));
> txSkeleton = txSkeleton.update("outputs", (outputs) => outputs.push(output));
> txSkeleton = txSkeleton.update("witnesses", (witnesses) => witnesses.push("0x55000000100000005500000055000000410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"));
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: duktapeTxHash,
    index: "0x0"
  },
  depType: "code"
})
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: lumos.config.TESTNET.SCRIPTS['SECP256K1_BLAKE160']['TX_HASH'],
    index: lumos.config.TESTNET.SCRIPTS['SECP256K1_BLAKE160']['INDEX']
  },
  depType: lumos.config.TESTNET.SCRIPTS['SECP256K1_BLAKE160']['DEP_TYPE']
})
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton, [wallet2.address], 3000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> let signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet2.privkey)).toArray();
> let signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> await rpc.sendTransaction(signedTx)
CKB::RPCError: jsonrpc error: {:code=>-3, :message=>"InvalidTx(ScriptFailure(ValidationFailure(101)))"}

Here we tried to send another user 2000000 UDTs, of course this should trigger an error since we are trying to forge more tokens. But with slight modification, we can show that a UDT transferring transaction works if you respect the sum verification rule:

> txSkeleton = txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = input.cellOutput.type;
  cell.data = bytes.hexify(Uint32LE.pack(1000000));
  return outputs;
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton, [wallet2.address], 3000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet2.privkey)).toArray();
> signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> let txHash = await rpc.sendTransaction(signedTx)

Flexible Rules

The UDT script shown here serves just as an example, in reality, dapps might be more complicated and requires more functions. You are also free to include more features for your UDT scripts depending on your needs, some examples include:

• Here we strictly ensure that the sum of output UDTs equals the sum of input UDTs, but in some cases, it might be enough just to ensure the sum of output UDTs does not exceed the sum of input UDTs. In order words, when not needed, a user can choose to burn the UDTs for the capacities.
• The above UDT script doesn't allow issuing more tokens after the initial creation process, but there might be another type of UDT that allows more issurance from the token issuer. This is also possible on CKB, the actual way to solve this task, is left as an exercise here :)
• Here we limit the script to only create one cell in the initial token creation process, it's also possible to create multiple cells to spread the usage in the initial token creation process.
• While we only cover ERC20 here, ERC721 should also be totally possible.

Notice those are just some examples, the actual ways of using CKB script are limitless here. We are more than happy to see cases where CKB dapp developers amaze us with interesting usage of CKB scripts.

There're many reasons behind this choice, making it a perfect choice for another article or even a conference talk. But fundamentally there lies one important reason: building software is all about finding the right abstraction, and we believe RISC-V is a better abstraction than WebAssembly for public permissionless blockchain.

While WebAssembly is already a huge advancement over higher level programming langauges as well as the first generation blockchain virtual machines, RISC-V works at a much lower level than WebAssembly, making it a more suitable choice for public blockchains which are designed to run for decades to come.

But that still leaves one question unanswered: a significant portion of the blockchain industry is betting on WebAssembly, contributing an (arguably) better ecosystem building on WebAssembly powered dapps. How can CKB compete with that? As mentioned above, RISC-V is actually a lower level of abstraction than WebAssembly, we can port existing WebAssembly programs, and run them on CKB VM directly. This way, we can enjoy the flexibility and stability provided by RISC-V, while also embracing the WebAssembly ecosystem.

In this article, we will show how you can run WebAssembly programs in CKB VM, we will also show that it actually has more benefits running this way than directly using a WebAssembly VM.

Personally, while I believe WebAssembly has some interesting features enabling different use cases, I don't believe WebAssembly has a better ecosystem in the blockchain space. If you look around, there are probably just 2 mature choices for building dapps in a WebAssembly-based blockchain: Rust, and AssemblyScript. People keep bragging about WebAssembly's ability to support arbitrary languages in a single abstract VM(I personally refuse to call WebAssembly low-level VM), but it really just comes down to one of the 2 choices here to build a real dapp. I think we probably have different definitions if we can call 2 supported languages a good VM ecosystem. There are some other languages playing catching up here, but they are not yet at stable phase to count as a richful ecosystem. While some interesting langauges have potentials in a WebAssembly based environment, no one pays attention to support them. And if you look hard enough, it also remains a question if 2 different blockchains using WebAssembly can share contracts with each other. Of course one might say: "well it's just a matter of time, given time more vibrant WebAssembly ecosystem will sprout", but the same argument could apply anywhere: why given time, an ecosystem for RISC-V won't be better?

But enough for the rant, let's just assume for now, WebAssembly does have a blockchain ecosystem, we can show that the 2 widely used choices, AssemblyScript and Rust, are all supported in a CKB VM environment.

I believe no words speak better than a demo you can play with. So let's try the official AssemblyScript and run the compiled program on CKB. We will just use the official example in AssemblyScript's introduction page:

$ cat fib.ts
export function fib(n: i32): i32 {
  var a = 0, b = 1;
    for (let i = 0; i < n; i++) {
        let t = a + b; a = b; b = t;
  }
  return b;
}

Please refer to AssemblyScript's documentation on how to install it. For convenience, I have some steps that you can just copy-paste here.

$ git clone https://github.com/AssemblyScript/assemblyscript.git
$ cd assemblyscript
$ npm install
$ bin/asc ../fib.ts -b ../fib.wasm -O3
$ cd ..

We have a compiled WebAssembly program to use here. What we can do then, is invoke a program named wasm2c to compile it to C source file, then compile it via a RISC-V compiler to a RISC-V program, and run it on CKB VM.

I'm sure you would ask: but this is a hack! It sort of does a decompilation of the WASM program then make it work, you are cheating here. The answer to this question, is yes and no:

• On the one hand, yes I'm cheating here, but the question I'm gonna raise in response is: all we should care, is the end result, if the result is good enough, why should we care if this is cheating? In addition, modern compiler is already complicated enough like a total black box, how can we be sure this decompilation will achieve worse result?
• On the other hand, this is just one way of transforming WebAssembly into RISC-V. There're numerous other ways in which you can achieve the same result. We will come back to this in the Recap section later.

Let's fire up wasm2c and transform the WebAssembly program:

$ git clone --recursive https://github.com/WebAssembly/wabt
$ cd wabt
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .
$ cd ../..
$ wabt/bin/wasm2c fib.wasm -o fib.c

You will see a pair of fib.c and fib.h file in current directory, they contain the transformation result of the WebAssembly program, and when compiled and called correctly, they will achieve the same feature as the WebAssembly program.

We can use a small wrapper C file to invoke the WebAssembly program:

$ cat main.c
#include <stdio.h>
#include <stdlib.h>

#include "fib.h"

int main(int argc, char** argv) {
  if (argc < 2) return 2;

  u8 x = atoi(argv[1]);

  init();

  u8 result = Z_fibZ_ii(x);

  return result;
}

This just reads an integer from a CLI argument, invokes the fibonacci function in the WebAssembly program, then return the result. Let's try compile it first:

$ sudo docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
(docker) $ cd /code
(docker) $ riscv64-unknown-elf-gcc -o fib_riscv64 -O3 -g main.c fib.c /code/wabt/wasm2c/wasm-rt-impl.c -I /code/wabt/wasm2c
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccfUDYhE.o: in function `__retain':
/code/fib.c:1602: undefined reference to `Z_envZ_abortZ_viiii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccfUDYhE.o: in function `i32_load':
/code/fib.c:42: undefined reference to `Z_envZ_abortZ_viiii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccfUDYhE.o: in function `f17':
/code/fib.c:1564: undefined reference to `Z_envZ_abortZ_viiii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/fib.c:1564: undefined reference to `Z_envZ_abortZ_viiii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccfUDYhE.o: in function `f6':
/code/fib.c:1011: undefined reference to `Z_envZ_abortZ_viiii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccfUDYhE.o:/code/fib.c:1012: more undefined references to `Z_envZ_abortZ_viiii' follow
collect2: error: ld returned 1 exit status
(docker) $ exit

As shown above, there's an error here. It tells us there's an Z_envZ_abortZ_viiii function not defined. Let's dive into why this happened.

First, let's transform the original WebAssembly file into a human readable form:

$ wabt/bin/wasm2wat fib.wasm -o fib.wast
$ cat fib.wast | grep "(import"
(import "env" "abort" (func (;0;) (type 2)))

So the problem is that WebAssembly can import external functions, when invoking, provides additional functionalities. In fact, the famous WASI is implemented based on the import feature. Later we shall see import can be used to implement more interesting features that are not possible in WebAssembly based blockchain virtual machines.

For now, let's provide an abort implementation to fix the error:

$ cat main.c
#include <stdio.h>
#include <stdlib.h>

#include "fib.h"

void (*Z_envZ_abortZ_viiii)(u32, u32, u32, u32);

void env_abort(u32 a, u32 b, u32 c, u32 d) {
  abort();
}

int main(int argc, char** argv) {
  if (argc < 2) return 2;

  u8 x = atoi(argv[1]);

  Z_envZ_abortZ_viiii = &env_abort;

  init();

  u8 result = Z_fibZ_ii(x);

  return result;
}
$ sudo docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:xenial bash
(docker) $ cd /code
(docker) $ riscv64-unknown-elf-gcc -o fib_riscv64 -O3 -g main.c fib.c /code/wabt/wasm2c/wasm-rt-impl.c -I /code/wabt/wasm2c
(docker) $ exit

Of course you can test the compiled fib_riscv64 program on CKB. But as a trick, there's a simple CKB VM binary in the test suite we can use the run this particular program. It's worth mentioning that this CKB VM binary works slightly different from the VM in CKB. It suffices to test WebAssembly programs in current example. But for testing proper CKB script, you might want to use the newly built standalone debugger, which follows all CKB semantics. Later posts will explain how the debugger works.

Let's try compile the binary in test suite and run the program:

$ git clone --recursive https://github.com/nervosnetwork/ckb-vm-test-suite
$ cd ckb-vm-test-suite
$ git clone https://github.com/nervosnetwork/ckb-vm
$ cd binary
$ cargo build --release
$ cd ../..
$ ckb-vm-test-suite/binary/target/release/asm64 fib_riscv64 5
Error result: Ok(8)
$ ckb-vm-test-suite/binary/target/release/asm64 fib_riscv64 10
Error result: Ok(89)

The error here is slightly misleading, the binary will treat any non-zero result from the program as errors. Since the program tested return the fibonacci calculation result as the return value, the binary will treat the return value(which is most likely non-zero) as error, but we can see that the actual error value contains the correct fibonacci value.

Now we proves AssemblyScript program indeed works on CKB VM! I'm sure more complicated programs might run into errors which need separate tweaking, but you already get the workflow and know where to look for when error happens :)

Rust

We've already seen simpler examples in the AssemblyScript part. Let's try something more interesting in the Rust part: can we do a whole signature verification in Rust code?

Turns out yes we can! But this is signficantly more than what we can fit in a blog post. I've prepared a demo project showcasing this. It uses a pure Rust implemented secp256k1 library to do signature verification. If you follow the instructions in the README, you can reproduce the exact steps of the following:

• Compile a complicated Rust program into WebAssembly
• Transform the WebAssembly program into RISC-V
• Run the resulting RISC-V program on CKB VM

Enhancements to WebAssembly

There's one additional thing we want to mention: if you check out the bindgen branch of the Rust secp256k1 demo repository, and try the same steps, you will run into the following errors:

/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o: in function `core::result::unwrap_failed':
/code/secp.c:342: undefined reference to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:344: undefined reference to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:344: undefined reference to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:347: undefined reference to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:350: undefined reference to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o:/code/secp.c:353: more undefined references to `Z___wbindgen_placeholder__Z___wbindgen_describeZ_vi' follow
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o: in function `i32_store':
/code/secp.c:56: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_set_nullZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o: in function `i32_load':
/code/secp.c:42: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_set_nullZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o: in function `i32_store':
/code/secp.c:56: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_set_nullZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:56: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_set_nullZ_vi'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /tmp/ccYMiL3C.o: in function `i32_load':
/code/secp.c:42: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_growZ_ii'
/riscv/lib/gcc/riscv64-unknown-elf/8.3.0/../../../../riscv64-unknown-elf/bin/ld: /code/secp.c:42: undefined reference to `Z___wbindgen_anyref_xform__Z___wbindgen_anyref_table_growZ_ii'
collect2: error: ld returned 1 exit status

Following the same steps in the AssemblyScript examples, we can certain imports in the WebAssembly file:

$ wabt/bin/wasm2wat wasm_secp256k1_test.wasm -o secp.wat
$ cat secp.wat | grep "(import"
(import "__wbindgen_placeholder__" "__wbindgen_describe" (func $__wbindgen_describe (type 3)))
(import "__wbindgen_anyref_xform__" "__wbindgen_anyref_table_grow" (func $__wbindgen_anyref_table_grow (type 4)))
(import "__wbindgen_anyref_xform__" "__wbindgen_anyref_table_set_null" (func $__wbindgen_anyref_table_set_null (type 3)))

Those are actually binding environment functions needed in the Rust wasm-bindgen. We will continue to work to provide the bindings compatible with CKB environment. But let's take a step back and think about this now: the environment functions needed here, are not part of WebAssembly standard. What's required in the standard, is that when an import entry cannot be found, the WebAssembly VM is expected to halt execution with an errors. To achieve different features, different WebAssembly based blockchains might inject different imports here, making it hard to write a WebAssembly program that's compatible across different blockchains.

In the CKB environment, however, we can attach any environment functions as we like, hence supporting all WebAssembly programs which are targeting different blockchains. What's more, we can use imports as we like to introduce new features to an existing WebAssembly programs, since the import functions are shipped together with the WebAssembly program, CKB itself doesn't have to do anything to support this, all the magic happens right within a single CKB script. For a WebAssembly powered blockchain, those environment functions are most likely to be fixed and part of the consensus rules, you cannot introduce new ones as you wish. Similarly, this tranformation based workflow on CKB will make it far easier to support new WebAssembly features, such as garbage collection, or threading, it really is just a matter of shipping the support features you need as part of your CKB script, there's no need to wait another 6 months for the next hardfork when a WebAssembly virtual machine gets updated, if it's updated.

It's About Ease of Implementation

You might have one question: "I get it, you have WebAssembly on RISC-V, but I could also have RISC-V on WebAssembly! WebAssembly is flexible!". In a sense, this is true, once a language or a VM surpasses a certain level of flexibility, it can be used to build many (even crazy) things. The first version of jslinux which emulates full x86 was even written in pure JavaScript! But the other side of the problem, is ease of implementation. Building WebAssembly on RISC-V feels more natural, since WebAssembly abstracts at a higher level with many high level features, such as higher level contrl flows, garbage collection, etc. RISC-V, on the other hand, really emulates what a real CPU can do, it is a very thin layer on top of the actual CPU running inside of the computer. So while both directions are possible indeed, certain features are easier to implement in the WebAssembly on RISC-V direction, while roadblocks might sit in front of you in the RISC-V on WebAssembly direction.

One alternative example is EVM, EVM has been advocating turing complete for years, but the sad truth is that it's close to impossible to build arbitrary complicated algorithsm on EVM: either the coding part is too difficult or gas consumption will be unreasonable. People have to come up with all kinds of hacks so as to introduce latest algorithms on EVM, we can only have reasonable blake2b algorithms in EVM when Istanbul hardfork lands. What about many other algorithms?

All of those reflect our rationale behind the RISC-V choice: we want to find the minimal layer on top of this generation's CPU architecture, and RISC-V is the most transparent model we can expose to the blockchain world while ensuring security and performance. Any different models, such as WebAssembly, EVM, etc., should be one layer on top of the RISC-V model, and can be naturally implemented via the RISC-V model. The other direction, however, might not feel so smooth at all.

Recap

Here we demonstrated that you can run non-trivial WebAssembly programs on CKB VM. But we do want to point out this workflow is not without its problems. One gotcha is performance, our preliminary testing shows that the WebAssembly based secp256k1 demo runs 30 times slower than a similar C based implementation compiled directly to CKB VM. After some investigation, we believe this is due to the following problems

• Due to how memory works in WebAssembly, wasm2c has to first put data segments in the code in plain C array, then when booting, allocate enough memory, then do memcpy to copy the data into the allocated memory. For the secp256k1 example, this means every boot of the program has to copy the 1MB pre-computed multiplication table. Combining with the fact that our RISC-V program now uses newlib, which contains a naive memcpy implementation optimized for code size over speed, this can significantly slow down the program.
• While wasm2c can deliver good performance for simpler programs, for a sophisticated and heavily optimized algorithm like secp256k1, the transformation layer could mean that many optimization chances are lost, hence making it slower than a direct implementation compiled directly to RISC-V

Luckily, the problems here are totally solvable. The above mentioned workflow is one way we can translate WebAssembly programs to RISC-V programs, but it's absolutely not the only way to achieve that. Like we mentioned above, the transformation layer hinders optimization opportunities, what if we bring in modern compilers to unleash all the possible optimizations here?

There is already progress being done which translates a WebAssembly program via LLVM into native code. The performance obtained here, is really good. Since LLVM 9 officially supports RISC-V now, it's perfectly possible to change the code so LLVM generates RISC-V assembly instead of x86_64 assembly. This way we can translate WebAssembly program via LLVM directly into a RISC-V program, enjoying all the advanced optimizations LLVM can performn on our code.

As a result, our current solution documented in this post shows this path is totally possible while achieving good enough performance for many existing cases(e.g., many type scripts can be written in Rust for safety, while the performance is not a big problem), this new LLVM solution can provide far better performance for the same workflow in the future. It's just a matter of time for us to find the time to work on this.

This post is written based on current CKB Lina mainnet version now.

The first solution to CKB script debugging, works with compiled languages such as C, Rust, etc. Perhaps you are used to writing C programs, and GDB is your best friend. You are wondering if debugging C programs with GDB is possible, and the answer, of course, is: yes, you can definitely debug your CKB script written in C via GDB! Let me show you how.

First we have the same carrot example from my old posts:

#include <memory.h>
#include "ckb_syscalls.h"

int main(int argc, char* argv[]) {
  int ret;
  size_t index = 0;
  uint64_t len = 0;
  unsigned char buffer[6];

  while (1) {
    len = 6;
    memset(buffer, 0, 6);
    ret = ckb_load_cell_data(buffer, &len, 0, index, CKB_SOURCE_OUTPUT);
    if (ret == CKB_INDEX_OUT_OF_BOUND) {
      break;
    }

    int cmp = memcmp(buffer, "carrot", 6);
    if (cmp) {
      return -1;
    }

    index++;
  }

  return 0;
}

I've made 2 changes to it:

• I've updated the script to make it compatible with CKB v0.23.0. In this version, we should be using ckb_load_cell_data to fetch cell data.
• I've also introduced a slight bug to the code, so we can later try the debugging workflow. You might noticed it if you are familiar with C, but no need to worry if you missed it, I will explain it later.

As usual, let's use our official toolchain to compile it to RISC-V code:

$ ls
carrot.c
$ git clone https://github.com/nervosnetwork/ckb-system-scripts
$ cp ckb-system-scripts/c/ckb_*.h ./
$ ls
carrot.c  ckb_consts.h  ckb_syscalls.h  ckb-system-scripts/
$ sudo docker run --rm -it -v `pwd`:/code nervos/ckb-riscv-gnu-toolchain:bionic-20191012 bash
root@3efa454be9af:/# cd /code
root@3efa454be9af:/code# riscv64-unknown-elf-gcc carrot.c -g -o carrot
root@3efa454be9af:/code# exit

Notice when I compile the script, I added -g so as to generate debugging information which is quite useful in GDB. For a production script, you would almost always want to strip them out to save previous on-chain space.

Now let's deploy the script to CKB. Have your CKB node running, and fire up to Javascript SDK:

$ node
Welcome to Node.js v20.12.0.
Type ".help" for more information.
>
> const lumos = require("@ckb-lumos/lumos");
> const indexer = new lumos.Indexer("https://testnet.ckb.dev/rpc");
> const rpc = new lumos.RPC("https://testnet.ckb.dev/rpc");
> lumos.config.initializeConfig(lumos.config.TESTNET);
> const wallet = {
  address:
    "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqvwg2cen8extgq8s5puft8vf40px3f599cytcyd8",
  privkey: "0x6109170b275a09ad54877b82f7d9930f88cab5717d484fb4741ae9d1dd078cd6",
};
> const wallet2 = {
  address: "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq2prryvze6fhufxkgjx35psh7w70k3hz7c3mtl4d",
  privkey: "0xace08599f3174f4376ae51fdc30950d4f2d731440382bb0aa1b6b0bd3a9728cd"
}

> const data = fs.readFileSync("carrot_bug");
> data.byteLength
19760
> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address],wallet2.address,"19900" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.data = "0x" + data.toString("hex");
  return outputs;
});
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const carrotTxHash = await rpc.sendTransaction(signedTx)

With carrot script on blockchain, we can create a transaction to test the carrot script:

> const carrotDataHash = lumos.utils.ckbHash(bytes.bytify("0x" + data.toString("hex")));
> const carrotTypeScript =  {
  codeHash: carrotDataHash,
  hashType: "data",
  args: "0x"
};

> let txSkeleton = lumos.helpers.TransactionSkeleton({ cellProvider: indexer });
> txSkeleton = await lumos.commons.common.transfer(txSkeleton,[wallet.address],wallet2.address,"100" + "00000000");
> txSkeleton.update("outputs", (outputs) => {
  let cell = outputs.first();
  cell.cellOutput.type = carrotTypeScript;
  return outputs;
});
> txSkeleton = lumos.helpers.addCellDep(txSkeleton, {
  outPoint: {
    txHash: carrotTxHash,
    index: "0x0"
  },
  depType: "code"
})
> txSkeleton = await lumos.commons.common.payFeeByFeeRate(txSkeleton,[wallet.address],1000);
> txSkeleton = lumos.commons.common.prepareSigningEntries(txSkeleton);
> const signatures = txSkeleton.get("signingEntries").map((entry) => lumos.hd.key.signRecoverable(entry.message, wallet.privkey)).toArray();
> const signedTx = lumos.helpers.sealTransaction(txSkeleton, signatures)
> const txHash = await rpc.sendTransaction(signedTx)

Uncaught:
ResponseException [Error]: {"code":-302,"message":"TransactionFailedToVerify: Verification failed Script(TransactionScriptError { source: Outputs[0].Type, cause: ValidationFailure: see error code -1 on page..

If you checked the transaction carefully, you will noticed that none of the output cells has data starting with carrot. However we still run into validation failure, it means our script must have a bug. Previously, you would run out of options here, you might go back to check the code, hoping you can see where it goes wrong. But that is not necessary now, you can just dump the transaction here, and feed it into a standalone CKB debugger to debug it!

First, let's dump the transaction together with its surrounding environment, into a local file:

> let txJson = rpc.paramsFormatter.toRawTransaction(lumos.helpers.createTransactionFromSkeleton(txSkeleton))
> fs.writeFileSync('failed-tx.json', JSON.stringify(txJson, null, 2))

You will need ckb-transaction-dumper to convert the failed-tx.json to a dump transaction:

$ ckb-transaction-dumper -t failed-tx.json -o carrot.json

Now let's try ckb-standalone-debugger: