Packages And Provenance

This page explains how package artifacts, provenance, registry approval, and runtime checks fit together. It is intentionally not the full publishing tutorial and not the full provenance reference.

Use the focused pages for details:

Concern	Go to
Build, package, sign, generate payloads, deploy, instantiate, call	Publishing
Descriptor fields, signatures, signing envelope, active provenance policy	Package Provenance
Registry entries, matching rules, statuses, approval policy	Contract Registry
AssemblyScript packaging helpers	AssemblyScript SDK
Runtime sidecar provenance and reproducible builds	Runtime Reproducible Builds
Operator runtime activation and preflight	Smart Contract Runtime Operations

Integrity Chain

A production contract package has several independent checks. Each one answers a different question:

Layer	Question
WASM hash	Are these the exact bytes that were reviewed?
Manifest hash	Is this the exact manifest that was reviewed?
Package descriptor	Do package name, version, runtime, WASM hash, and manifest hash belong together?
Package provenance	Did an accepted signer approve that descriptor?
Contract registry	Did the network approve that package/version/hash tuple for use?
Runtime compatibility	Will the runtime execute the same way under the pinned protocol rules?
Runtime preflight	Is this node ready to execute contracts with the required sidecar?

The usual chain is:

1. Build WASM.
2. Review manifest.
3. Create noos-contract.json with codeHash and manifestHash.
4. Sign the descriptor into provenance/signatures.json.
5. Generate transaction payloads.
6. Register the package when registry policy requires it.
7. Submit transaction DEPLOY_CONTRACT_CODE.
8. Submit transaction INSTANTIATE_CONTRACT.
9. Validators verify hashes, provenance, registry approval, and runtime rules.

If any link changes, rebuild the evidence after that point. For example, a manifest edit changes the manifest hash, which changes the package descriptor, which invalidates previous provenance signatures and registry hash matching.

Package Artifact Boundary

A contract package is the portable artifact that publishers, reviewers, operators, and automation can inspect before submission. The standard package contains:

noos-contract.json
manifest.json
build/
  contract.wasm
README.md
examples/
provenance/
  signatures.json

The package is file-backed so it can be reviewed before any node accepts it. Chain state records the accepted result after transactions execute:

• transaction DEPLOY_CONTRACT_CODE records bytecode by codeHash;
• transaction INSTANTIATE_CONTRACT records the contract instance;
• accepted provenance is stored in contract metadata;
• accepted registry reference is stored in contract metadata;
• registry entries are consensus state.

For exact package commands, use Publishing. For descriptor and signature fields, use Package Provenance.

Runtime Compatibility Vectors

NOOSChain keeps golden compatibility vectors for each protocol-pinned contract runtime. These vectors prove that the same WASM bytecode, manifest, arguments, host snapshot, and block inputs still produce the same sidecar intents and chain state outputs.

The current v1 suite covers:

• successful calls;
• argument handling;
• storage writes;
• events and return values;
• bucket metadata reads;
• encrypted-record metadata reads;
• encrypted-record metadata writes;
• memory pressure;
• large arguments and event payloads;
• traps;
• fuel exhaustion.

Run the compatibility suite:

npm run test:contract-runtime-compatibility

When intentionally adding a new runtime profile, add it in:

src/contracts/runtime-compatibility.ts

Then generate the first golden vector:

NOOS_UPDATE_CONTRACT_RUNTIME_VECTORS=true npm run test:contract-runtime-compatibility

Review the generated JSON under:

test/fixtures/contracts/runtime-compat/

Do not regenerate old profile vectors as a shortcut after changing runtime behavior. If a Wasmtime, ABI, host import, metering, or execution-limit change is intentional, add a new profile and keep old vectors for historical replay.

Runtime Preflight Summary

Before publishing or routing production contract calls to a node, verify the Wasmtime sidecar:

npm run build:contract-wasmtime-sidecar
npm run noos -- contracts runtime preflight --json

The command fails closed unless /node/contracts/runtime/preflight reports ok: true. The result includes the sidecar path, protocol-pinned requirements, sidecar handshake, binary presence, startup check, capabilities, host imports, and fuel metering.

Recommended production environment:

NOOS_SMART_CONTRACTS_ENABLED=true
NOOS_CONTRACT_RUNTIME_PREFLIGHT=required
NOOS_CONTRACT_WASMTIME_SIDECAR_PATH=/opt/noos/bin/noos-contract-executor-wasmtime

Check one contract's readiness on the current node:

npm run noos -- contracts readiness contract-report-store --json
npm run noos -- contracts readiness contract-report-store --refresh --json
npm run noos -- contracts alerts contract-report-store --json

The --refresh form recomputes local runtime, bucket, permission, and payload readiness before returning. The output answers whether the contract is callable on this node now and, if not, why.

For operator runbooks, activation gates, rollout attestations, and sidecar diagnostics, use Smart Contract Runtime Operations.

Dependency And Deactivation Checks

Before deactivating a contract, inspect dependency impact:

npm run noos -- contracts deactivation-dependencies contract-report-store --include-recent-calls --json
npm run noos -- contracts deactivation-dependencies contract-report-store --policy-check --block-registry --require-replacement --replacement-contract-id contract-report-store-v2 --json

The report lists:

• active caller contracts that declare outbound calls to the target;
• the target's outbound dependencies;
• pending migration work;
• matching registry entries;
• recent call metrics when requested;
• recommended operator actions.

The --policy-check form simulates enforced deactivation policy and returns policy.wouldBlockDeactivation with stable blocking reasons. Recent call metrics are advisory; enforced policy uses deterministic chain state.

Publisher Checklist

Before submitting publish transactions:

• WASM was built from the intended source revision;
• manifest was reviewed and matches the intended ABI, auth, buckets, calls, and migrations;
• noos-contract.json contains the expected package name and version;
• descriptor codeHash matches the WASM;
• descriptor manifestHash matches the canonical manifest;
• package provenance exists when policy requires it;
• signer type, signer id, public key, and signature count satisfy policy;
• registry approval exists when registry policy requires it;
• runtime preflight passes on the target node class;
• readiness and monitoring checks are planned after instantiation.

When any of these fail, fix the source artifact and regenerate downstream evidence instead of editing hashes or signatures by hand.

Next Steps

• Publishing
• Package Provenance
• Contract Registry
• AssemblyScript SDK
• Runtime Reproducible Builds
• Smart Contract Runtime Operations
• Security Guide