Add NFT collection bootstrap path

Author: a19q3

docs/CELLSCRIPT_EXAMPLE_BUSINESS_FLOWS.md

@@ -15,7 +15,7 @@ examples on a local CKB chain:
 - `token.cell`
 - `vesting.cell`
 
-For those examples, all 43 business actions are strict-compiled, deployed, dry-
+For those examples, all 44 business actions are strict-compiled, deployed, dry-
 run, committed, and measured with builder-generated CKB transactions. The report
 also records cycles, consensus transaction size, occupied capacity, malformed
 transaction rejection, and output-capacity sufficiency.
@@ -211,6 +211,10 @@ and batch mint flows.
 
 ```mermaid
 flowchart TD
+    AO["Collection parameters"] --> AP["create_collection"]
+    AP --> AQ["Check max_supply bounds"]
+    AQ --> AR["Create Collection output Cell"]
+
     A["Collection input Cell"] --> B["mint"]
     B --> C["Check supply below max"]
     C --> D["Update Collection total_supply"]
@@ -264,10 +268,15 @@ flowchart LR
     I["collection_creator"] --> J["Collection creator predicate"]
 ```
 
-CKB acceptance status: all nine actions are builder-backed and run on-chain. The
+CKB acceptance status: all ten actions are builder-backed and run on-chain. The
 five locks strict-compile and have builder-backed valid-spend and invalid-spend
 cases.
 
+Bootstrap note: `mint` and `batch_mint` require an existing `Collection` input
+Cell. Use `create_collection` to materialise the first live `Collection` Cell;
+the stateful NFT listing scenario now proves `create_collection -> mint ->
+create_listing -> buy_from_listing` from committed devnet Cells.
+
 ## `timelock.cell`
 
 Business purpose: absolute and relative time locks, locked assets, normal

docs/releases/CELLSCRIPT_0_13_2_ACCEPTANCE_COMMUNITY_POST.md

@@ -32,10 +32,10 @@ supported as a compatibility wrapper.
 The current release evidence includes:
 
 - 7 production bundled examples.
-- 43/43 production acceptance actions covered.
-- 16 builder-backed lock valid/invalid spend cases.
+- 44/44 production acceptance actions covered.
+- 17 builder-backed lock valid/invalid spend cases.
 - 27 stateful local CKB scenarios.
-- 46 committed stateful steps.
+- 47 committed stateful steps.
 - 7 end-to-end business-flow scenarios.
 - 20 stateful action-branch scenarios.
 

docs/releases/CELLSCRIPT_0_13_2_RELEASE_NOTES.md

@@ -264,14 +264,14 @@ New at the 0.13.2 release cutoff:
   minting, AMM pool lifecycle, vesting revoke, and multisig execution flows;
 - stateful action-branch scenarios cover every production acceptance action not
   already covered by those end-to-end flows;
-- the stateful report must cover 43/43 production acceptance actions with no
+- the stateful report must cover 44/44 production acceptance actions with no
   missing action IDs or missing action artifacts;
 - every stateful step must have dry-run evidence, committed transaction
   evidence, consumed-input liveness checks, output liveness checks, measured
   cycles, consensus-serialized transaction size, occupied-capacity evidence, and
   no under-capacity outputs.
 
-The current release gate expectation is 27 stateful scenarios, 46 committed
+The current release gate expectation is 27 stateful scenarios, 47 committed
 stateful steps, 7 end-to-end business scenarios, and 20 stateful action-branch
 scenarios. If any new production action is added later, the stateful coverage
 gate must fail until that action is covered.

docs/releases/CELLSCRIPT_0_13_RELEASE_SCOPE.md

@@ -286,5 +286,5 @@ python3 scripts/validate_ckb_cellscript_production_evidence.py \
 
 The stateful section is intentionally stricter than a few happy-path flows:
 the current production scope requires 7 end-to-end business scenarios, 20
-stateful action-branch scenarios, 46 committed stateful steps, and 43/43
+stateful action-branch scenarios, 47 committed stateful steps, and 44/44
 production acceptance actions covered with no missing action IDs.

examples/nft.cell

@@ -21,7 +21,7 @@ resource NFT has store, create, consume, replace, burn, relock, read_ref {
     royalty_bps: u16,
 }
 
-resource Collection has store, replace {
+resource Collection has store, create, replace {
     name: String,
     symbol: String,
     creator: Address,
@@ -52,6 +52,12 @@ receipt RoyaltyPayment has create {
     amount: u64,
 }
 
+action create_collection(creator: Address, max_supply: u64, name: String, symbol: String, base_uri: String) -> collection: Collection
+where
+    assert(max_supply > 0, "Max supply must be positive")
+    assert(max_supply <= MAX_SUPPLY, "Max supply too high")
+    create collection = Collection { name, symbol, creator, total_supply: 0, max_supply, base_uri } with_lock(creator)
+
 action mint(collection_before: Collection, to: Address, metadata_hash: Hash) -> (collection_after: Collection, nft: NFT)
 where
     assert(collection_before.total_supply < collection_before.max_supply, "Max supply reached")

scripts/ckb_cellscript_acceptance.sh

@@ -505,7 +505,7 @@ NFT_TYPES_SOURCE = """resource NFT has store, create, consume, replace, burn, re
     royalty_bps: u16
 }
 
-resource Collection has store, replace {
+resource Collection has store, create, replace {
     creator: Address
     total_supply: u64
     max_supply: u64
@@ -533,6 +533,18 @@ receipt RoyaltyPayment has create {
 """
 
 NFT_ACTION_SOURCES = {
+    "create_collection": """
+action create_collection(creator: Address, max_supply: u64) -> collection: Collection
+where
+    assert_invariant(max_supply > 0, "max supply must be positive")
+    assert_invariant(max_supply <= 10000, "max supply too high")
+
+    create collection = Collection {
+        creator: creator,
+        total_supply: 0,
+        max_supply: max_supply
+    } with_lock(creator)
+""",
     "mint": """
 action mint(collection_before: Collection, to: Address, metadata_hash: Hash) -> (collection_after: Collection, nft: NFT)
 where
@@ -1460,6 +1472,7 @@ for action, source in LAUNCH_ACTION_SOURCES.items():
 
 ORIGINAL_SCOPED_ACTIONS = {
     "nft.cell": [
+        "create_collection",
         "mint",
         "transfer",
         "create_listing",
@@ -1512,6 +1525,7 @@ ORIGINAL_SCOPED_LOCK_FAIL_CLOSED = {}
 EXPECTED_SOURCE_ACTIONS = {
     "token.cell": ["mint_with_authority", "transfer_token", "burn", "merge"],
     "nft.cell": [
+        "create_collection",
         "mint",
         "transfer",
         "create_listing",
@@ -2538,6 +2552,9 @@ def molecule_u32(value):
 def molecule_bytes(data):
     return molecule_u32(len(data)) + data
 
+def molecule_string_witness(data):
+    return molecule_bytes(molecule_bytes(data))
+
 def molecule_fixvec(items):
     out = bytearray(molecule_u32(len(items)))
     for item in items:
@@ -3920,7 +3937,36 @@ def build_nft_action_case(action_record, cellscript_lock, cellscript_type, desti
     original_scoped = action_record.get("kind") == "original-scoped-action-strict"
     flow_state = 0 if original_scoped else None
 
-    if action == "mint":
+    if action == "create_collection":
+        name = b"Acceptance Collection"
+        symbol = b"ACPT"
+        base_uri = b"ckb://cellscript/nft/"
+        max_supply = 200
+        valid_collection_payload = (
+            collection_molecule_data(current_owner, 0, max_supply, name, symbol, base_uri)
+            if original_scoped
+            else collection_data(current_owner, 0, max_supply)
+        )
+        malformed_collection_payload = (
+            collection_molecule_data(current_owner, 1, max_supply, name, symbol, base_uri)
+            if original_scoped
+            else collection_data(current_owner, 1, max_supply)
+        )
+        witness = (
+            entry_witness(current_owner, max_supply, molecule_string_witness(name), molecule_string_witness(symbol), molecule_string_witness(base_uri))
+            if original_scoped
+            else entry_witness(current_owner, max_supply)
+        )
+        initial = create_script_locked_cells(
+            "nft.create_collection",
+            [{"capacity": 1000 * 100_000_000, "lock": cellscript_lock, "type": None, "data": b""}],
+            cell_deps,
+        )
+        input_cell = initial["cells"][0]
+        outputs = [{"capacity": hex_u64(1000 * 100_000_000), "lock": cellscript_lock, "type": cellscript_type}]
+        valid_tx = transaction(input_cell, outputs, ["0x" + valid_collection_payload.hex()], cell_deps, [witness])
+        malformed_tx = transaction(input_cell, outputs, ["0x" + malformed_collection_payload.hex()], cell_deps, [witness])
+    elif action == "mint":
         input_collection_payload = (
             collection_molecule_data(current_owner, 10, 1000)
             if original_scoped
@@ -5855,7 +5901,7 @@ def run_stateful_nft_listing_sale(always_success_dep):
     scenario = "nft.mint-list-transfer-by-listing"
     actions = {
         name: deploy_stateful_action(action_record_by(nft_action_artifacts, name), always_success_dep)
-        for name in ("mint", "create_listing", "buy_from_listing")
+        for name in ("create_collection", "mint", "create_listing", "buy_from_listing")
     }
     collection_type = always_success_lock("0xc1")
     nft_type = always_success_lock("0xc2")
@@ -5864,7 +5910,12 @@ def run_stateful_nft_listing_sale(always_success_dep):
     seller = bytes([0x11]) * 32
     buyer_lock = always_success_lock("0xc5")
     buyer = decode_hex(script_hash(buyer_lock), 32)
-    royalty_recipient = seller
+    collection_creator = actions["mint"]["lock_hash"]
+    royalty_recipient = collection_creator
+    collection_name = b"Stateful Collection"
+    collection_symbol = b"SNFT"
+    collection_base_uri = b"ckb://cellscript/stateful-nft/"
+    max_supply = 200
     metadata_hash = bytes([0x33]) * 32
     token_id = 1
     price = 10_000
@@ -5874,32 +5925,51 @@ def run_stateful_nft_listing_sale(always_success_dep):
     steps = []
 
     initial = create_script_locked_cells(
-        "stateful.nft.collection",
+        "stateful.nft.collection_seed",
         [{
             "capacity": 900 * 100_000_000,
-            "lock": actions["mint"]["lock"],
-            "type": collection_type,
-            "data": collection_molecule_data(seller, 0, 1000),
+            "lock": actions["create_collection"]["lock"],
+            "type": None,
+            "data": b"",
         }],
-        actions["mint"]["cell_deps"],
+        actions["create_collection"]["cell_deps"],
     )
-    collection0 = initial["cells"][0]
+    collection_seed = initial["cells"][0]
     tx1 = transaction(
+        collection_seed,
+        [{"capacity": hex_u64(800 * 100_000_000), "lock": actions["mint"]["lock"], "type": collection_type}],
+        ["0x" + collection_molecule_data(collection_creator, 0, max_supply, collection_name, collection_symbol, collection_base_uri).hex()],
+        actions["create_collection"]["cell_deps"],
+        [
+            entry_witness(
+                collection_creator,
+                max_supply,
+                molecule_string_witness(collection_name),
+                molecule_string_witness(collection_symbol),
+                molecule_string_witness(collection_base_uri),
+            )
+        ],
+    )
+    step = run_stateful_step(scenario, "create_collection_for_live_mint", tx1, [collection_seed])
+    steps.append(step)
+    collection0 = output_cell_from_tx(step["commit"], tx1, 0)
+
+    tx2 = transaction(
         collection0,
         [
             {"capacity": hex_u64(500 * 100_000_000), "lock": actions["mint"]["lock"], "type": collection_type},
             {"capacity": hex_u64(300 * 100_000_000), "lock": actions["buy_from_listing"]["lock"], "type": nft_type},
         ],
         [
-            "0x" + collection_molecule_data(seller, token_id, 1000).hex(),
+            "0x" + collection_molecule_data(collection_creator, token_id, max_supply, collection_name, collection_symbol, collection_base_uri).hex(),
             "0x" + nft_data(token_id, seller, metadata_hash, royalty_recipient, 250).hex(),
         ],
         actions["mint"]["cell_deps"],
         [entry_witness(seller, metadata_hash)],
     )
-    step = run_stateful_step(scenario, "mint_nft_for_listing_sale", tx1, [collection0])
+    step = run_stateful_step(scenario, "mint_nft_for_listing_sale", tx2, [collection0])
     steps.append(step)
-    nft_for_sale = output_cell_from_tx(step["commit"], tx1, 1)
+    nft_for_sale = output_cell_from_tx(step["commit"], tx2, 1)
     nft_dep = cell_dep_for(nft_for_sale)
 
     listing_initial = create_script_locked_cells(
@@ -5908,7 +5978,7 @@ def run_stateful_nft_listing_sale(always_success_dep):
         actions["create_listing"]["cell_deps"],
     )
     listing_input = listing_initial["cells"][0]
-    tx2 = transaction(
+    tx3 = transaction(
         listing_input,
         [
             {"capacity": hex_u64(300 * 100_000_000), "lock": actions["buy_from_listing"]["lock"], "type": listing_type},
@@ -5921,11 +5991,11 @@ def run_stateful_nft_listing_sale(always_success_dep):
         [nft_dep] + actions["create_listing"]["cell_deps"],
         [entry_witness(price, created_at)],
     )
-    step = run_stateful_step(scenario, "create_listing_from_live_nft_dep", tx2, [listing_input])
+    step = run_stateful_step(scenario, "create_listing_from_live_nft_dep", tx3, [listing_input])
     steps.append(step)
-    listing = output_cell_from_tx(step["commit"], tx2, 0)
+    listing = output_cell_from_tx(step["commit"], tx3, 0)
 
-    tx3 = transaction(
+    tx4 = transaction(
         [nft_for_sale, listing],
         [
             {"capacity": hex_u64(300 * 100_000_000), "lock": buyer_lock, "type": nft_type},
@@ -5940,7 +6010,7 @@ def run_stateful_nft_listing_sale(always_success_dep):
         actions["buy_from_listing"]["cell_deps"],
         [entry_witness(buyer, seller, price), "0x"],
     )
-    step = run_stateful_step(scenario, "buy_listing_from_live_nft_and_listing", tx3, [nft_for_sale, listing])
+    step = run_stateful_step(scenario, "buy_listing_from_live_nft_and_listing", tx4, [nft_for_sale, listing])
     steps.append(step)
 
     return {
@@ -6561,6 +6631,7 @@ try:
         "burn",
         "buy_from_listing",
         "cancel_listing",
+        "create_collection",
         "create_listing",
         "create_offer",
         "mint",

scripts/validate_ckb_cellscript_production_evidence.py

@@ -47,7 +47,7 @@
     "v0_15_identity_lifecycle.cell",
     "v0_15_scoped_invariant.cell",
 ]
-EXPECTED_ACTION_COUNT = 43
+EXPECTED_ACTION_COUNT = 44
 EXPECTED_STATUS = "passed"
 EXPECTED_MODE = "production"
 EXPECTED_LOCK_SPEND_MATRIX = {
@@ -76,6 +76,7 @@
 EXPECTED_ACTIONS_BY_RUN_KEY = {
     "token_action_runs": ["mint_with_authority", "transfer_token", "burn", "merge"],
     "nft_action_runs": [
+        "create_collection",
         "mint",
         "transfer",
         "create_listing",

tests/backend_shape_baseline.json

@@ -37,15 +37,15 @@
   },
   {
     "example": "nft.cell",
-    "line_count": 13935,
-    "text_size": 54380,
+    "line_count": 14851,
+    "text_size": 57812,
     "relaxed_branch_count": 1,
     "max_cond_branch_abs_distance": 7276,
-    "machine_block_count": 2256,
+    "machine_block_count": 2398,
     "max_machine_block_size": 276,
-    "machine_cfg_edge_count": 3855,
-    "machine_call_edge_count": 538,
-    "unreachable_machine_block_count": 1841
+    "machine_cfg_edge_count": 4078,
+    "machine_call_edge_count": 557,
+    "unreachable_machine_block_count": 2217
   },
   {
     "example": "timelock.cell",