Fix canonical entry witness examples

Author: a19q3

Cargo.lock

@@ -183,9 +183,13 @@ which is the fillable skeleton a Rust builder can attach to the candidate
 transaction after replacing placeholders with concrete cell, capacity, and
 dry-run facts.
 
-`cellc entry-witness` emits the raw `_cellscript_entry` payload. Do not wrap it
-in `WitnessArgs.input_type` unless the CellScript source explicitly reads that
-separate CKB witness surface.
+`cellc entry-witness` emits the raw `_cellscript_entry` payload, not a complete
+transaction witness. For the canonical
+`cellscript-witnessargs-input-type-v2` placement ABI, parse or create the
+selected script-group `WitnessArgs`, preserve its `lock` and `output_type`
+fields, and place the payload in `input_type` before any lock-script signer
+runs. Never submit the raw `CSARGv1` payload as a transaction witness and never
+mutate `input_type` after signing.
 
 ## ProofPlan And Builder Assumptions
 

docs/examples/token_amm_bootstrap.md

@@ -7,3 +7,6 @@ publish = false
 
 [dependencies]
 cellscript-ckb-adapter = { path = "../../crates/cellscript-ckb-adapter" }
+
+[dev-dependencies]
+ckb-types = "1.0.0"

examples/ckb-sdk-builder/Cargo.toml

@@ -24,8 +24,27 @@ It demonstrates the boundary:
   outputs, lineage, witnesses, warnings, and estimated fee without rendering UI.
 - `AcceptedActionReport` records cycles, tx-pool acceptance, optional submitted
   tx hash, tx size, occupied capacity, fee, and lineage after node checks.
+- `place_entry_witness_payload_before_signing` preserves the existing
+  `WitnessArgs.lock` and `output_type` fields while placing the compiler-emitted
+  `CSARGv1` payload in canonical `WitnessArgs.input_type`. Call it before any
+  lock-script signer because the signature commits to the complete witness.
 - `ckb-sdk-rust` owns transaction building, signer integration, RPC cycle
   estimation, tx-pool acceptance, and optional submission.
 
+The placement step is explicit:
+
+```rust
+let witness = place_entry_witness_payload_before_signing(
+    &base_witness_args,
+    EntryWitnessPlacementAbi::WitnessArgsInputTypeV2,
+    entry_payload,
+)?;
+```
+
+`entry_payload` is the raw output of `cellc entry-witness`; the resulting
+serialized `WitnessArgs` is the transaction witness. A raw `CSARGv1` payload,
+`output_type` alias, or post-signing mutation is not compatible with the 0.23
+CKB entry ABI.
+
 The cookbook tests are offline and do not require a running CKB node. Focused
 local-node evidence lives in `scripts/cellscript_ckb_adapter_acceptance.sh`.

examples/ckb-sdk-builder/README.md

@@ -9,6 +9,7 @@ pub use cellscript_ckb_adapter::*;
 #[cfg(test)]
 mod tests {
     use super::*;
+    use ckb_types::{bytes::Bytes, packed::WitnessArgs, prelude::*};
 
     #[test]
     fn cookbook_uses_formal_adapter_crate() {
@@ -20,4 +21,25 @@ mod tests {
         assert!(!evidence.ckb_vm_execution);
         assert!(!evidence.tx_pool_acceptance);
     }
+
+    #[test]
+    fn cookbook_places_entry_payload_in_witnessargs_input_type_before_signing() {
+        let base = WitnessArgs::new_builder()
+            .lock(Some(Bytes::from(vec![0u8; 65])).pack())
+            .output_type(Some(Bytes::from_static(b"preserved-output-type")).pack())
+            .build();
+        let payload = Bytes::from_static(b"CSARGv1\0\x2a\0\0\0\0\0\0\0");
+
+        let witness =
+            place_entry_witness_payload_before_signing(&base, EntryWitnessPlacementAbi::WitnessArgsInputTypeV2, payload.clone())
+                .expect("canonical entry placement should succeed before signing");
+
+        assert_eq!(witness.lock().to_opt().expect("lock placeholder preserved").raw_data().len(), 65);
+        assert_eq!(witness.input_type().to_opt().expect("entry payload placed").raw_data(), payload);
+        assert_eq!(
+            witness.output_type().to_opt().expect("output_type preserved").raw_data(),
+            Bytes::from_static(b"preserved-output-type")
+        );
+        assert_eq!(EntryWitnessPlacementAbi::WitnessArgsInputTypeV2.name(), ENTRY_WITNESS_PLACEMENT_ABI);
+    }
 }

examples/ckb-sdk-builder/src/lib.rs

@@ -524,6 +524,8 @@ fn token_amm_bootstrap_docs_cover_builder_friction_boundary() {
         "launch_token` materialises the Pool and LP receipt topology directly",
         "Do not rely on \"the first action runs on creation\" as a protocol rule",
         "Cell-bound inputs and outputs are transaction Cells, not witness payload args",
+        "place the payload in `input_type` before any lock-script signer runs",
+        "Never submit the raw `CSARGv1` payload as a transaction witness",
         "Strict v0.16 ProofPlan checks compile the bundled token, AMM, and launch actions as original scoped entries",
     ] {
         assert!(bootstrap_text.contains(needle), "bootstrap guide should contain `{needle}`");
@@ -536,6 +538,10 @@ fn token_amm_bootstrap_docs_cover_builder_friction_boundary() {
     ] {
         assert!(bootstrap.contains(needle), "bootstrap guide should contain `{needle}`");
     }
+    assert!(
+        !bootstrap.contains("Do not wrap it in `WitnessArgs.input_type`"),
+        "bootstrap guide must not reintroduce the retired raw-witness placement guidance"
+    );
 
     let flows = std::fs::read_to_string(
         Utf8PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs").join("CELLSCRIPT_EXAMPLE_BUSINESS_FLOWS.md"),