Wire the Product CDM manifest and contract resolver

[knzeng-e]

Outcome

The Product CDM runtime adapter is now backed by a real contract resolver over
a generated cdm.json snapshot, selectable with
VITE_DOTIFY_RUNTIME_ADAPTER=product-cdm. It stays off by default. Catalog
reads can route through Product SDK contract handles; contract writes stay on
the viem signer path.

This is the Phase 4 "wire a generated CDM manifest/types into Product mode"
item from docs/backlog/polkadot-product-readiness-and-killer-dapp-roadmap.md
(#85). Stacked on #112.

Issue and context

The previous branch left ProductCdmRuntimeAdapter unreachable: it knew how to
map Dotify's runtime surface onto Product contract handles, but nothing could
produce those handles. createProductCdmRuntimeContractResolver documented the
gap explicitly.

The roadmap framed the blocker as needing CDM-installed packages. That turned
out to be wrong, and the correction is the main design decision here.

Architecture and key concepts

A generated snapshot manifest, not cdm install. Dotify's Solidity
contracts are deployed through Asset Hub's eth-rpc, which is a compatibility
layer over pallet-revive - the same pallet the Product SDK contract helpers
target. The deployed H160 addresses are therefore already reachable through
@parity/product-sdk-contracts with no PolkaVM recompilation and no registry
entry. CdmJsonContract needs only version, address, and abi for
getContract(), and new ContractManager(...) is documented as snapshot-only.

web/scripts/generate-cdm-manifest.mjs emits that snapshot from the same
Hardhat artifacts the viem bindings come from, so the two adapters cannot
disagree about an ABI.

Output	Contents
cdm.json	@dotify/artist-directory, @dotify/artist-runtime-factory at their deployments.json addresses
smartRuntime.ts	merged artist-runtime diamond facet ABI (41 entries)
cdm.d.ts	Contracts module augmentation for typed handles

Artist runtimes are deliberately absent from the manifest: a diamond is deployed
per artist, so its address is known at call time, not build time. A placeholder
address would misrepresent the deployment.

flowchart LR
  Artifacts[Hardhat artifacts] --> Gen[generate-cdm-manifest]
  Deployments[deployments.json] --> Gen
  Gen --> Manifest[cdm.json + cdm.d.ts]
  Gen --> Facets[merged facet ABI]
  Manifest --> Manager[ContractManager<br/>fixed addresses]
  Facets --> Create[createContract<br/>per-artist diamond]
  Manager --> Resolver[ProductCdmContractResolver]
  Create --> Resolver
  Resolver --> Adapter[ProductCdmRuntimeAdapter]
  Adapter --> Ports[RuntimeReadPort]

Loading

Design decisions and tradeoffs

Build-time selection, not runtime. Two reasons. Switching the authority for
access policy is a deployment decision an operator makes with evidence, not
something a page should be able to flip. And Vite inlines the value, so a
viem build tree-shakes the entire Product contract graph away:

Build	Output
unset or viem	4.4 MB
product-cdm	10 MB

The 5.6 MB difference is @parity/product-sdk-descriptors, whose shared
descriptors module references every chain's metadata. Only one chunk is fetched
at runtime, but all are published, and Bulletin storage is a finite quota.
Both shipped builds stay at 4.4 MB.

Reads only. RuntimeWritePort has no equivalent provider on purpose.
Routing a payment or a publication through a signer with no host transaction
evidence is not a reasonable default.

No fallback on failure. A failed Product setup rejects every read with that
error rather than degrading to viem. The adapter in use must never be
ambiguous, because the artist runtime is the authority on access policy.

A lazy facade instead of call-site churn. Every RuntimeReadPort method
already returns a promise, so the Product adapter's async setup hides behind a
facade rather than turning ~16 call sites into double-awaits.

Two SDK constraints that shaped this

1. createChainClient routes exclusively through the Product host provider
   and throws when none is present - there is no direct-WebSocket fallback.
   Product mode is therefore impossible in a standalone build, and
   validateProductionEnvironment now rejects product-cdm unless
   VITE_DOTIFY_HOST_MODE is enabled.

2. The host decides which chain an environment resolves to, and only
   devnet is correct - see the follow-up commit below. A wrong environment
   resolves every manifest address to an account with no code, which reads as
   artists with no releases. verifyDeployment() queries artistCount before
   any catalog read and fails closed with a named error.

createChainClient is used rather than the zero-config getChainAPI because
the preset table references every environment's assetHub, bulletin, and
individuality descriptors.

Corrections to the previous branch's notes

Both "unverified" markers I added on #112 were resolved by reading the SDK
types, and the code was already right:

• payForAccess - TxOptions carries value?: bigint and methods take
  positional args followed by an options object, so [contentHash, { value }]
  is correct.
• waitForTransaction - .tx() resolves at best-block by default and
  TxResult carries the including block, so txContract has already awaited
  inclusion. The no-op is safe by construction, not an omission. That is the
  same point viem's waitForTransactionReceipt resolves at.

The adapter's structural type mirror also matches the real SDK exactly:
Result is {ok,value}|{ok,error} and QueryResult is
{success,value,gasRequired}.

Separately, Polkadot Hub TestNet is live again - head at block 11,544,296,
past the 10,612,201 freeze, with the ArtistDirectory still returning code. The
existing deployments.json deployment survived; no redeploy was needed.

Review guide

1. web/scripts/generate-cdm-manifest.mjs - manifest shape, facet merge
   collision check, why unnamed params are renamed for codegen only.
2. web/src/features/runtime/productCdmContracts.ts - the two resolution paths
   and verifyDeployment.
3. web/src/features/runtime/runtimeReaderProvider.ts - the build-time gate and
   the no-fallback property.
4. web/src/features/runtime/runtimeAdapterConfig.ts +
   deploymentSafety.ts - fail-closed selection and the host-mode requirement.

Verify carefully

• A viem build still contains no Product contract or descriptor chunks.
• product-cdm without a host mode is rejected at build time.
• An unknown adapter value falls back to viem rather than disabling reads.
• Writes still go through the viem signer in every mode.
• cdm.json addresses match deployments.json.

Validation

Evidence	Result
cd web && npm run test:unit	216 pass (was 215 on #112; +14 over main, covering adapter selection, the resolver, the build-time gate, and the no-fallback property)
cd web && npm run lint	0 errors; the 3 pre-existing App.tsx/ArtistShell.tsx warnings remain
cd web && npm run build	pass - 4.4 MB, 0 chain-metadata chunks, Product graph tree-shaken
cd web && npm run build:product-devnet	pass - 4.4 MB
VITE_DOTIFY_RUNTIME_ADAPTER=product-cdm npm run build:product-devnet	pass - 10 MB, CDM chunk + 4 metadata chunks present
cd web && npm run smoke:production-env	pass
cd services/api && npm run typecheck && npm test	pass, 92 tests
cd contracts/evm && npm run fmt:check	pass
node scripts/backlog-sync.mjs --check --offline	pass; pre-existing warnings remain
git diff --check	clean

Chain liveness confirmed read-only against eth-rpc-testnet.polkadot.io:
eth_blockNumber = 11544296, eth_chainId = 420420417, and eth_getCode on
the directory returns bytecode.

Known limitations and follow-ups

Not smoke-tested against a real Product host. Every Product path here is
exercised through injected dependencies, not a live container. The resolver
cannot be run outside a host at all, by SDK design.

The chain question is settled - and the answer removed a blocker. Product
DevNet is not a separate network: it is a preset over the Paseo system
parachains (Asset Hub 1000, People 1004, Bulletin 1010) at EVM chain
420420417, which is exactly where Dotify is already deployed. Verified
read-only: eth-rpc-testnet.polkadot.io and
paseo-assethub-rpc.laissez-faire.trade return the same chain id, blocks one
apart, and byte-identical ArtistDirectory code. No contract redeploy is
needed to port Dotify to DevNet.

The correction is that the SDK's paseo preset targets Paseo Next (Asset Hub
Next 1500 / People Next 1502) - a different network per the Product docs. The
default has been changed to devnet and paseo is no longer selectable.

The only gate left for Product contract mode is pallet-revive account mapping
plus real host-signed transaction evidence, before writes can move off the EVM
wallet path.

npm run generate:cdm must be re-run after any contract redeploy, or cdm.json
addresses go stale. This is not yet enforced by CI the way generate:abis is.

---

Follow-up: 9246537 corrects the chain preset

Review round on this branch found the default productEnvironment was wrong,
in a way that would have produced an empty catalog rather than an error at
build time.

Product DevNet is a preset, not a network. It targets the Paseo system
parachains - Asset Hub (1000), People (1004), Bulletin (1010) - at EVM chain
420420417. Verified read-only on 2026-07-29 against the ArtistDirectory at
0xcf1534c6e2b0e43b9436c1e86a076466dc0f2108:

Endpoint	eth_chainId	Block	Directory bytecode
https://eth-rpc-testnet.polkadot.io/	0x190f1b41	11546347	3660 chars, sha256 36707b24…
https://paseo-assethub-rpc.laissez-faire.trade	0x190f1b41	11546348	3660 chars, sha256 36707b24…

Two providers, one chain. Dotify's deployments.json addresses are already
DevNet addresses; no redeploy is required.

The SDK's paseo preset is Paseo Next v2 (Asset Hub Next 1500 / People
Next 1502). The Product documentation states those "belong to a different
network" and "funds sent there will not appear on this Devnet". Dotify has no
deployment there, so ProductChainEnvironment now admits only devnet and the
config guard refuses anything else - a chain that cannot hold the catalog is
not a configuration option.

Also realigns the environment reference tables, clearing three markdownlint
MD060 warnings.

Re-verified after the correction: 216 web tests, 92 API tests, 0 lint errors,
both shipped builds still 4.4 MB, backlog sync clean.