standards: add integration hardening and docs

Author: HDauven

.github/workflows/standards-hardening.yml

@@ -0,0 +1,31 @@
+name: Standards Hardening
+
+on:
+  workflow_dispatch:
+    inputs:
+      property_cases:
+        description: Property-test cases per invariant
+        required: false
+        default: "8192"
+      data_driver_cases:
+        description: Forge data-driver fuzz cases
+        required: false
+        default: "2048"
+  schedule:
+    - cron: "17 2 * * *"
+
+jobs:
+  hardening:
+    name: Standards property and ABI fuzzing
+    runs-on: core
+    timeout-minutes: 240
+    env:
+      STANDARDS_PROPTEST_CASES: ${{ github.event.inputs.property_cases || '8192' }}
+      STANDARDS_PROPTEST_MAX_SHRINK_ITERS: "16384"
+      STANDARDS_DATA_DRIVER_FUZZ_CASES: ${{ github.event.inputs.data_driver_cases || '2048' }}
+      STANDARDS_DATA_DRIVER_FUZZ_SHRINK_ITERS: "4096"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dsherret/rust-toolchain-file@v1
+      - run: rustup target add wasm32-unknown-unknown
+      - run: make standards-hardening

Makefile

@@ -1,4 +1,6 @@
-STANDARDS_WASM_CONTRACTS := standards/examples/drc20_roles_pausable standards/examples/drc721_collection standards/examples/multisig_controller standards/examples/proxy_counter
+STANDARDS_EXAMPLES := standards/examples/authorization_counter standards/examples/drc20_roles_pausable standards/examples/drc721_collection standards/examples/multisig_controller standards/examples/proxy_counter
+STANDARDS_TEST_HELPERS := standards/examples/moonlight_call_router
+STANDARDS_WASM_CONTRACTS := $(STANDARDS_EXAMPLES) $(STANDARDS_TEST_HELPERS)
 LEGACY_SUBDIRS := tests/alice tests/bob tests/charlie genesis/transfer genesis/stake tests/host_fn
 STANDARDS_PROPTEST_CASES ?= 8192
 STANDARDS_PROPTEST_MAX_SHRINK_ITERS ?= 16384

docs/dusk-contract-standards-audit.md

@@ -0,0 +1,152 @@
+# Dusk Contract Standards Audit Packet
+
+This document is the auditor-facing entry point for the Dusk-native standards
+layer. It captures the review scope, security assumptions, invariant matrix,
+validation commands, and known residual risks for this branch.
+
+## Scope
+
+In scope:
+
+- `standards/dusk-contract-standards/src/**`
+- `standards/examples/authorization_counter`
+- `standards/examples/drc20_roles_pausable`
+- `standards/examples/drc721_collection`
+- `standards/examples/multisig_controller`
+- `standards/examples/proxy_counter`
+- `scripts/dusk-contract-standards-local-smoke.sh`
+- `standards/dusk-contract-standards/tests/**`
+
+Out of scope:
+
+- Dusk protocol consensus, wallet, node, prover, and VM internals.
+- Forge macro implementation correctness, except where the generated
+  data-driver and Wasm artifacts are exercised through this repository's tests.
+- Economic policy choices such as exact upgrade delays, role assignment
+  procedures, and marketplace royalty enforcement.
+- Compatibility with Ethereum/OpenZeppelin ABIs where Dusk-native semantics
+  deliberately diverge.
+
+## Security Model
+
+The standards layer assumes:
+
+- `CallContext::current()` correctly reports observed Moonlight root callers
+  through `public_sender`, including normal transfer-contract entrypoint
+  execution, and reports immediate contract callers for nested calls.
+- Phoenix calls do not expose a stable caller identity. Phoenix authorization
+  must therefore be an explicit Schnorr signature over an `AuthorizedAction`.
+- Dusk signature primitives verify according to their upstream implementations.
+- `abi::self_id()`, `abi::block_height()`, `abi::emit`, and contract-call
+  routing are provided correctly by the host.
+- Client encoders use the same schema and byte serialization as the generated
+  Forge data-drivers.
+
+The layer does not assume:
+
+- an Ethereum-like `msg.sender` for Phoenix;
+- delegatecall-style proxy storage behavior;
+- off-chain signatures are safe without chain/contract/domain/action/payload
+  binding;
+- zero principals are valid owners, recipients, spenders, operators, or admins.
+
+## Invariant Matrix
+
+| ID | Invariant | Primary Coverage |
+| --- | --- | --- |
+| AUTH-1 | Signed actions bind chain id, contract, domain, action id, payload hash, nonce, principal, and expiry before nonce/replay consumption. | `tests/primitives.rs`, `tests/properties.rs`, VM test, local-node smoke |
+| AUTH-2 | Rejected envelope, signature, expiry, role, owner, admin, and replay-key cases do not advance nonce/replay state. | property negative matrices, VM test, local-node smoke |
+| AUTH-3 | Phoenix authorization proves control of a Schnorr key principal and never relies on observed caller identity. | primitives, properties, signed auth example, local-node smoke |
+| AUTH-4 | Moonlight owners can authorize by observed root caller or signed BLS action; contract owners only by observed immediate contract caller. Transfer-contract entrypoint calls map to `public_sender`, while nested calls do not. | primitives, reference contracts, VM test, `core::context` unit tests |
+| MULTISIG-1 | Threshold multisig requires distinct owner quorum and rejects duplicate signers before nonce/replay consumption. | primitives |
+| MULTISIG-2 | Observed Moonlight/contract owners can count toward quorum; Phoenix owners require signed action approvals. | primitives |
+| MULTISIG-3 | Multisig owner and threshold maintenance requires current quorum and rejected changes leave state unchanged. | primitives |
+| MULTISIG-4 | Standalone controller proposal/confirmation requires distinct owners, rejects non-owners and duplicate confirmations without nonce movement, expires stale proposals, tombstones executed ids, and clears stale pending operations after authority-removing changes. | primitives, properties, VM test |
+| MULTISIG-5 | A contract-owned proxy/admin path can be controlled by a 2-of-3 standalone multisig controller through observed inter-contract caller context, while direct owner calls to the governed target fail. | VM test, local-node smoke |
+| ACCESS-1 | Role grants/revokes are admin-gated, reject zero accounts, and emit typed events when state changes. | primitives, DRC20 reference, data-driver event decoding |
+| ACCESS-2 | Owner and owner-set initialization reject zero principals atomically. | primitives, properties |
+| PAUSE-1 | Reference pausable DRC20/DRC721 pause all balance-changing operations. | primitives, VM test, local-node smoke |
+| PAUSE-2 | Approvals remain available while paused and do not move balances or ownership. | VM test, local-node smoke |
+| TOKEN20-1 | DRC20 total supply equals the modeled sum of balances after arbitrary operation sequences. | property state-machine model |
+| TOKEN20-2 | DRC20 transfer, transfer-from, allowance, mint, burn, cap, and vote checkpoint failures are atomic. | primitives, properties |
+| TOKEN721-1 | DRC721 owner, balance, approval, operator, enumerable, and total-supply views remain internally consistent. | property state-machine model |
+| TOKEN721-2 | DRC721 mint, transfer, burn, approval, operator, and royalty failures are atomic. | primitives, properties |
+| ROYALTY-1 | Royalty receivers cannot be zero, basis points cannot exceed 10,000, and overflow-prone quotes do not mutate state. | primitives, properties |
+| NONCE-1 | Nonce domains are independent, monotonic, import/export safe, and atomic on rejection. | primitives, properties |
+| REPLAY-1 | Replay keys cannot be reused for the same principal and import/export is monotonic. | primitives, properties |
+| PROXY-1 | Upgrade admin rejects zero admin/implementation and binds signed admin actions to exact payloads. | primitives, VM test, local-node smoke |
+| PROXY-2 | Prepare, activate, cancel, rollback, and rollback-finalization obey delay/window state transitions and emit events. | primitives, properties, data-driver event decoding |
+| TIMELOCK-1 | Timelock scheduling/execution/cancellation follows delay and predecessor constraints. | primitives, properties |
+| TIMELOCK-2 | Controller minimum-delay changes are self-governed through scheduled operations, not direct arbitrary admin mutation. | primitives, properties |
+| REENTRANCY-1 | Scoped guard rejects nested entry and resets after panics. | primitives |
+| ABI-1 | Forge data-driver schemas load for every reference contract. | `tests/data_driver_fuzz.rs` |
+| ABI-2 | Function inputs JSON-encode, decode, and re-encode consistently; malformed and mutated payloads do not crash. | `tests/data_driver_fuzz.rs` |
+| ABI-3 | Function outputs and typed events decode from rkyv and mutated output/event payloads do not crash readers. | `tests/data_driver_fuzz.rs` |
+| NODE-1 | Real local Rusk deployment accepts valid signed calls and rejects replay, bad payload, expired action, pause, and proxy replay cases while preserving expected state. | `scripts/dusk-contract-standards-local-smoke.sh` |
+
+## Reproducible Validation
+
+Run the audit-grade validation pass:
+
+```sh
+./scripts/dusk-contract-standards-audit-grade.sh
+```
+
+Default intensity:
+
+- `STANDARDS_PROPTEST_CASES=8192`
+- `STANDARDS_PROPTEST_MAX_SHRINK_ITERS=16384`
+- `STANDARDS_DATA_DRIVER_FUZZ_CASES=4096`
+- `STANDARDS_DATA_DRIVER_FUZZ_SHRINK_ITERS=8192`
+
+For a funded local-node run, start Rusk and provide wallet/node settings:
+
+```sh
+RUN_LOCAL_NODE_SMOKE=1 \
+RUSK_URL=http://127.0.0.1:18080 \
+RUSK_WALLET_BIN=/path/to/rusk-wallet \
+WALLET_DIR=target/rusk-local-smoke/wallet \
+WALLET_RESTORE_FILE=/path/to/wallet.dat \
+./scripts/dusk-contract-standards-audit-grade.sh
+```
+
+For dependency advisory scanning, install `cargo-audit` and opt in:
+
+```sh
+RUN_CARGO_AUDIT=1 ./scripts/dusk-contract-standards-audit-grade.sh
+```
+
+## Focused Reviews
+
+- `docs/dusk-contract-standards-multisig-controller-review.md`
+
+## Auditor Checklist
+
+Reviewers should focus on:
+
+- whether the Dusk principal model is the right abstraction for Moonlight,
+  Phoenix, and contract callers;
+- whether every public signed path uses action-bound helpers before nonce
+  consumption;
+- whether single-owner admin paths should be replaced with
+  `ThresholdMultisig` composition or standalone `MultisigController`
+  ownership before production deployment;
+- whether payload-hash construction is unambiguous and domain separated enough
+  for downstream wallets;
+- whether pause semantics match product/security expectations;
+- whether upgrade and timelock policies are sufficient for production systems;
+- whether any event is missing for an indexer-relevant state change;
+- whether generated data-driver schemas are acceptable as the client/wallet
+  ABI source of truth.
+
+## Residual Risks
+
+The branch is audit-ready, not audit-complete. Remaining risk areas:
+
+- independent client encoders may still disagree with Forge data-drivers unless
+  they are tested differentially;
+- Dusk runtime host-function behavior is assumed rather than proven here;
+- no formal verification is included for arithmetic or state machines;
+- dependency advisory scanning is optional unless `cargo-audit` is installed;
+- local-node smoke is deterministic and adversarial for defined invariants, but
+  it is not a long-running network chaos test.

docs/dusk-contract-standards-hardening.md

@@ -0,0 +1,168 @@
+# Dusk Contract Standards Hardening Track
+
+This branch is a separate hardening track for the Dusk-native standards layer.
+It keeps implementation work close to the contracts, but treats security
+validation as a first-class deliverable rather than a final smoke test.
+
+## Current Scope
+
+The first hardening pass focuses on invariants that should hold regardless of
+the composing contract:
+
+- signed authorization must bind contract, domain, action id, payload hash,
+  nonce, principal, and expiry before nonce/replay state is consumed;
+- Phoenix signed authorization must preserve nonce and replay-key state across
+  all rejected envelope, signature, expiry, policy, and replay-key cases;
+- owner, role, and upgrade-admin checks must not consume a valid signer nonce
+  when the signer is not authorized for the policy being checked;
+- threshold multisig checks must verify distinct owner quorum before consuming
+  any signer nonce or replay key;
+- mixed owner-set checks must follow the same no-consume-on-unauthorized rule;
+- failed token operations must not leave partial native state behind;
+- DRC20 total supply must equal the modeled sum of balances for all touched
+  accounts;
+- DRC20 allowance movement must match the reference model exactly;
+- DRC721 total supply must equal the modeled number of live token ids;
+- DRC721 owner, approval, operator, balance, and enumerable views must remain
+  internally consistent after arbitrary operation sequences;
+- nonce import/export and replay-key import/export must be monotonic,
+  idempotent, and atomic on rejected nonce consumption;
+- voting checkpoints must reject non-monotonic writes without partially
+  updating account or total-supply checkpoints;
+- royalty registry mutations and overflow-prone royalty quotes must leave
+  registry state unchanged on rejection;
+- supply-cap changes must reject cap reductions below current supply and
+  overflow-prone mints without moving the configured cap;
+- owner-set initialization and timelock-controller maintenance operations must
+  validate before mutating durable state;
+- the reserved zero principal must not be accepted as an actor, recipient,
+  spender, minter, burner, or operator where that would create ownership or
+  authorization state.
+
+## Added Validation
+
+`standards/dusk-contract-standards/tests/properties.rs` adds property-based
+state-machine tests for:
+
+- action-bound authorization rejection cases;
+- Phoenix action-bound authorization rejection and replay-key preservation
+  cases;
+- mixed owner sets;
+- access-control role/admin mutation;
+- timelock scheduling, execution, cancellation, and delay mutation;
+- timelock-controller self-governed delay changes and malformed maintenance
+  payload rejection;
+- upgrade-admin prepare, activate, cancel, rollback, and finalization flows;
+- nonce/replay state import, consumption, and rejection;
+- two-step ownership;
+- DRC20 supply caps and voting-unit checkpoints;
+- DRC20 accounting and allowance flows;
+- DRC721 ownership, approval, operator, balance, and enumerable views;
+- DRC721 royalty registry mutation and quote behavior.
+
+The tests generate random operation sequences, run them against the real
+primitive and an independent model, and assert after each operation that:
+
+- success/failure matches the model;
+- successful calls produce the exact expected state;
+- failing calls leave the pre-call state unchanged.
+
+The saved proptest regression file keeps the self-transfer case that caught a
+DRC20 accounting bug during this pass.
+
+The extended invariant pass also found and fixed:
+
+- a `VotingUnits::move_units` atomicity bug where an account checkpoint could
+  be written before a later total-supply checkpoint rejected the operation;
+- an `OwnerSet::init` atomicity bug where a later invalid owner could leave
+  earlier owners in the set;
+- a `TimelockController::execute_min_delay_change` atomicity bug where a
+  malformed payload could mark an operation done before being rejected.
+
+## Commands
+
+Run the hardening tests with:
+
+```sh
+cargo test -p dusk-contract-standards
+cargo test -p dusk-contract-standards --test properties
+```
+
+Run the long randomized hardening loop with:
+
+```sh
+start=$(date +%s)
+end=$((start + 14400))
+while [ "$(date +%s)" -lt "$end" ]; do
+  PROPTEST_CASES=2048 PROPTEST_MAX_SHRINK_ITERS=8192 \
+    cargo test -p dusk-contract-standards --test properties
+done
+```
+
+On April 26, 2026, this loop ran for 14,404 seconds and completed 367 full
+property-suite iterations without a failure.
+
+On April 26, 2026, the extended 16-test property suite also passed a
+4,096-case focused run:
+
+```sh
+PROPTEST_CASES=4096 PROPTEST_MAX_SHRINK_ITERS=8192 \
+  cargo test -p dusk-contract-standards --test properties
+```
+
+The property suite now also honors `STANDARDS_PROPTEST_CASES` and
+`STANDARDS_PROPTEST_MAX_SHRINK_ITERS`, which lets CI run longer without
+editing the test source:
+
+```sh
+STANDARDS_PROPTEST_CASES=8192 STANDARDS_PROPTEST_MAX_SHRINK_ITERS=16384 \
+  cargo test -p dusk-contract-standards --test properties
+```
+
+Forge data-driver ABI fuzzing covers JSON-to-rkyv input encoding, input
+decoding, roundtrips, malformed JSON, bad shapes, unknown functions, output
+decoding, typed event decoding, and mutated input/output/event payloads for the
+five standards reference contracts:
+
+```sh
+make standards-data-drivers
+STANDARDS_DATA_DRIVER_FUZZ_CASES=2048 \
+  cargo test -p dusk-contract-standards --test data_driver_fuzz -- --ignored
+```
+
+The `standards-hardening` workflow runs these longer property and data-driver
+fuzz jobs on demand and nightly.
+
+Run the audit-grade validation script with:
+
+```sh
+./scripts/dusk-contract-standards-audit-grade.sh
+```
+
+See `docs/dusk-contract-standards-audit.md` for the auditor-facing scope,
+threat model, invariant matrix, and residual-risk register.
+
+Run the full standards validation pass with:
+
+```sh
+cargo fmt
+cargo test -p dusk-contract-standards
+cargo build --release -Z build-std=core,alloc --target wasm32-unknown-unknown \
+  -p authorization-counter \
+  -p drc20-roles-pausable \
+  -p drc721-collection \
+  -p multisig-controller \
+  -p proxy-counter \
+  --features authorization-counter/contract,drc20-roles-pausable/contract,drc721-collection/contract,multisig-controller/contract,proxy-counter/contract
+cargo test -p dusk-contract-standards --test examples_vm -- --ignored
+make standards-data-drivers
+cargo test -p dusk-contract-standards --test data_driver_fuzz -- --ignored
+cargo clippy -p dusk-contract-standards --all-targets -- -D warnings
+```
+
+## Next Research Items
+
+The next hardening layer should add differential tests against independent
+client encoders, formal or semi-formal arithmetic/state-machine proofs, and
+local-node scenario tests that intentionally mix successful transactions with
+rejected transactions across block boundaries over longer runs.