Skip to main content
This document records architecture decisions that are settled enough to guide implementation. Open questions stay in RFCs and target notes until resolved here. See also: Review checklist (English), Review checklist (中文).

Decision Log

IDDateDecisionRationale
D-0012026-06-30RFC 0001 and RFC 0002 are Accepted as the engineering directionDetailed target and backlog docs exist; Draft status was misleading
D-0022026-06-30Phase 1 (target registry + portable IR + artifact metadata) must complete before non-EVM spikesSpikes need capability checks and shared scenario definitions
D-0032026-06-30CosmWasm and Solana spikes run in parallel after Phase 1No fixed order between the two; both validate different backend families
D-0042026-06-30Canonical Solana target id is solana-sbpf-linker Superseded by D-026Stock Zig + sbpf-linker fitted platform tooling; solana-sbf is a filename alias only. D-026 supersedes this with solana-sbpf-asm as the preferred direct-assembly route.
D-0052026-06-30Keep solana-zig-fork as fallback/reference trackMature SDK reference from solana-sdk-mono; not the primary product path
D-0062026-06-30NEAR is the Wasm-host reference; CosmWasm is the first new Wasm spike in-repoFork lessons inform structure; CosmWasm validates host adapter generality
D-0072026-06-30Move POC starts with Aptos only; Sui followsAptos account resources are simpler; Sui object model tests abstraction harder
D-0082026-06-30Move targets use source generation, not Lean runtime on MoveVMProofs stay in Lean; Move carries executable logic only
D-0092026-06-30wasm-polkadot / ink! stays research-onlyNot in the target registry until a spike is scheduled
D-0102026-06-30Cloud platform waits until two or more targets reach Experimental stageAvoid building a UI shell before local backends are real
D-0112026-06-30Add psy-dpn as a Research target under ZK circuit source generationPsy has no public Yul-like IR; first integration should generate .psy and call Dargo
D-0122026-07-01Classify kaspa-toccata as a docs-first Research candidate, not a ZK circuit sourcegen targetToccata is Kaspa L1 programmability through transaction v1, covenants, inline proof verification, and based-app settlement; code registry changes wait until UTXO/covenant capabilities are reviewed
D-0132026-07-01Classify wasm-stellar-soroban as a docs-first Wasm-host Research candidateSoroban emits Wasm but has Stellar-specific storage TTL, authorization, contract spec, deployment, and CLI semantics; registry changes wait until the first spike path is chosen
D-0142026-07-01Classify wasm-icp-canister as a docs-first Wasm-host Research candidateInternet Computer canisters emit Wasm but have Candid, principal identity, update/query call modes, cycles, stable memory, async inter-canister calls, and lifecycle semantics; registry changes wait until a canister spike path is chosen
D-0152026-07-01Classify ton-tvm as a docs-first TVM/Tolk sourcegen Research candidateTON contracts target TVM with cells, TL-B serialization, message handlers, get methods, action lists, account lifecycle, and TVM gas semantics; registry changes wait until a sourcegen spike path is chosen
D-0162026-07-01Classify bch-cashscript as a docs-first UTXO script/covenant sourcegen Research candidateBitcoin Cash contracts through CashScript lock and spend UTXOs with BCH Script, transaction introspection, CashTokens, and SDK transaction-builder semantics; registry changes wait until a CashScript spike path is chosen
D-0172026-07-01Classify algorand-avm as a docs-first AVM/TEAL sourcegen Research candidateAlgorand contracts target AVM approval/clear-state or LogicSig programs with ARC-4 ABI, global/local/box storage, resource references, atomic transaction groups, inner transactions, and AVM budget semantics; registry changes wait until an Algorand package spike path is chosen
D-0182026-07-01Classify cardano-plutus-aiken as a docs-first eUTXO validator sourcegen Research candidateCardano contracts validate eUTXO spends through datum, redeemer, script context, Plutus/UPLC artifacts, execution units, Plutus blueprints, and off-chain transaction-building semantics; registry changes wait until an Aiken sourcegen spike path is chosen
D-0192026-07-01Classify tezos-michelson-ligo as a docs-first Michelson/LIGO sourcegen Research candidateTezos contracts target Michelson with typed storage, parameters, entrypoints, views/events, operation lists, big_map, tickets, Sapling, gas, and storage-burn semantics; registry changes wait until a LIGO sourcegen spike path is chosen
D-0202026-07-01Classify starknet-cairo as a docs-first Cairo/Sierra/CASM sourcegen Research candidateStarknet contracts compile through Cairo into Sierra/CASM with ABI, class hashes, declaration/deployment metadata, Starknet storage/events, account abstraction, syscalls, and L1/L2 messaging semantics; registry changes wait until a Cairo package spike path is chosen
D-0212026-07-01Classify bitcoin-script-miniscript as a docs-first Bitcoin base-layer spending-policy Research candidateBitcoin Script is intentionally limited to UTXO locking/unlocking policy with signatures, hash locks, timelocks, descriptors, Miniscript, Taproot/Tapscript, PSBT flows, and standardness/fee constraints; registry changes wait until a Miniscript/descriptor spike path is chosen
D-0222026-07-01Classify zcash-shielded as a docs-first privacy UTXO/ZK payment Research candidateZcash is Bitcoin-derived but shielded support depends on Sapling/Orchard notes, nullifiers, anchors, value-balance constraints, viewing/disclosure policy, and protocol-defined ZK proofs; registry changes wait until shielded-note capabilities and a proving/validation boundary are reviewed
D-0232026-07-01Classify aleo-leo as a docs-first Aleo ZK application sourcegen Research candidateAleo programs combine private off-chain proof execution, public on-chain finalization, encrypted records, public mappings/storage, Aleo Instructions, Aleo VM bytecode, ABI, prover/verifier artifacts, and execute/deploy transactions; registry changes wait until the proof/finalization split is reviewed
D-0242026-07-01Model Robinhood Chain as robinhood-chain-testnet, an EVM-compatible chain profile under evm, not a new compiler targetRobinhood Chain executes EVM-compatible Arbitrum Orbit L2 contracts; ProofForge’s EVM backend covers bytecode generation, while the chain profile records chain id, RPC, explorer, verifier, rollup, and deployment metadata
D-0252026-07-01Add solana-sbpf-asm as a new Solana route (direct sBPF assembly codegen) under exploration; keep solana-sbpf-linker as fallbackGenerating sBPF assembly directly from the portable IR avoids the full Lean Zig runtime linking risk; the blueshift-gg/sbpf toolchain handles assembly and linking. See RFC 0005 and design doc.
D-0262026-07-01Adopt solana-sbpf-asm as the canonical Solana route; supersede solana-sbpf-linkerThe direct-assembly route avoids Lean runtime linking risk, gives full control over compute units and stack, and mirrors the EVM/Yul pattern. solana-sbpf-linker is kept as historical reference only — codegen should target the assembly route.
D-0272026-07-01CPI and PDA effects stay in a Solana‑specific layer, not the portable IRcpiInvoke, cpiInvokeSigned, and pdaDerive are Solana‑only concepts (Solana’s account‑passing CPI + PDA derivation have no analog on EVM, Wasm, or Move). They belong in ProofForge.Backend.Solana.Effects or the Solana SDK module, gated by the crosscall.cpi and storage.pda capabilities. The portable IR (ProofForge.IR.Contract.Effect) remains chain‑neutral — new constructors only when ≥2 target families share the same semantic shape.
D-0282026-07-02User contracts target a chain-neutral Contract Intent API; the selected target resolves intents into capability plansThe default SDK surface should not reveal the destination chain. Users write portable contract intents, then --target selects the target adapter, which routes those intents to lower-level capability implementations, checks support/runtime constraints, and emits target artifacts. Capability ids remain the internal protocol used by target adapters and Target Extension SDKs; they are not the primary user-facing API.
D-0292026-07-01Adopt Rust near-sdk-rs source generation as the in-repo wasm-near v0 backendThe EmitZig/Zig host bridge sources are not present in the repository; portable IR → near-sdk-rs package → cargo wasm32 validates NEAR semantics now and preserves the Zig host-bridge path for restoration later. (Renumbered from the NEAR branch’s D-025 during the 2026-07 branch consolidation merge.)
D-0302026-07-01wasm-near v0 supports Hash map keys, .assertions.check, and .account.explicitRequired by existing MapProbe (Hash keys, assertEq) and ContextProbe (contractId) fixtures; .crosscall.invoke remains unsupported for sourcegen v0. (Renumbered from the NEAR branch’s D-026.)
D-0312026-07-01Adopt EmitWat (portable IR → Wasm AST → WAT text → wat2wasm) as the canonical Wasm-family backend; demote the Rust near-sdk-rs sourcegen to a frozen v0 stopgapEmitWat mirrors the in-repo portable-IR → Yul renderer Backend/Evm/IR.lean (used by every --emit-*-ir-yul CLI mode), not the separate LCNF-based Compiler/LCNF/EmitYul.lean. Because the portable IR already abstracts over Lean objects (u32/u64/bool/hash scalars + storage effects only), EmitWat needs no Lean runtime port, object-model boxing, or GC — avoiding both the near-sdk macro coupling of the Rust route (E0119 Borsh / missing-&self cargo-check failures) and the Lean-runtime-to-Wasm port that blocks the prior EmitZig plan. Shared layer: Compiler/Wasm/AST.lean + Printer.lean + IR→AST lowering (parallel to Compiler/Yul/AST.lean + Printer.lean); reusable validation from Backend/WasmNear/IR.lean and Backend/Evm/IR.lean. Per-chain: host imports + ABI serialization. Key spike risk: NEAR argument (de)serialization (JSON/Borsh), which the EVM backend does not face (EVM uses calldata). (Renumbered from the NEAR branch’s D-027.)
D-0322026-07-01Ratify aleo-leo Research exit design: Leo-first zk-app-sourcegen boundary, canonical capabilities for Road 1, artifact manifest schema, and leo build/leo test toolchainAleo’s proof/finalization split requires its own sourcegen family distinct from psy-dpn-style circuit sourcegen; code registry changes remain deferred until the Road 1 spike succeeds and is reviewed. (Renumbered from the Aleo branch’s D-025 during the 2026-07 branch consolidation merge.)
D-0332026-07-01Add wasm-cloudflare-workers as a Research Wasm-host targetCloudflare Workers is not a blockchain, but it shares the Wasm-host backend pattern with NEAR/CosmWasm; it validates the portable-core model by running the same verified business logic off-chain with reinterpreted capabilities. (Renumbered from the Cloudflare branch’s D-025 during the 2026-07 branch consolidation merge.)
D-0342026-07-02Adopt the tiered target portfolio (target-roadmap) and classify UTXO script targets as a separate policy familyTier gates: shared-scenario parity on evm/solana-sbpf-asm/wasm-near opens wasm-cosmwasm (D-006) and move-aptos (D-007) in parallel; Soroban/Sui/sourcegen targets open on those exits; at most one sourcegen spike active at a time. Bitcoin-family targets (bitcoin-script-miniscript, bch-cashscript, zcash-shielded, kaspa-toccata) are spending-policy generators, not contract executors: they get a policy IR (predicate tree; no storage/events/crosscall) with new policy.* capability ids and a PSBT/regtest validation lane, instead of being forced through the contract pipeline
D-0352026-07-02Current phase completion criterion: shared scenario (Counter, then ValueVault) must pass on evm, solana-sbpf-asm, and wasm-near before opening Tier-1 targetsLocks the Definition of Done for the current consolidation phase; keeps new research targets docs-only until Gate G0 is met, preventing premature registry/capability churn
D-0362026-07-02Unify allocator modeling at the IR/Target layer under one AllocatorModel (strategy/region/release), keep Solana solana.allocator.* metadata keys as the Solana-specific configuration syntax, and give EVM an explicit bump-over-scratch bindingResolves the Workstream 24 allocator-unification open question; RFC 0008 defines the triple. Persistent-state models (EVM storage, Solana accounts, NEAR storage) stay outside the allocator abstraction. Statement.release remains rejected on EVM until ownership soundness (FV-3) justifies a checked no-op
D-0372026-07-02Keep wasm-cloudflare-workers under the wasmHost target family as a Research off-chain hostIt shares the Wasm-host backend pattern (EmitWat, portable-core + host-bridge) with NEAR/CosmWasm; its off-chain status is expressed by stage (Research) and capability set rather than by a separate family. A distinct off-chain host family is deferred until more off-chain targets force a new classification
D-0382026-07-03Bind the evm target profile to the explicit bump-over-call-scratch allocator model (AllocatorConfig.evm: strategy bump, region call-scratch, release = none)Documents what EmitYul/EVM plan already do: EVM uses word-addressed transaction-scratch memory with compiler-chosen offsets and never frees. Statement.release stays rejected on EVM v0. The transition to release = noop is gated on FV-3 proving that ownership checking makes release semantically transparent (no use-after-release, no double-release) so that EVM traces remain identical to reuse-capable targets
D-0392026-07-03Accept the CLI product surface as proof-forge build|emit|check --target ID [--fixture ID] before testkit M4 binds to legacy flagsRFC 0009 defines the target-first surface, fixture registry, and legacy-flag alias/deprecation plan. The 2026-07-03 review found M1 already landed through the compatibility layer (Command/CliOptions, check, list commands, and legacy alias metadata), so this decision ratifies the surface and makes the remaining M3/M4 migration explicit rather than acting as a pre-code freeze
D-0402026-07-03Make resource budgets (EVM gas, Solana CU, NEAR gas) a required part of the Tier-0 parity gateTier-0 shared-scenario parity (D-034) must compare behavior and budgets; RFC 0010 defines optional per-step budget baselines with tolerance bands in testkit scenarios, preventing fake parity and locking in the current Solana direct-assembly CU advantage
D-0412026-07-03Adopt a portable runtime error model (assertion_id + optional user_code) and a unified ContractSpec client schemaEach target encodes the same error id in its native form (EVM revert, Solana custom error, NEAR panic payload, Psy assertion index); testkit asserts expect.error. A target-neutral ContractSpec JSON generalizes the existing Solana IDL and feeds per-chain TS clients after testkit M3
D-0422026-07-03Adopt a versioning and compatibility policy for the portable IR, artifact/deploy JSON schemas, capability ids, and the SDK/CLIIR uses major.minor where new constructors are minor and semantic changes are major; artifact/deploy schemas use integer schemaVersion with a tolerant-reader rule; capability ids are append-only; SDK/CLI follows semver-ish rules pre- and post-1.0. RFC 0012 defines the full policy
D-0432026-07-03Add an upgradePolicy intent (`immutableauthority(keyRef)governance(ref)`) and keep signing outside the compilerEach target lowers the policy honestly or rejects it at compile time; EVM v0 supports only immutable; Solana supports immutable and authority; NEAR supports immutable and authority as account-key policy. ProofForge emits unsigned transactions/manifests only; key custody stays in wallets/KMS/CI secrets. RFC 0013 defines the full lifecycle and signing boundary
D-0442026-07-03Tier-0 completion first: finish solana-sbpf-asm, evm, wasm-near (in that implementation priority) to full DoD — behavior parity and resource budgets (D-040) — before any new-chain advancementOperationalizes D-035/D-040. Until Gate G0 closes with budgets, the already-landed Aptos/CosmWasm spikes are frozen at their current M1/M2 state (no registry stage, no M3/M4, no Tier-2 start); D-045 extends that freeze through the stricter primary-chain sign-off Gate P0. The old “open Tier-1 in parallel” wording in D-034/Workstream 28 is superseded for the current phase by this completion-first rule. See target-roadmap Tier-0 completion checklist and gate-status for per-criterion status.
D-0452026-07-03Primary-chain completion covenant: product implementation priority is solana-sbpf-asmevm (Ethereum) → wasm-near (NEAR/Wasm), and those three chains must be completed to production-grade quality before any additional chain advances beyond docs-only research or frozen spike maintenanceThis is the product-level sequencing rule above individual workstreams. “Complete” means target-first build/emission, local execution or deployment smoke, artifact/deploy metadata, capability diagnostics, resource budgets, CI coverage, and maintained docs. New targets may still receive docs-first research notes, and already-landed Aptos/CosmWasm/Aleo/Psy/Cloudflare spikes may receive CI/security maintenance, but no new registry/capability/testkit/CI advancement for additional chains should land until the primary three-chain sign-off is recorded in gate-status.

Target Family Classification

FamilyTargetsBackend pattern
Direct compilerevmContractSpec / portable IR → EVM semantic plan → Yul AST/source → solc; the older Lean → LCNF → Yul path is research/equivalence only
EVM-compatible chain profilesrobinhood-chain-testnetReuse evm bytecode/ABI output; add chain id, RPC, explorer, verifier, rollup, and deployment metadata
Wasm hostwasm-near, wasm-cosmwasm, wasm-cloudflare-workers (off-chain host, D-033), wasm-stellar-soroban (candidate, docs only), wasm-icp-canister (candidate, docs only)Portable IR → EmitWat (Wasm AST → WAT) → wat2wasm + per-chain host imports; Rust/CDK sourcegen used only as a frozen v0 stopgap (D-031, wasm-family); Cloudflare Workers currently uses TypeScript sourcegen
Binary toolchainsolana-sbpf-linker, solana-zig-forkLean → EmitZig → bitcode → sbpf-linker (historical reference; superseded by D-026)
sBPF direct codegensolana-sbpf-asmLean → IR → sBPF assembly (.s) → sbpf toolchain → ELF (canonical D-026)
Source codegenmove-aptos, move-suiPortable IR → Move package source
AVM sourcegen researchalgorand-avm (candidate, docs only)Portable IR → Algorand Python, Algorand TypeScript, or TEAL package → AVM approval/clear-state or LogicSig bytecode + ARC-4/app metadata
eUTXO validator sourcegen researchcardano-plutus-aiken (candidate, docs only)Portable IR → Aiken package → UPLC/Plutus validator artifacts + Plutus blueprint + transaction scenario metadata
Michelson sourcegen researchtezos-michelson-ligo (candidate, docs only)Portable IR → LIGO package → Michelson contract + parameter/storage schema + operation/view/event manifests
Cairo sourcegen researchstarknet-cairo (candidate, docs only)Portable IR → Cairo/Scarb package → Sierra/CASM artifacts + ABI/class-hash/deployment metadata
Aleo ZK app sourcegen (zk-app-sourcegen)aleo-leo (candidate, docs only)Portable IR → Leo package → Aleo Instructions → Aleo VM bytecode + ABI/prover/verifier artifacts + execute/deploy metadata
TVM sourcegen researchton-tvm (candidate, docs only)Portable IR → Tolk or lower-level TON source → TVM/BOC artifact + TL-B/message manifests
Bitcoin script policy researchbitcoin-script-miniscript (candidate, docs only)Portable IR → policy/Miniscript/descriptor package → Script/Tapscript output + PSBT/regtest validation metadata
Privacy UTXO ZK payment researchzcash-shielded (candidate, docs only)Portable IR → shielded transaction/proving manifest → Zcash transaction with Sapling/Orchard proof bundle + zcashd/library validation metadata
UTXO script sourcegen researchbch-cashscript (candidate, docs only)Portable IR → CashScript .cash source → cashc artifact JSON + BCH transaction-builder validation
ZK circuit sourcegenpsy-dpnPortable IR → .psy package → Dargo → DPN circuit JSON
UTXO covenant researchkaspa-toccata (candidate, docs only)Portable IR → covenant/Silverscript package + transaction v1 manifest + optional proof settlement metadata

Roadmap Summary

Superseded by the tier/gate model in target-roadmap (D-034), the Tier-0 completion-first rule (D-044), and the primary-chain completion covenant (D-045). The historical phase labels below are kept only for traceability; do not use them for scheduling. The authoritative sequencing is the tier model with the primary-chain sign-off gate first (Tier 0 active → Gate P0 → Tier 1 → Gate G2 → …), with Gate status tracked in gate-status.
Phase 0: EVM baseline (done)
Phase 1: Target registry + portable IR + artifact metadata + capability errors
Phase 2: Parallel spikes — CosmWasm (wasm-cosmwasm) + Solana (solana-sbpf-linker)   [superseded: Solana is solana-sbpf-asm per D-026]
Phase 3: Move sourcegen — Aptos POC first, then Sui                                  [frozen at Aptos M1/M2 spike per D-044 until Tier-0 DoD]
Phase 3.5: Psy DPN sourcegen research spike
Research lane: Kaspa Toccata covenant/based-app target note before registry changes
Research lane: Stellar Soroban Wasm-host target note before registry changes
Research lane: Internet Computer canister target note before registry changes
Research lane: Algorand AVM/TEAL target note before registry changes
Research lane: Cardano Plutus/Aiken eUTXO target note before registry changes
Research lane: Tezos Michelson/LIGO target note before registry changes
Research lane: Starknet Cairo target note before registry changes
Research lane: Aleo Leo ZK app target note before registry changes
Research lane: TON TVM/Tolk target note before registry changes
Research lane: Bitcoin Script/Miniscript spending-policy target note before registry changes
Research lane: Zcash shielded privacy payment target note before registry changes
Research lane: Bitcoin Cash CashScript target note before registry changes
Phase 4: Cross-target shared scenario hardening   [= Gate G0, D-035/D-040/D-044]
Phase 5: Cloud platform
Detailed tasks: Implementation backlog.

Authoritative Specs

TopicDocument
Portable Contract IRportable-ir.md
Capability IDscapability-registry.md
Counter shared scenarioshared-scenario.md
Target engineering shapeRFC 0002
CosmWasm SDK spike sketchtargets/wasm-family.md
Wasm-NEAR sourcegen targettargets/wasm-near.md
Cloudflare Workers targettargets/cloudflare-workers.md
Stellar/Soroban target candidatetargets/stellar-soroban.md
Internet Computer target candidatetargets/internet-computer.md
Algorand AVM target candidatetargets/algorand-avm.md
Solana instruction manifesttargets/solana-sbf.md
Cardano Plutus/Aiken target candidatetargets/cardano-plutus-aiken.md
Tezos Michelson/LIGO target candidatetargets/tezos-michelson-ligo.md
Starknet Cairo target candidatetargets/starknet-cairo.md
Aleo Leo target candidatetargets/aleo-leo.md
TON TVM target candidatetargets/ton-tvm.md
Bitcoin Script/Miniscript target candidatetargets/bitcoin-script-miniscript.md
Zcash Shielded target candidatetargets/zcash-shielded.md
Bitcoin Cash CashScript target candidatetargets/bitcoin-cash-cashscript.md
Psy/DPN ZK targettargets/psy-dpn.md
Kaspa/Toccata target candidatetargets/kaspa-toccata.md

Superseded Positions

These earlier doc positions are no longer authoritative:
  • RFC 0001 Phase 2 = Solana only, Phase 3 = Wasm only — replaced by parallel Phase 2 spikes (D-003).
  • Milestone 3 = Solana as the single second target — replaced by parallel CosmWasm + Solana (D-003).
  • CLI id solana-sbf — use solana-sbpf-asm (D-026).
  • Move POC generates both Sui and Aptos packages at once — Aptos first (D-007).
  • D-034 “open Tier-1 (cosmwasm + aptos) in parallel after Gate G0” — for the current phase, Tier-0 completion-first (D-044) and the primary-chain completion covenant (D-045) take precedence: finish solana-sbpf-asm/evm/wasm-near to production-grade DoD before advancing any Tier-1 spike past its current state.
  • D-039’s original “no code changes until Workstream 29 M1” wording — corrected on 2026-07-03 after review found M1 already landed; RFC 0009 is accepted with M1 implemented and M3/M4 still open.
  • decisions.md “Roadmap Summary” Phase 0–5 model — superseded by the tier/gate model in target-roadmap (D-034); kept above only for traceability.