Omnilock is a new lock script designed for interoperability. It supports various transaction verifications used in popular blockchains, such as Bitcoin, Ethereum, EOS, and the kawaii 🐶 , Dogecoin. Omnilock is also extensible, so more verification algorithms can be added in future. This feature makes Omnilock a powerful module in Nervos interoperability 2.0.

Another feature of Omnilock for practitioners is the regulation compliance module (Consider it as interoperability with the traditional world :-)). If enabled, the specified administrator can revoke tokens held by users under circumstances which the administrator deems proper. This part has evolved from the Regulation Compliance Extension (RCE) proposal for xUDT. This feature provides an option that sits at the other side of the asset lock spectrum and lays the foundation of registered assets like Apple stock on CKB. When used together, Omnilock and RCE provide an ERC-1404 equivalence.

(We used to name this lock Regulation Compliance Lock, or RC Lock. It’s renamed to Omnilock later as more functionalities are added.)

Authentication

Omnilock introduces a new concept, authentication ( auth ) to CKB lock scripts: an auth is a 21-byte data structure containing the following components:

<1 byte flag> <20 bytes auth content>

Depending on the value of the flag, the auth content has the following interpretations:

• 0x0: The auth content represents the blake160 hash of a secp256k1 public key. The lock script will perform secp256k1 signature verification, the same as the SECP256K1/blake160 lock.

• 0x01~0x05: It follows the same unlocking methods used by PW-lock

• 0x06: It follows the same unlocking method used by CKB MultiSig

• 0xFC: The auth content that represents the blake160 hash of a lock script. The lock script will check if the current transaction contains an input cell with a matching lock script. Otherwise, it would return with an error. It's similar to P2SH in BTC.

• 0xFD: The auth content that represents the blake160 hash of a preimage. The preimage contains exec information that is used to delegate signature verification to another script via exec.

• 0xFE: The auth content that represents the blake160 hash of a preimage. The preimage contains dynamic linking information that is used to delegate signature verification to the dynamic linking script. The interface described in Swappable Signature Verification Protocol Spec is used here.

Omnilock Script

An Omnilock script has the following structure:

Code hash: Omnilock script code hash
Hash type: Omnilock script hash type
Args: <21 byte auth> <Omnilock args>

among which, the structure of <Omnilock args> is as follows:

<1 byte Omnilock flags> <32 byte RC cell type ID, optional> <2 bytes minimum ckb/udt in ACP, optional> <8 bytes since for time lock, optional> <32 bytes type script hash for supply, optional>

Administrator Mode

When "administrator mode" is enabled, <32 byte RC cell type ID> must be present. The RC cell type ID contains the type script hash used by a special cell with the same format as RCE Cell. RC cell follows a set of rules and contains whitelists and blacklists. These lists can be used in the SMT proofs scenarios.

The RCE cells are organized in tree structure illustrated in the following diagram:

The above shows the 4 lists in total. The RC Cell type ID is pointed to the root of tree and represents 4 lists in order. If the current RCRule uses blacklist, the auth identity in omni_identity (see below) must not be present in the blacklist SMT tree. If the current RCRule uses whitelist, the auth identity in omni_identity must be present in the whitelist SMT tree.

The RC cell has the following distinctions compared to RCE Cell:

• The cell used here contains auth identities, not lock script hashes.
• If the cell contains an RCRule structure, this structure must be in whitelist mode.
• If the cell contains an RCCellVec structure, there must be at least one RCRule structure using whitelists in the RCCellVec.

To make it easier for reference, we call this cell RC AdminList Cell. To make this mode more flexible, when no type script hash is found in cell_deps, it continues searching input cells with the same type script hash. Once a cell is found, it will be used as RC AdminList Cell.

If the administrator mode flag is on, Anyone-can-pay mode, Time-lock mode and Supply mode flag will be ignored even set. That means both the administrator and the user can unlock the cell, but the administrator is not constrained by timelock. The administrator can only unlock existing cells with Administrator mode on. It's still impossible to bypass supply limitation or mint new tokens at will.

Anyone-can-pay Mode

When anyone-can-pay mode is enabled, <2 bytes minimum ckb/udt in ACP> must be present. It follows the rules of anyone-can-pay lock. The <1 byte CKByte minimum> and <1 byte UDT minimum> are present at the same time.

Time-lock Mode

When time-lock mode is enabled, <8 bytes since for time lock> must be present. The check_since is used. The input parameter since is obtained from <8 bytes since for time lock>.

Supply Mode

When supply mode is enabled, <32 bytes type script hash> must be present. The cell data of info cell which is specified by type script hash has the following data structure:

version (1 byte)
current supply (16 bytes, little endian number)
max supply (16 bytes, little endian number)
sUDT script hash (32 bytes, sUDT type script hash)
... (variable length, other data)

Currently, the version is 0. Only the current supply field can be updated during transactions. The script iterates all input and output cells, accumulating input amounts and output amounts identified by sUDT script hash. Then the script verifies:

<issued amount> = <output amount> - <input amount>
<output current supply> = <issued amount> + <input current supply>

<output current supply> <= <max supply>

All the modes mentioned above can co-exist in Omnilock args in memory layout.

Omnilock Witness

When unlocking an Omnilock, the corresponding witness must be a proper WitnessArgs data structure in molecule format. In the lock field of the WitnessArgs, an OmniLockWitnessLock structure must be present as follows:

import xudt_rce;

array Auth[byte; 21];

table Identity {
    identity: Auth,
    proofs: SmtProofEntryVec,
}
option IdentityOpt (Identity);

// the data structure used in lock field of witness
table OmniLockWitnessLock {
    signature: BytesOpt,
    omni_identity: IdentityOpt,
    preimage: BytesOpt,
}

When omni_identity is present, it will be validated whether the provided auth in omni_identity is present in RC AdminList Cell associated with the current lock script via SMT validation rules. In this case, the auth included in omni_identity will be used in further validation.

If omni_identity is missing, the auth included in lock script args will then be used in further validation.

Once the processing above is successfully done and the auth to be used is confirmed, the flag in the designated auth will be checked for the succeeding operations:

• When the auth flag is 0x0, a signature must be present in OmniLockWitnessLock. We will use the signature for secp256k1 recoverable signature verification. The recovered public key hash using the blake160 algorithm must match the current auth content.

• When the auth flag is 0xFC, we will check against the current transaction, and there must be an input cell, whose lock script matches the auth content when hashed via blake160.

When signature is present, the signature can be used to unlock the cell in anyone-can-pay mode.

When preimage is present, if auth flag is:

• 0xFD (exec): the preimage's memory layout will be as follows:

exec code hash (32 bytes)
exec hash type (1 byte)
place (1 byte)
bounds (8 bytes)
pubkey hash (20 bytes)

Firstly, message, signature, pubkey hash are encoded into hex strings suggested by Ideas on chained locks. Then these strings are passed in as arguments in ckb_exec. The code finally returned is the same as ckb_exec.

• 0xFE (dynamic linking), the preimage's memory layout will be as follows:

dynamic library code hash (32 bytes)
dynamic library hash type (1 byte)
pubkey hash （20 bytes)

It loads the dynamic linking libraries of code hash and hash type, and gets the entry function of validate_signature. Then it calls the entry function to validate the message and signature. The auth returned from the entry function is compared with the blake160 hash of the pubkey. If they are the same, then validation succeeds.

Visit the Github page if you are interested in the related pull requests.

Examples

Unlock via owner's public key hash

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0x0> <pubkey hash 1> <Omnilock flags: 0>
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <valid secp256k1 signature for pubkey hash 1>
        omni_identity: <MISSING>
        preimage: <MISSING>
      <...>

Unlock via owner's lock script hash

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0xFC> <lock hash: 0x1234> <Omnilock flags: 0>
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock: blake160 for this lock script must be 0x1234
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <MISSING>
        omni_identity: <MISSING>
        preimage: <MISSING>
      <...>

Unlock via administrator's public key hash

CellDeps:
    <vec> Omnilock Script Cell
    <vec> RC AdminList Cell 1
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0x0> <pubkey hash 1> <Omnilock flags: 1> <RC AdminList Cell 1's type ID>
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <valid secp256k1 signature for pubkey hash 2>
        omni_identity:
           identity: <flag: 0x0> <pubkey hash 2>
           proofs: <SMT proofs for the above identity in RC AdminList Cell 1>
        preimage: <MISSING>
      <...>

Unlock via administrator's lock script hash (1)

CellDeps:
    <vec> Omnilock Script Cell
    <vec> RC AdminList Cell 1
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0> <pubkey hash 1> <Omnilock flags: 1> <RC AdminList Cell 1's type ID>
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock: blake160 for this lock script must be 0x1234
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <MISSING>
        omni_identity:
           identity: <flag: 0xFC> <lock hash: 0x1234>
           proofs: <SMT proofs for the above identity in RC AdminList Cell 1>
        preimage: <MISSING>
      <...>

Unlock via anyone-can-pay

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0x0> <pubkey hash 1> <Omnilock flags: 2> <2 bytes minimun ckb/udt in ACP>
    <...>
    follow anyone-can-pay rules
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <MISSING>
        omni_identity: <MISSING>
        preimage: <MISSING>
      <...>

Unlock via dynamic linking

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0xFE> <preimage hash> <Omnilock flags: 0>
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <valid secp256k1 signature for pubkey hash 1>
        omni_identity: <MISSING>
        preimage: <code hash> <hash type> <pubkey hash 1>
      <...>

Unlock via exec

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0xFD> <preimage hash> <Omnilock flags: 0>
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <valid secp256k1 signature for pubkey hash 1>
        omni_identity: <MISSING>
        preimage: <code hash> <hash type> <place> <bounds> <pubkey hash 1>
      <...>

Unlock via owner's public key hash with time lock limit

CellDeps:
    <vec> Omnilock Script Cell
Inputs:
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0x0> <pubkey hash 1> <Omnilock flags: 4> <since 1>
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <valid secp256k1 signature for pubkey hash 1>
        omni_identity: <MISSING>
        preimage: <MISSING>
      <...>

Unlock via administrator's lock script hash (2)

Note: the location of RC AdminList Cell 1

CellDeps:
    <vec> Omnilock Script Cell

Inputs:
    <vec> RC AdminList Cell 1
        Data: <RCData, union of RCCellVec and RCRule>
        Type: <its hash is same to RC AdminList Cell 1's type ID>
        Lock: <...>
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock:
            code_hash: Omnilock
            args: <flag: 0> <pubkey hash 1> <Omnilock flags: 1> <RC AdminList Cell 1's type ID>
    <vec> Cell
        Data: <...>
        Type: <...>
        Lock: blake160 for this lock script must be 0x1234
    <...>
Outputs:
    <vec> Any cell
Witnesses:
    WitnessArgs structure:
      Lock:
        signature: <MISSING>
        omni_identity:
           identity: <flag: 0xFC> <lock hash: 0x1234>
           proofs: <SMT proofs for the above identity in RC AdminList Cell 1>
        preimage: <MISSING>
      <...>

✍🏻 This article is written by Jiandong Xu.

Other articles that you might like:

• RVV (RISC-V V Extension): Key to the Efficient On-Chain Cryptography
• Peer Discovery in Nervos Network
• Blockchain Abstraction and Interoperability 2.0