ckbc.md

CKBC Technical Specification and Design Standard

1. Script Definitions and Parameter Specifications

1.1 CKBC UDT Cell

• Capacity: The minimum amount of CKB required for the cell's occupied capacity.
• Lock: A user-defined lock script.
• Type: The standard xUDT script.
  • code_hash: XUDT_CODE_HASH
  • hash_type: XUDT_HASH_TYPE
  • args: [ckbc-vault-type-hash (32 bytes)] + [flags (4 bytes)]
    • ckbc-vault-type-hash: The Blake2b hash of the ckbc-vault-type script.
    • flags: 0xE0000000 (little-endian bytes: 0x000000E0).
      • Enables 0x20000000 (disables Lock Script Hash owner mode for inputs).
      • Enables 0x40000000 (checks Type Script Hashes in outputs).
      • Enables 0x80000000 (checks Type Script Hashes in inputs).
• Data:
  • The first 16 bytes encode amount: u128 in little-endian order, denominated in Shannon (10^8 Shannon = 1 CKB/CKBC).
  • Additional extension data may follow. The current protocol neither interprets this data nor includes it in the token amount.

1.2 CKBC-vault Cell (Vault Cell)

• Capacity: The amount of locked CKB, denominated in Shannon.
• Lock: The always_success lock script.
  • code_hash: ALWAYS_SUCCESS_CODE_HASH
  • hash_type: ALWAYS_SUCCESS_HASH_TYPE
  • args: Empty.
• Type: The ckbc-vault-type script.
  • code_hash: VAULT_TYPE_CODE_HASH
  • hash_type: VAULT_TYPE_HASH_TYPE
  • args: Empty.
• Data:
  • The first 16 bytes encode capacity: u128 in little-endian order, denominated in Shannon. Its value must equal the cell's capacity field.
  • A Vault Cell with fewer than 16 data bytes is invalid. Extension data after byte 16 is ignored and not validated.

---

2. Validation Rules (Enforced by ckbc-vault-type)

Each ckbc-vault-type Script Group found in the inputs or outputs independently performs the following validations.

2.1 Current Pool Identity and Basic Validity

For the currently executing ckbc-vault-type Script Group, define and require the following:

• current_vault_type_hash: The full Type Script Hash of the current Script Group.
• matching_vault_cell: A Vault Cell whose Type Script Hash equals current_vault_type_hash.
• matching_CKBC_cell: A CKBC xUDT Cell that meets all of the following conditions:
  • code_hash == XUDT_CODE_HASH
  • hash_type == XUDT_HASH_TYPE
  • args == [current_vault_type_hash (32 bytes)] + [flags (4 bytes)]
  • flags == 0xE0000000
• The args of ckbc-vault-type must be empty. A Vault Cell with non-empty args is always invalid.
• Input Vault data is not revalidated. A Vault Cell is immutable after creation, and its data was validated when the cell was created as an output. That result is therefore trusted when the cell is later consumed as an input, even after a contract upgrade. All conservation and transaction constraints use the input cells' capacity fields and cell counts directly; they do not depend on input data.

2.2 Capacity and Token Conservation Inequality

The increase in the amount of CKBC tokens in a transaction must not exceed the increase in Vault capacity:

total_output_CKBC - total_input_CKBC <= total_output_vault_capacity - total_input_vault_capacity

• total_input_vault_capacity / total_output_vault_capacity: The sum of the input/output cell capacity fields for all matching_vault_cell instances, denominated in Shannon.
• total_input_CKBC / total_output_CKBC: The sum of the amount values encoded in the first 16 data bytes of all input/output matching_CKBC_cell instances, denominated in Shannon. Any extension data is excluded from the calculation.

2.3 Vault Transaction Limit

A transaction must meet one of the following conditions:

• The inputs contain no Vault Cells for the current pool (minting): count(input.matching_vault_cell) == 0
• The inputs contain Vault Cells for the current pool (partial or full unlock):
  • Total output Vault capacity must be strictly less than total input Vault capacity: output_vault_capacity < input_vault_capacity
  • The number of output Vaults must not exceed the number of input Vaults: count(output.matching_vault_cell) <= count(input.matching_vault_cell)
  • There may be no more than two output Vaults: count(output.matching_vault_cell) <= 2

This rule minimizes the number of public Vaults an attacker can occupy in a single transaction. It cannot prevent an attacker from creating multiple concurrent transactions that occupy Vaults. The transaction pool policy should handle competition between concurrent transactions.

2.4 Vault Capacity Bounds

The capacity of each output Vault Cell, if any, must fall within the following range:

occupied_capacity <= output_vault.capacity <= max_capacity

• occupied_capacity: The minimum capacity derived from the physical byte size occupied by the cell structure at the CKB VM level (typically 90 CKB).
• max_capacity: A protocol-level hard limit embedded in the ckbc-vault-type script code rather than configured dynamically through args. It is fixed at 5,000,000 CKB.

---

3. Standard Transaction Structures

3.1 Mint / Deposit Transaction

• Inputs:
  • User CKB funding Cell(s)
• Outputs:
  • One or more CKBC-vault Cells (total capacity: V_out)
  • One or more CKBC UDT Cells (total amount: U_out, where U_out <= V_out)
  • CKB change Cell(s) (optional)

3.2 Partial Redemption Transaction

• Inputs:
  • One or more CKBC-vault Cells (total capacity: V_in)
  • User CKBC UDT Cells (amount: U_in)
• Outputs:
  • Zero, one, or two CKBC-vault Cells (total capacity: V_out, where V_out < V_in; the count must not exceed the number of input Vaults)
  • User CKB funding Cells (capacity: the remainder of V_in - V_out after deducting the transaction fee)
  • User CKBC UDT Cells (amount: U_out, where U_in - U_out >= V_in - V_out)

3.3 Full Redemption Transaction

• Inputs:
  • One or more CKBC-vault Cells (total capacity: V_in)
  • User CKBC UDT Cells (amount: U_in, where U_in >= V_in)
• Outputs:
  • User CKB funding Cells (capacity: the remainder of V_in after deducting the transaction fee)
  • User CKBC UDT Cells (amount: the remainder of U_in - V_in; omitted when the remainder is zero)

3.4 Standard Transfer Transaction

• Inputs:
  • User CKBC UDT Cell(s)
• Outputs:
  • Recipient CKBC UDT Cell(s)
  • User CKBC UDT change Cell(s) (optional)
• Note: No ckbc-vault-type Cell participates in the transaction, so xUDT applies its standard transfer validation. CKBC represents a redeemable share of the public CKB reserve pool. Redemption rights follow CKBC ownership rather than the identity of the original depositor.