Skip to content

Latest commit

 

History

History
2208 lines (1679 loc) · 106 KB

DECISIONS.md

File metadata and controls

2208 lines (1679 loc) · 106 KB

Decisions

D044: A-12 public disclosure boundary

Date: 2026-11-17 Status: PENDING TEAM/LEGAL DECISION

Issue #132 item 13 requests suppression of surveillance details. A-12 v2's raiseFlag, markUncertain, ReviewResolved and assessmentOf expose subjects, reason/flag data and resolution through public storage, calldata and events. Reporter redaction cannot hide those records.

Until the team/legal decision is resolved, Reg D v5 (family 1/version 5) and A-12 v2 (RedFlagKnowledgeBarV2) are reference-only and non-production-activatable through supported production paths. Production onboarding validation rejects A-12-v2, Reg D v5 recipes, Manifest references and bindings before Safe export, verification or delayed-update activation preflight. ProductionCoreDeployer deploys ProductionElementRegistry, which rejects A-12-v2 through both registration overloads, preventing compilation of Reg D v5's required Element. DeployStack explicitly uses the generic registry for local reference work. Production core has no legal-policy profile or automatic Manifest activation.

The generic ElementRegistry has no production mode or allowlist. Already deployed generic registries and manually assembled deployments are not upgraded or constrained by these gates. Governance must not use them to activate these reference versions in production. ID checks do not certify arbitrary replacement implementations or aliases as legally approved.

Options requiring a team/legal decision:

  • Keep the detailed assessment implementation reference-only.
  • Move detailed records off-chain under approved access/retention controls and expose only coarse commitments through a separately reviewed version.

Neither option is selected here. Do not record real surveillance data with the reference implementation. PR #161 remains draft.

D024: Reg D v5 adopts immutable nonblocking A-12 v2 by explicit selection

Date: 2026-11-10

Context

Issue #132 item 6 calls for A-12 in the Reg D reference recipe. The legacy wave-3 script requested FLAG_ONLY for A-12-v1, whose immutable metadata declares BLOCK; the real ElementRegistry rejects that mismatch. Existing registered versions and active Manifests must retain their meanings.

Decision

  1. Add RedFlagKnowledgeBarV2 with identity A-12-v2 and matching FLAG_ONLY metadata. Preserve its nonblocking check behavior and separate assessment APIs/events. Review assessments do not populate Engine flags or create a new settlement gate.
  2. Add family 1 version 5, RegD506cRecipeV5, with V3's nine Elements in the same order followed by A-12-v2. Wave-3 registers v2 explicitly as FLAG_ONLY without activating a Recipe or migrating an asset.
  3. Require explicit ASSET_PROFILE=reg-d-v5 selection through DeployStack and matching direct-script/CLI inputs. The default stays BUIDL-like; reg-d stays v3. The full E2E launcher and Toolkit templates retain their two profiles.
  4. Local reference v3 assets adopt v5 only through a reviewed Manifest commitment, exact Recipe binding, scheduled semantic update, timelock and activation. The new policy ID invalidates prior-policy RFQ quotes at settlement. Production adoption is prohibited pending the item 13 decision in D044.

Alternatives Considered

  • Change A-12-v1 metadata or v3 membership: rejected because immutable policy identities and existing deployments must retain their reviewed behavior.
  • Turn assessments into an automatic blocking gate: deferred pending approved production review procedures and a separately specified enforcement change.

Consequences

  • Registration and activation remain separate; the additional reference profile is opt-in. An always-passing A-12 check does not establish verification adequacy.
  • Open counsel items: which red flags suspend reliance before sale, who resolves them, what evidence suffices, and whether this reference composition is suitable for an intended production policy. These questions remain unresolved.
  • Include this additive capability in a coordinated minor SDK release under docs/sdk-versioning.md; package promotion remains separate release work.

Related Files

  • src/compliance/elements/RedFlagKnowledgeBarV2.sol
  • src/compliance/recipes/RegD506cRecipeV5.sol
  • tools/deploy-wave3/DeployWave3Elements.s.sol
  • scripts/check-wave3-element-policies.sh
  • docs/compliance/recipes/R1_RegD-506c-Issuance.md
  • docs/compliance/spec-sheets/A-12_willful-blindness.spec.md

D025: Additive canonical settlement events preserve legacy consumers

Date: 2026-11-10

Context

Issue #132 item 7 needs token, policy and measured amount fields for settlement reconstruction. Existing consumers use Router Executed and RFQAdapter events; adding another event must not cause indexers to count a trade multiple times.

Decision

  1. New Router deployments emit SettlementExecutedV2 only after successful ComplianceEngine.commit. It carries execution ID, venue, token pair, the fresh pre-trade decision's policy ID and independently measured input/output in token base units. Execution ID, venue and policy ID are indexed.
  2. Preserve legacy Router/adapter events, return values and execution ID derivation. Use a private emission helper to accommodate Solidity 0.8.17's stack limit without changing compiler settings or settlement order.
  3. Use V2 as the canonical settlement record where available and legacy Executed as fallback. Select capability per deployment, or prefer V2 per execution for mixed history. Legacy/adapter logs correlate to that settlement. Deduplicate canonical logs by chain ID, transaction hash and log index.
  4. CLI decoding supports both versions. Existing immutable deployments require explicit selection of a new Router address to gain the event capability.

Alternatives Considered

  • Replace legacy events: rejected because existing indexers and CLI consumers require backward compatibility.
  • Count every Router/adapter event independently: rejected because those logs describe the same execution.

Consequences

  • The event adds reconstruction fields without identity evidence, reasons or surveillance details. It does not implement record retention.
  • Open counsel items: applicable record categories, RFQ/precheck classification, retention, legal holds and required retrievable contents. Events and hashes do not substitute for retained records; no legal applicability is decided here.
  • Coordinate future issue #139 consumers with the same canonical event selection. This additive event/CLI capability fits a minor SDK release.

Related Files

  • src/execution/ExecutionRouter.sol
  • src/libraries/Events.sol
  • services/cli/src/abi.ts
  • services/cli/src/commands.ts
  • docs/architecture/execution-routing.md
  • docs/sdk-versioning.md

D026: Complete public diagnostics remain separate from settlement authority

Date: 2026-11-10

Context

Issue #132 item 11 requests all requirement outcomes rather than only the first Engine failure. Detailed public results also need a defined disclosure boundary for sensitive checks and cannot become a second source of settlement authority.

Decision

  1. An explicitly deployed immutable ComplianceReporter binds its Registry references to the selected Engine and reads both active legs' exact compiled rules/parameters. It preserves the Engine outcome and continues through every requirement, including path alternatives and flag-only checks.
  2. Return diagnostic pass/fail, undetermined and nonapplicable results separately from engineStatus. Provider/Recipe failures make the report incomplete; callers treat unavailable reads as unavailable, without cached permission. Reports never authorize execution or replace fill-time Engine evaluation.
  3. Aggregate all versions of A-01, A-12 and F-* into one restricted outcome. Withhold per-subject outcomes, reasons, flags and claims for these families. Binding/Recipe composition, including which bindings contain restricted elements, their positions and counts, is public Registry configuration and is not hidden by the reporter. Whenever these families are present, including when nonapplicable, redact decision reasonCode, flagsBitmap and reliedClaims to prevent indirect disclosure through those fields.
  4. Export an additive typed Toolkit reader with an explicit pinned block reference and report version 1. Keep confidential enrichment in a separately controlled off-chain system. This API cannot conceal existing public storage, calldata, events, Registry composition or direct Engine/Element queries.

Alternatives Considered

  • Extend Engine short-circuit evaluation to provide all diagnostics: rejected because settlement semantics must remain stable.
  • Expose every sensitive row or redact rows alone: rejected because reasons, flags and relied-claim fields can disclose suppressed checks indirectly.

Consequences

  • A diagnostic failure can coexist with Engine permission when a path alternative or nonblocking check fails. Consumers must preserve that distinction.
  • Open counsel items: approve public fields and recipient access; confirm the restricted taxonomy and any additional aggregation/suppression; decide whether the coarse restricted result and Engine verdict suit the intended audience. SAR-related records and confidential investigation enrichment stay off-chain.
  • The reporting boundary makes no chain-wide secrecy or disclosure-approval claim. Production adoption remains explicit. Plan a coordinated minor SDK release; existing package versions and persisted schemas are not reinterpreted.

Related Files

  • src/compliance/ComplianceReporter.sol
  • src/interfaces/compliance/IComplianceReporter.sol
  • src/types/ComplianceReportTypes.sol
  • services/toolkit/src/compliance-reporting.ts
  • docs/product-specs/compliance-reporting.md
  • docs/architecture/compliance-policy.md

D027: RFQ rejection disclosure is opt-in and generic by default

Date: 2026-11-10

Context

This PR implements operational RFQ risk disclosure only. Issue #132 item 12 also requests tiered compliance outcomes; qualification, holding period, jurisdiction and other Element failures remain OPEN pending a counsel-approved taxonomy. No compliance bridge is implemented. Disclosure belongs at host presentation, independently of compliance reporting and settlement authority.

Decision

  1. The coordinator may emit only recognized operational identifiers: INVENTORY_LIMIT_EXCEEDED, RISK_LIMIT_EXCEEDED and PRICING_OUTSIDE_LIMITS. A schema-v1 JSON policy maps them to detailed, action_only or generic tiers and literal messages. Only detailed entries expose the identifier.
  2. Snapshot an optional disclosurePolicyFile at host startup, supplied directly or through the existing production bootstrap dependencies. Select no default file; the shipped policy is reference-only. Policy changes require a reviewed version and restart.
  3. Disclose only when every supplied reason is recognized and explicitly allowlisted. Unknown, malformed, unallowlisted or sensitive reasons suppress the entire response's disclosure, including policy version. Missing, oversized or invalid policy files disable disclosure. Sanctions, AML and surveillance identifiers cannot be enabled through policy edits.
  4. Preserve HTTP 422 and error: "risk_rejected", adding only optional disclosure. Never interpolate provider/internal text. Keep authentication, exact taker binding, reservation/signing, persisted quote records and idempotent replay behavior unchanged. Do not reinterpret existing schema/bootstrap versions.

Alternatives Considered

  • Return raw provider rejection messages: rejected because wording and sensitive content cannot be controlled by the disclosure policy.
  • Disclose recognized entries from a partly unknown list: rejected because the whole response requires a known, reviewed disclosure classification.
  • Enable the reference policy by default: rejected because audience and wording approval remain operator/counsel decisions.

Consequences

  • Structured complete reason lists are required; the host does not infer sensitivity from provider text. No privileged audience or reporter integration is introduced by this capability.
  • Open counsel/operator items: approve authenticated recipients for each tier, the mapping of each operational identifier and exact production wording. The reference policy does not establish sufficient disclosure or recipient access.
  • The public SDK additions fit a coordinated minor release; package publication and version promotion remain release-owner work.

Related Files

  • services/rfq/src/types.ts
  • services/rfq/src/coordinator.ts
  • services/rfq-host/src/disclosure.ts
  • services/rfq-host/src/server.ts
  • services/rfq-host/src/runtime.ts
  • services/rfq-host/policies/disclosure.v1.json
  • docs/product-specs/production-rfq-policy.md

D023 — Router commit requires independently measured exact settlement amounts

Date: 2026-10-20

Context

Compliance evaluation and quantitative limits use the amounts in ComplianceContext, while an adapter also returns a settlement result. If those values diverge, stateful accounting cannot reliably describe the transfer that actually occurred. Re-running the full Compliance Engine after settlement is not safe because some Elements intentionally inspect pre-transfer balances and canTransfer state.

Decision

The current Router execution version supports exact full fills only. It snapshots the authenticated buyer's tokenIn and tokenOut balances immediately before and after adapter execution and requires all of the following to match:

  • measured input and context.amountIn;
  • measured output and context.amountOut;
  • adapter-reported output and measured output.

Only the measured context is passed to ComplianceEngine.commit. Any mismatch reverts the complete transaction, including token transfers and nonce consumption. AMM callers therefore bind an exact output quote before execution.

Alternatives Considered

  • Trust adapter-reported output: rejected because it does not independently prove the payer/recipient balance changes.
  • Replace only amountOut during commit: rejected because the pre-trade decision would still have evaluated a different amount.
  • Re-evaluate every Element after settlement: rejected because post-transfer balances can change the meaning of checks designed for pre-transfer state.
  • Permit an output range immediately: deferred until a versioned preview or settlement-aware compliance interface can preserve pre-state semantics.

Consequences

  • RFQ exact full fills remain compatible.
  • AMM price movement away from the quoted output fails closed and must be retried with a fresh quote.
  • Fee-on-transfer/rebasing tokens are prohibited at asset onboarding and partial fills are unsupported by this version. Buyer-side deltas do not prove every intermediate settlement balance, so onboarding is the required control for non-standard token behavior rather than a universal Router detection guarantee.
  • Venue-authoritative participant, flow and affiliate provenance remains a separate production activation blocker.

Related Files

  • src/execution/ExecutionRouter.sol
  • src/execution/adapters/amm/UniswapV3Adapter.sol
  • docs/architecture/execution-routing.md
  • docs/security.md
  • GitHub issue #153

D020 — Asset-side checks follow the actual regulated-token flow

Date: 2026-09-29

Context

ComplianceContext.buyer는 심사 대상 투자자이지 항상 RWA 수령자는 아니다. 매수는 RWA가 seller -> buyer로 이동하지만 매도는 buyer -> seller로 이동한다. 기존 C-01-v1은 양 방향에서 buyer의 취득 이력만 읽었고, B-02-v1 live wiring도 항상 seller의 잔액과 buyer의 identity를 검사해 RWA 매도 방향을 잘못 해석했다. 또한 F-02-v1.setThreshold는 누구나 변경할 수 있었다.

Decision

  1. ComplianceContext.tokenIn/tokenOut과 평가 중인 regulated asset으로 실제 from/to를 결정하는 공통 AssetFlow 해석을 사용한다.
  2. RWA가 tokenOut이면 seller -> buyer, tokenIn이면 buyer -> seller로 처리하고, 어느 leg에도 없으면 fail-closed한다.
  3. C-01-v2는 실제 RWA sender의 acquisition evidence를 읽고, B-02-v2는 같은 sender/recipient 방향으로 free balance, identity와 canTransfer를 검사한다.
  4. F-02-v2 threshold 변경은 owner 또는 명시적 operator만 수행한다.
  5. D017/D019의 immutable version 원칙에 따라 v1 계약을 수정하지 않는다. 신규 reference deployment는 Reg D recipe family 1 version 3과 새 Element ID를 exact binding하며 기존 배포와 reason decode는 보존한다.
  6. 1차 발행은 재판매 보유기간에서 제외하되 호출자가 지정할 수 있는 flowType만 신뢰하지 않는다. PRIMARY_DISTRIBUTION과 Manifest 설정에 고정된 실제 RWA 송신자 주소가 모두 일치하고 RWA가 tokenOut인 최초 판매 방향일 때만 C-01-v2를 건너뛴다. 설정이 없거나 주소·방향이 다르면 일반 보유기간 검사를 그대로 수행한다.
  7. reference/demo/testnet 자산은 B-02-v2의 선언 확인만 사용하지 않고 실제 Identity Registry, Modular Compliance 및 token runtime code hash를 배포 시점에 봉인한다. 이후 배선 변경은 다음 거래에서 fail-closed한다.

Alternatives Considered

  • v1 계약을 in-place 수정: 과거 review, policy ID와 배포 의미를 소급 변경하므로 제외
  • buyer/seller 인자만 사용: regulated asset이 tokenIn인지 tokenOut인지 구분할 수 없어 매도 방향 오류가 남으므로 제외
  • venue별 분기: AMM/RFQ마다 중복되고 새 venue가 같은 오류를 반복하므로 제외
  • PRIMARY_DISTRIBUTION 표지만으로 C-01을 생략: 거래 요청자가 flow type을 지정하므로 secondary resale을 primary로 가장할 수 있어 제외
  • surveillance threshold를 owner-only로 제한: 안전하지만 운영 자동화/incident 대응의 operator plane을 불필요하게 제거하므로 owner+operator를 선택

Consequences

  • 신규 buy에서는 pool/maker 같은 실제 RWA source에도 acquisition evidence가 필요하다.
  • 신규 sell에서는 investor가 RWA sender이고 maker/pool이 identity-verified recipient여야 한다.
  • reference Anvil/testnet/CLI는 recipe v3와 B/C/F v2를 사용한다.
  • primary distributor 주소는 자산별 Manifest config와 policy ID/history에 결합된다.
  • reference/demo/testnet B-02는 live wiring drift를 체결 전에 거절한다.

Related Files

  • src/compliance/libraries/AssetFlow.sol
  • src/compliance/elements/LockupV2.sol
  • src/compliance/elements/Erc3643NativeV2.sol
  • src/compliance/elements/SurveillanceFlagV2.sol
  • src/compliance/recipes/RegD506cRecipeV3.sol

D018 — 정책 파라미터와 실행 인스턴스를 versioned commitment로 고정한다

Date: 2026-09-15

Context

자산별 정책값을 Element 구현에 하드코딩하면 같은 규칙을 상품마다 다시 배포하게 되고 Manifest governance 밖에서 의미가 달라질 수 있다. 반면 모든 규칙을 범용 DSL로 만들면 법률 의미, 타입, gas와 compiler 검증 범위가 과도하게 커진다.

Decision

ADR-010을 accepted decision으로 채택한다. 자산별 정책값은 versioned ManifestPolicyConfig가 소유하며 Manifest와 원자적으로 활성화한다. Element는 bounded parameter를 받는 하나의 ABI로 통일하고 반복 primitive만 제한적으로 정규화한다. 정책 식별자는 exact Recipe/Element/schema/parameter뿐 아니라 chain, 배포 주소와 runtime code hash를 함께 고정하며 decisionHash가 이를 참조한다.

정책 lifecycle은 온체인 event로 보존하고 상세 자료는 PII-free canonical 감사 아티팩트로 관리한다. 긴급 Element 교체는 pause 후 새 불변 version과 정상 timelock을 사용한다. production Recipe 조회는 exact recipeKey + version으로 통일하고 모호한 latest-address API를 제거한다.

Alternatives Considered

  • Element별 자산값 유지: Manifest history와 분리되므로 제외
  • 공통 ABI에 Element별 struct 노출: 새 Element마다 core 타입이 바뀌므로 제외
  • runtime code hash 또는 주소 중 하나만 고정: 코드와 배포 인스턴스를 동시에 증명하지 못하므로 제외
  • 모든 감사 자료 온체인 저장 또는 event replay만 사용: 비용·PII 또는 복원 운영 위험이 커서 온체인 이력과 PII-free 아티팩트를 결합
  • Safe break-glass와 같은-ID 구현 교체: timelock 우회와 과거 의미 변경 때문에 제외
  • 범용 정책 DSL: 현재 반복 근거에 비해 compiler·gas·감사 범위가 과도해 제외

Consequences

  • 기존 testnet 배포 ABI 호환 대신 저장소 전체를 하나의 interface로 migration한다.
  • local Anvil demo는 유지하지만 ABI/schema/latest call site를 함께 갱신해야 한다.
  • 구현은 GitHub epic #101의 하위 이슈별 feature branch와 PR로 분리한다.
  • 실제 상품값, 보관 기간, provider/Safe 운영자는 외부 승인 전 production에서 fail-closed한다.

Related Files

  • docs/decisions/ADR-010-policy-parameters-versioning-and-audit.md
  • docs/decisions/decision-register.md
  • FEATURES.md
  • PROGRESS.md
  • GitHub issues #101–#110

D010 — Configuration-driven Toolkit is the operator entry point

Date: 2026-07-22

Context

CLI 명령과 Foundry 배포 스크립트를 사용자가 각각 조합하면 자산 profile, venue, deployment artifact가 서로 어긋날 수 있고, 같은 설정을 dashboard/backend가 재사용하기 어렵다.

Decision

versioned JSON Toolkit config를 사용자 입력의 source of truth로 둔다. 초기 schema는 asset profile, deployment artifact/network, 활성 venue와 operator/investor/maker role reference를 포함하며, 공통 validator가 CLI와 이후 deployer/API/dashboard에서 재사용된다. CLI는 toolkit-init과 toolkit-validate를 제공하고, 배포 artifact의 profile과 설정이 충돌하면 fail-closed한다.

Alternatives Considered

  • CLI별 옵션과 Foundry env만 유지: 반복 입력과 profile drift를 막지 못해 제외
  • YAML을 먼저 도입: 새 parser dependency와 두 개의 설정 문법을 만들게 되어 JSON schema를 먼저 확정한 뒤 adapter로 확장하기로 함

Consequences

  • deployment/simulation/operator workflow가 동일한 설정 계약을 소비할 수 있다.
  • schema migration과 secret custody는 별도 단계로 남는다.

Related Files

  • services/toolkit/src/config.ts
  • docs/architecture/deployment-operations.md
  • FEATURES.md

D001 — Repository-managed Harness를 사용한다

Date: 2026-06-09

Context

프로젝트 상태와 다음 작업이 대화나 외부 메모에 의존하면 새 에이전트 세션이 정확한 범위와 완료 조건을 복구하기 어렵다.

Decision

다음 역할을 저장소 파일로 관리한다.

  • 진입 지침: AGENTS.md
  • 아키텍처 라우터: ARCHITECTURE.md
  • feature 상태: FEATURES.md
  • 세션 상태: PROGRESS.md
  • 결정 이유: DECISIONS.md
  • 품질 상태: QUALITY.md
  • 큰 작업 계획: docs/exec-plans/
  • 전체 검증: scripts/check.sh

Alternatives Considered

  • 대화와 외부 노트만 사용: 세션 간 복구와 검증 근거가 약해 제외
  • 모든 내용을 AGENTS.md에 작성: 진입 문서가 길어지고 중복되므로 제외

Consequences

  • 작업 전후 상태 문서 갱신 비용이 생긴다.
  • 대신 작업 범위, 결정 이유와 검증 결과가 저장소에 남는다.

Related Files

  • AGENTS.md
  • FEATURES.md
  • PROGRESS.md

D002 — 외부 제품 방향을 별도 migration feature로 반영한다

Date: 2026-06-09

Context

팀 공유 입력에는 SDK/reference DEX와 4-Layer compliance 모델을 설명하는 새 제품 방향이 있다. 기존 공식 문서와 동시에 수정하면 Harness 구조 변경과 제품 경계 변경이 섞인다.

Decision

Harness baseline에서는 당시 docs/를 공식 source of truth로 유지했다. 외부 입력 반영은 DOC-001 feature와 별도 Exec Plan에서 수행했다.

Alternatives Considered

  • Harness 작업과 아키텍처 migration을 동시에 수행: 변경 범위와 검증 기준이 혼합되어 제외

Consequences

  • HE-001 동안 당시 문서와 다음 방향 입력 자료가 함께 존재했다.
  • DOC-001에서 채택된 방향을 공식 source-of-truth에 반영하고 migration pending 상태를 종료한다.

Related Files

  • docs/exec-plans/completed/DOC-001-imported-architecture-alignment.md
  • docs/product-specs/index.md
  • FEATURES.md

D003 — SDK를 주 제품, Corner Store를 reference DEX로 정의한다

Date: 2026-06-09

Context

기존 문서는 Corner Store 자체를 multi-venue execution product로 설명했다. 팀 공유 자료는 장기 성공 기준을 제3의 DEX와 운영주체가 재사용하는 DEX-level compliance 표준과 SDK 채택으로 정의한다.

Decision

주 제품은 등록 가능한 compliance policy core와 교체 가능한 execution venue integration kit로 구성된 Solidity SDK다.

  • Compliance Core는 context, Element/Recipe/Manifest registry, evaluation과 structured decision을 제공한다.
  • Execution Integration Kit는 generic ExecutionRouter, VenueRegistry, 공통 Adapter interface와 dispatch/replay protection을 제공한다.

Corner Store DEX는 SDK에 구체 Adapter, testnet policy fixture와 배포·운영 구성을 결합해 실행 가능성을 증명하는 reference implementation이다.

Alternatives Considered

  • Corner Store DEX만 제품으로 유지: integration 재사용성과 표준화 목표를 충분히 설명하지 못해 제외
  • TypeScript client SDK를 즉시 주 제품으로 정의: 실제 소비자와 ABI가 없어 범위를 과도하게 확정하므로 제외

Consequences

  • SDK 공통 컴포넌트는 Uniswap이나 Corner Store-specific 코드에 의존하지 않는다.
  • 정책은 Element/Recipe/Manifest 등록으로, 실행 venue는 Adapter 등록으로 확장한다.
  • Uniswap v3/RFQ/Order Book의 구체 Adapter와 Corner Store 배포 구성은 reference 구현이며 SDK integrator에게 강제되지 않는다.
  • TypeScript tooling과 package 배포 형식은 실제 integration 요구가 생길 때 결정한다.

Related Files

  • docs/MVP-v2-multi-venue.md
  • docs/ROADMAP.md
  • ARCHITECTURE.md

D004 — 이름 기반 4-Layer와 cumulative multi-Recipe를 사용한다

Date: 2026-06-09

Context

기존 3-Layer 문서는 Recipe가 자산 정책과 규제 조합을 함께 담당하고, 거래당 하나의 Recipe를 선택하는 인상을 주었다. 법률 연구는 한 거래에 발행·재판매·펀드·행위 등 복수 법률효과가 동시에 적용된다는 구조를 제시했다.

Decision

거래 측 compliance를 Element, Recipe, Manifest, Operator의 이름 기반 4-Layer로 정의한다.

  • Element: 구성요건 사실
  • Recipe: 법률효과 하나
  • Manifest: 자산별 Recipe/engine/version/coverage binding
  • Operator: 판단·승인·감시

거래마다 applicable Recipe를 식별한다. Required Recipe의 Element는 cumulative AND로 평가하고, ADR-007 이후 명시적 path option과 flag-only binding을 분리한다. 기존 ExecutionRouter, ComplianceEngine과 Adapter 분리는 유지한다.

Alternatives Considered

  • 기존 Token Policy에 모든 정보를 유지: 법률 조합과 자산 binding 책임이 섞여 제외
  • 하나의 종합 Recipe 사용: 독립 법률효과의 재사용과 동시 적용을 표현하기 어려워 제외

Consequences

  • Manifest lifecycle과 multi-Recipe orchestration이 핵심 구현 phase가 된다.
  • Element 수와 production 법률 기준은 별도 승인 전 확정하지 않는다.
  • acquisition source, stateful commit hook과 reject logging은 열린 결정으로 남는다.

Related Files

  • docs/architecture/compliance-policy.md
  • docs/architecture/asset-manifest.md
  • docs/ROADMAP.md

D005 — 누락된 자산 분류는 fail-closed한다

Date: 2026-06-09

Context

연구 입력의 실행 흐름은 Manifest가 없는 일반 ERC-20에 early exit를 제안한다. 그러나 Manifest 부재만으로 자산이 비규제임을 판정하면 regulated asset의 onboarding 누락이 public path 우회로 바뀔 수 있다.

Decision

일반 ERC-20 public execution은 명시적 UNREGULATED 분류에만 허용한다. Manifest와 UNREGULATED 분류가 모두 없는 자산은 UNKNOWN으로 fail-closed한다.

ACTIVE Manifest의 invalid reference, unsupported engine 또는 version 오류도 fail-closed한다.

pair 거래에서는 tokenIn과 tokenOut을 각각 분류한다. 양쪽 모두 명시적 UNREGULATED일 때만 public pass-through를 허용하고, 하나 이상의 regulated 자산이 있으면 양쪽에서 확인된 모든 regulated Manifest를 함께 평가한다.

Alternatives Considered

  • Manifest 부재를 곧바로 public pass-through로 처리: onboarding 누락이 규제 우회가 될 수 있어 제외
  • 모든 자산을 regulated로 처리: 일반 ERC-20 integration 비용이 과도해 제외

Consequences

  • API, event와 테스트가 UNKNOWN, UNREGULATED, regulated evaluation을 구분해야 한다.
  • mixed pair와 regulated-regulated pair에서 어느 한쪽의 Manifest도 생략할 수 없다.
  • production onboarding에서 명시적 asset classification을 요구한다.
  • 기술적으로 우회 불가능한 규제 enforcement가 필요하면 별도 venue 통제가 필요하다.

Related Files

  • docs/MVP-v2-multi-venue.md
  • docs/architecture/asset-manifest.md
  • docs/security.md

D006 — Corner Store compliance 보장은 Router 경로에 한정한다

Date: 2026-06-21

Context

PR #12 이후 Corner Store 내부 실행 경로는 다음 경계를 갖는다.

  • regulated-regulated pair에서 양쪽 ACTIVE Manifest를 모두 평가한다.
  • 누락된 Recipe reference는 fail-closed한다.
  • AMM Adapter 실행은 Router-only다.
  • Router caller는 context.initiator와 일치해야 한다.

그러나 이런 보강은 Corner Store 경로를 거치는 거래에만 적용된다. 사용자가 ERC-3643 token을 직접 전송하거나, AMM pool/RFQ settlement/wrapper/custodian을 직접 사용하면 ExecutionRouter, ComplianceEngine.evaluate()와 ComplianceEngine.commit()을 우회할 수 있다.

Decision

현재 skeleton의 보안·제품 보장은 제한된 범위 모델로 정의한다.

Corner Store는 router-mediated trade에 대해 DEX-level compliance를 강제한다. Router 밖의 RWA 이동 또는 경제적 소유권 이전은 자동으로 Corner Store 4-Layer evaluation과 stateful commit()을 거치지 않는다.

Router 밖 경로는 production deployment에서 다음 중 하나로 처리해야 한다.

  • ERC-3643 token/compliance module이 핵심 제한을 직접 강제한다.
  • end user가 직접 호출할 수 없는 controlled venue/settlement로 제한한다.
  • 제품 문서와 사용자-facing 설명에서 명시적으로 out-of-scope로 선언한다.

Alternatives Considered

  • Router-exclusive model을 즉시 확정: 임의의 third-party pool과 직접 호출 가능한 venue를 기술적으로 차단하는 방식이 아직 설계되지 않아 제외한다.
  • Token-level enforcement model을 즉시 확정: ERC-3643 issuer module이 Corner Store의 모든 Recipe, cap, venue와 surveillance 요구를 대체한다는 외부 운영 계약이 없어 제외한다.
  • 모든 non-router path를 암묵적으로 안전하다고 취급: Corner Store 검사가 생략될 수 있어 제외한다.

Consequences

  • docs/security.md와 ARCHITECTURE.md는 protected path와 non-protected path를 명시해야 한다.
  • RFQ/Order Book settlement와 future Adapter는 Router-only authorization 또는 동등한 호출자 제한을 merge 조건으로 가져야 한다.
  • 직접 ERC-3643 transfer, 직접 venue call, wrapper/vault/custodian과 offchain beneficial ownership transfer는 별도 제한·위임·out-of-scope 결정 전까지 Corner Store 보장으로 표현하지 않는다.
  • Stateful surveillance는 Router 경로에서만 완전성을 주장할 수 있다.

Related Files

  • docs/security.md
  • ARCHITECTURE.md
  • docs/architecture/execution-routing.md

D007 — PD-1~PD-7 Phase 1 architecture baseline을 확정한다

Date: 2026-07-14

Context

Phase 1 구현 전에 Manifest schema, Recipe evaluation, post-trade state, identity claim, enforcement action, governance와 lifecycle record 보존 방식에 대한 개발팀 합의가 필요했다.

이 결정들은 BUIDL-like demo나 RFQ/API 구현보다 상위의 아키텍처 baseline이다.

Decision

PD-1~PD-7을 Phase 1 architecture baseline으로 확정한다.

  • PD-1: Manifest는 explicit core + registry-backed RecipeBinding 구조를 사용한다.
  • PD-2: Router/Engine은 Manifest-level multi-Recipe binding 모델을 사용한다.
  • PD-3: token transfer 기준 acquisition timestamp와 router execution context를 분리하고, post-trade commit은 idempotent하게 처리한다.
  • PD-4: investor qualification은 ERC-3643/ONCHAINID claim pipeline을 기본 인터페이스로 사용하고, Securitize/TA는 adapter boundary로 연동한다.
  • PD-5: BLOCK, FLAG_ONLY, OPERATOR_REVIEW 중심의 enforcement action 모델과 constrained override를 사용한다.
  • PD-6: governance authority는 외부 Safe-style multisig를 사용하고, compliance relaxation은 timelock을 요구한다.
  • PD-7: Manifest lifecycle은 semantic versioning, append-only history, central pause state와 hash-anchored record preservation을 사용한다.

Alternatives Considered

  • PD별 ADR을 7개로 분리: 현재 결정들이 하나의 Phase 1 구조 freeze를 구성하므로 단일 baseline ADR로 묶는 편이 리뷰와 추적에 더 적합해 보류한다.
  • 현행 issuanceRecipeId + fundRecipeId 구조 유지: BUIDL-like demo에는 충분하지만 future policy 조합과 path option을 표현하기 어려워 transitional 구조로만 남긴다.
  • Corner Store 전용 identity model 신설: ERC-3643/T-REX와 ONCHAINID 호환성을 해치고 TA/KYC provider 연동성이 떨어져 제외한다.

Consequences

  • PD-1~PD-7은 더 이상 열린 구조 질문이 아니며, 후속 작업은 구현 명세와 migration issue로 진행한다.
  • 현재 코드의 transitional 구조는 별도 implementation branch에서 RecipeBinding[], compiled plan, lifecycle registry 등으로 이전해야 한다.
  • 실제 Securitize/TA 연동은 공식/current interface 확인 후 별도 refinement issue에서 처리한다.

Related Files

  • docs/decisions/ADR-007-pd-architecture-decisions.md
  • docs/decisions/decision-register.md
  • docs/architecture/phase1-structural-decisions-proposed.md

D008 — RFQ v2 hardening: maker approval, full-fill, non-custodial, nonce-scoped cancel

Date: 2026-07-04

Context

RFQ v1(RFQ-001)은 EIP-712 signed quote와 router-only settlement를 확정했으나 dealer approval, signer custody, quote cancellation, partial fill을 열린 항목으로 남겼다(docs/security.md RFQ Safety, D006 protected-path 경계). v2 hardening에서 maker approval gate와 maker-initiated cancellation을 구현하면서 이들 항목의 범위와 정책을 확정할 필요가 있다.

Decision

RFQ venue의 다음 정책을 확정한다.

  • maker approval은 adapter-local하며 operator가 관리한다(RFQAdapter.approvedMaker, setMakerApproved onlyOperator). 여러 quote-driven venue가 공유하는 dealer registry는 두 번째 quote-driven venue가 생길 때까지 도입하지 않는다.
  • fill 정책은 full-fill을 유지한다. compliance 판정은 평가된 정확한 amount에 바인딩되며, partial fill은 아직 설계되지 않은 per-fill 재평가 semantics를 요구하므로 채택하지 않는다.
  • custody는 non-custodial을 유지한다. settlement는 두 개의 safeTransferFrom leg로 수행하며, adapter는 자산을 보관하지 않는다. custodial RFQ variant는 범위 밖이다.
  • cancellation은 nonce-scoped이며 idempotent하다. usedQuoteNonce fill guard를 재사용하여 cancel과 fill이 같은 nonce namespace를 공유한다. cancel-vs-fill race는 먼저 채굴된 transaction으로 해소된다.

Alternatives Considered

  • 공유 dealer registry를 즉시 도입: 두 번째 quote-driven venue가 없어 abstraction을 과도하게 확정하므로 제외
  • partial fill 지원: compliance 판정과 amount binding, per-fill 재평가 semantics가 미설계여서 제외
  • custodial settlement: 자산 보관 위험과 별도 신뢰 가정이 필요해 reference 범위 밖으로 제외
  • cancel을 revert 기반 또는 별도 mapping으로 구현: fill guard와 상태를 이중화하고 race semantics를 복잡하게 만들어 제외

Consequences

  • maker off-boarding은 operator의 setMakerApproved(maker, false)로 처리한다.
  • signer key custody와 operator key management(multisig/HSM/rotation)은 여전히 open decision이며 production hardening에서 확정한다.
  • partial fill과 dealer inventory risk는 별도 feature spec 전까지 비활성이다.
  • 위협 모델은 docs/rfq-threat-model.md가 source of truth다.

Related Files

  • docs/rfq-threat-model.md
  • docs/security.md
  • src/execution/adapters/rfq/RFQAdapter.sol
  • FEATURES.md

D009 — Reg D 506(c) recipe를 9-element reference set으로 확장한다

Date: 2026-07-04

Context

reference Reg D 506(c) set을 향한 compliance module buildout이 최우선 작업이다. strategy report note-14는 Reg D 506(c) 판정을 9개 element로 분해한다. 기존 RegD506cRecipe는 illustrative 2-element(A-01 sanctions + A-03 accredited)만 요구했다. 나머지 element와 recipe 확장을 landing하면서, 열린 legal 결정과 production data source는 여전히 approval-gated로 남겨야 한다(ROADMAP Phase 1: "implemented for illustrative/reference Elements and Recipes; production legal criteria remain approval-gated").

Decision

  • 6개의 새 illustrative element를 추가한다(note-14 Reg D 506(c) set의 adapter): Jurisdiction(A-02), IdentityUniqueness(A-04), UsTaxResident(A-05), AssetClassification(B-01, bytes32 requiredClassification 생성자 인자), Erc3643Native(B-02), FormDFiling(E-01). attestation setter는 모두 operator-gated(Governed/onlyOperator)이며, production data source (OFAC oracle, ONCHAINID claim, ERC-165 introspection, EDGAR)는 approval-gated seam으로 남는다.
  • RegD506cRecipe를 in-place로 9-element set으로 확장한다(순서: A-01, A-02, A-03, A-04, A-05, B-01, B-02, C-01, E-01). recipe id는 1 유지, version은 2로 bump, 여전히 always-applicable. 이는 illustrative reference wiring이며 approved production policy가 아니다(ROADMAP/MVP-v2 gating 언어를 따른다).
  • C-01 Lockup은 test fixture에서 injected mock acquisition source (IAcquisitionSource)를 통해서만 참여한다. production acquisition/lot data source 결정과 holding-period 활성화 default는 변경하지 않는다(CR-3 seam, ROADMAP: "acquisition data가 필요한 Recipe는 data source가 결정되기 전 활성화하지 않는다"). recipe는 illustrative fixture로 남는다.

Alternatives Considered

  • 새 element에 ungated setter를 사용(legacy mock element와 동일): state-input write-gate가 없어 hardening 방향과 어긋나므로 제외. 대신 새 element는 Governed/onlyOperator를 쓴다(legacy element와의 divergence).
  • Lockup을 recipe에서 제외: 9-element reference set을 완전히 wiring하지 못하므로 제외. mock acquisition source로 fixture에서만 활성화한다.
  • production data source(OFAC/ONCHAINID/ERC-165/EDGAR)를 지금 연결: legal 검토와 data source 결정이 미완이라 제외. approval-gated seam으로 남긴다.

Consequences

  • ungated legacy mock element(Sanctions A-01, AccreditedInvestor A-03, QualifiedPurchaser)와 새 operator-gated element 사이에 hardening divergence가 생긴다. legacy element 정렬은 follow-up으로 추적한다.
  • RegD506cRecipe(id 1)를 issuance recipe로 쓰는 모든 fixture(unit Engine.t.sol, 통합 IntegrationBase/SwapFlow)는 9개 element를 모두 만족하도록 buyer/asset attestation을 추가해야 했다(fix fixtures, not product code). engine/registry/router product code는 변경하지 않았다.
  • production 활성화 전 legal 검토, acquisition/lot data source 결정, production data source 연결은 여전히 open이다.

Related Files

  • src/compliance/recipes/RegD506cRecipe.sol
  • src/compliance/elements/Jurisdiction.sol, src/compliance/elements/IdentityUniqueness.sol, src/compliance/elements/UsTaxResident.sol, src/compliance/elements/AssetClassification.sol, src/compliance/elements/Erc3643Native.sol, src/compliance/elements/FormDFiling.sol, src/compliance/elements/Lockup.sol
  • test/integration/IntegrationBase.sol, test/integration/AmmReferenceElements.t.sol
  • test/unit/compliance/Recipes.t.sol, test/unit/compliance/Engine.t.sol
  • docs/ROADMAP.md

D010 — Manifest lifecycle를 validated state machine로 만들고 engine을 default-deny로 닫는다

Date: 2026-07-04

Context

MVP-v2 §5는 asset Manifest에 explicit operator approval step을 포함한 full lifecycle을 요구한다. 기존 TokenPolicyRegistry는 임의 상태를 덮어쓰는 raw setStatus만 제공했고(승인 단계 없음), ComplianceEngine.evaluate는 SUSPENDED와 UNKNOWN만 명시적으로 reject한 뒤 나머지를 _evaluateActivePair로 흘려보냈다. 이 구조에 PROPOSED/RETIRED 상태를 추가하면 두 개의 fail-open 구멍이 생긴다: (a) PROPOSED/RETIRED 자산이 UNREGULATED와 pair되면 element가 0개 수집되어 allowed = true, (b) PROPOSED/RETIRED가 ACTIVE와 pair되면 ACTIVE side만 검증되고 거래가 통과한다.

Decision

1. Lifecycle state machine (states/transitions). Manifest는 아래 transition만 허용하는 명시적 state machine을 따른다. 그 외 모든 (state, action)은 dedicated custom error Errors.InvalidManifestTransition으로 revert한다.

From Action To Gate
UNKNOWN 또는 RETIRED registerManifest PROPOSED onlyOwner
PROPOSED approveManifest ACTIVE onlyOperator (issuance recipe 필수)
ACTIVE suspendManifest(reasonCode) SUSPENDED onlyOperator
SUSPENDED scheduleManifestResume 후 resumeManifest ACTIVE owner schedule + timelock + operator execute
ACTIVE 또는 SUSPENDED retireManifest(reasonCode) RETIRED (terminal) onlyOperator
UNKNOWN setUnregulated UNREGULATED onlyOwner
UNREGULATED clearUnregulated UNKNOWN onlyOwner

registerManifest는 caller가 넣은 m.status를 무시하고 항상 PROPOSED로 착지하며 declaredBy = msg.sender를 기록한다. approveManifest는 approvedBy = msg.sender를 기록한다. MANIFEST-002 이후 completeness floor는 deprecated issuance field가 아니라 비어 있지 않고 최소 하나의 blocking/path gate가 있는 validated RecipeBinding[]다. RETIRED는 terminal이며 재발행은 RETIRED→register→approve 경로로만 가능하다. gating model: owner가 자산을 classify/declare(register/setUnregulated/clearUnregulated)하고, operator가 approve/suspend/retire와 예약된 resume 실행을 구동한다. resume 예약과 semantic update 예약은 D011에 따라 owner governance가 담당한다.

2. Enum-append storage rationale. PolicyStatus에 PROPOSED(4)와 RETIRED(5)를 SUSPENDED(3) 뒤에 APPEND한다. 기존 numeric value(UNKNOWN=0, UNREGULATED=1, ACTIVE=2, SUSPENDED=3)는 storage layout과 enum↔uint cast에서 load-bearing이므로 절대 재정렬하지 않는다. 그 결과 enum의 numeric order는 lifecycle graph의 semantic order와 일치하지 않는다(type 파일에 명시적 주석). UNKNOWN=0을 유지하는 것은 absent manifest가 fail-closed default가 되도록 하는 핵심이다.

3. setStatus 제거. raw setStatus overwrite는 제거한다(pre-production breaking change; 모든 caller/test/factory를 이 feature에서 갱신). validation 없는 상태 덮어쓰기는 approval step과 transition guard를 우회하므로 유지할 수 없다.

4. Engine default-deny 재구조화 (positive allowlist). evaluate의 enumerated bad-status 검사(SUSPENDED/UNKNOWN reject)를 side별 positive allowlist로 교체한다: 각 side는 UNREGULATED 또는 ACTIVE여야 하며, 그 외(UNKNOWN/SUSPENDED/PROPOSED/ RETIRED와 미래에 추가될 모든 member)는 fail-closed한다. bad state를 열거하는 대신 permitted state를 열거하는 이유: reject list에 새 상태를 추가하는 것을 잊으면 그대로 fail-open이 되지만, allowlist는 새로 추가된 상태를 default로 거부하므로 "append-only 안전"하다. both-UNREGULATED fast-path pass-through는 유지한다. commit은 router가 evaluate를 먼저 호출하고 reject 시 revert하므로 rejected pair에서 도달 불가능하다 — mirror guard가 필요 없고, in-file 주석으로 이유를 남긴다(재구조화하지 않음).

5. clearUnregulated correction path. 잘못 UNREGULATED로 tag된 token을 UNKNOWN(clean slate)으로 되돌려 이후 regulated manifest로 register할 수 있게 한다. onlyOwner이며 UNREGULATED가 아닌 상태에서 호출하면 InvalidManifestTransition. setUnregulated와 대칭인 governance classification 호출이다.

6. declaredBy = msg.sender semantics와 factory consequence. register는 declaredBy = msg.sender, approve는 approvedBy = msg.sender를 기록한다. CornerStoreFactory.registerRWAToken은 register→approve를 한 governed call에서 연속 실행하며 factory가 registry의 owner이자 approving operator다(배포 시 governance가 registry ownership을 factory로 이전). 그 결과 이 경로로 onboarding된 token의 declaredBy/approvedBy는 factory 주소이며, attribution은 factory 경계에서 멈춘다.

Alternatives Considered

  • Engine에서 reject list(bad state 열거) 유지: PolicyStatus에 member를 추가할 때마다 reject list 갱신을 잊으면 fail-open이 되므로 제외. positive allowlist는 구조적으로 fail-closed default를 보장한다.
  • enum member를 semantic order로 재정렬: storage layout과 enum↔uint cast가 깨지므로 제외. append-only만 허용한다.
  • setStatus를 deprecated로 유지: validation 우회 경로가 남으므로 제외 (pre-production이라 breaking removal 비용이 낮다).
  • PROPOSED/RETIRED에 UNKNOWN/SUSPENDED와 다른 별도 reason-code family 부여: 기존 _rejectPolicy가 이미 uint32(status)를 reason code에 인코딩하므로 side의 실제 status를 그대로 넘기면 distinct code가 자동으로 나온다 — 추가 scheme 불필요.

Consequences

  • 모든 onboarding은 propose→approve 2단계를 거친다(factory는 한 call에서 collapse).
  • ACTIVE manifest의 issuance recipe re-point는 retire→register→approve 경로를 써야 한다(ACTIVE 위 re-register는 illegal).
  • engine은 미래에 PolicyStatus member가 추가되어도 default로 fail-closed한다.
  • fixture는 register→approve(및 UNREGULATED는 setUnregulated)로 통일된다.

Related Files

  • src/types/ComplianceTypes.sol (enum append + 주석)
  • src/registry/TokenPolicyRegistry.sol, src/interfaces/compliance/ITokenPolicyRegistry.sol
  • src/compliance/ComplianceEngine.sol (evaluate default-deny gate)
  • src/factory/CornerStoreFactory.sol (register+approve, natspec)
  • test/unit/compliance/Engine.t.sol, test/unit/registry/TokenPolicyRegistry.t.sol
  • test/integration/EmergencyPause.t.sol, test/integration/IntegrationBase.sol, test/integration/Surveillance.t.sol

D011 — 위험 중단은 즉시, 재개와 Manifest 의미 변경은 timelock으로 분리한다

Date: 2026-07-22

Context

ADR-007은 모든 Router가 공유하는 central pause state, 즉시 containment, 지연된 compliance relaxation, Manifest semantic version/history 보존을 요구한다. 기존 reference stack은 venue suspension과 Manifest status만 있어 global/asset pause가 없었고, 재개와 core fact 변경을 즉시 수행할 수 있었다. 배포 후 TokenPolicyRegistry.owner()가 Factory가 되므로 owner-only governance 호출을 EOA가 직접 실행할 수도 없었다.

Decision

  1. OperatorRegistry를 global/asset/venue pause의 source of truth로 사용하고 Router는 nonce 소비와 compliance evaluation 전에 세 범위를 모두 fail-closed로 검사한다.
  2. operator는 pause와 Manifest suspend처럼 위험을 줄이는 동작을 즉시 수행한다. unpause는 owner가 예약하고 최소 1일 뒤 owner가 실행한다.
  3. Manifest resume와 ACTIVE/SUSPENDED semantic update도 owner 예약과 최소 1일 timelock을 요구한다. update activation은 version을 증가시키며 기존 SUSPENDED 상태를 해제하지 않는다.
  4. Manifest version, current hash, chained history hash와 pause history hash를 보존하고 actor, old/new, reason, effective time을 append-only event로 남긴다.
  5. 배포 후 registry owner인 CornerStoreFactory가 resume/update schedule/cancel을 forwarding한다. Factory owner는 production에서 외부 Safe-style governance다. registry operator는 delay가 지난 동작의 실행과 즉시 tightening을 담당한다.

Consequences

  • 사고 containment는 timelock 없이 가능하지만 재개는 같은 actor가 즉시 우회할 수 없다.
  • Factory ownership wiring을 유지하면서 governance 호출이 실제 배포에서도 도달 가능하다.
  • chain별 delay, 실제 Safe provider, issuer-level disable과 RecipeBinding migration은 후속 production 설정/feature다.

Related Files

  • src/registry/OperatorRegistry.sol
  • src/registry/TokenPolicyRegistry.sol
  • src/execution/ExecutionRouter.sol
  • src/factory/CornerStoreFactory.sol
  • test/integration/EmergencyPause.t.sol
  • scripts/e2e-anvil.sh

D012 — 취득 lot와 거절·감시 상태는 provider-neutral off-chain 계층으로 수렴한다

Date: 2026-07-22

Context

ADR-008은 acquisition source, person-group state, reject logging과 Router 밖 transfer 감시를 하나의 off-chain compliance data layer로 결정했다. 기존 Lockup은 만료나 lineage 상태 없이 단일 timestamp만 읽었고, 실제 provider 계약이 없다는 이유로 현재 문서에는 해당 결정을 여전히 open으로 표시한 곳이 남아 있었다.

Decision

  1. Transfer Agent별 API는 TransferAgentProvider adapter 뒤에 둔다. Corner Store core는 Securitize 전용 undocumented field를 하드코딩하지 않는다.
  2. per-lot 입력은 acquisition date, payment completion, source type과 lineage를 검증한다. 단일 holder×asset 온체인 snapshot은 lot 선택을 과대 추정하지 않도록 현재 lot 중 가장 늦은 유효 clock을 사용한다.
  3. 온체인 AttestedAcquisitionSource에는 clock, observation/expiry, PII-free source hash와 status만 저장한다. missing, broken lineage, stale과 immature는 Lockup에서 서로 다른 reason으로 fail-closed한다.
  4. person-group volume/holder state는 execution id로 idempotent하게 commit한다. 동일 id+동일 내용은 no-op, 동일 id+다른 내용은 충돌로 거부한다.
  5. rejected attempt와 Router 밖 transfer finding은 off-chain hash-chain audit record로 보존한다. 이 local SDK는 tamper evidence를 제공하지만 production WORM, retention 또는 SAR 시스템이라고 주장하지 않는다.

Consequences

  • mock TA로 전체 경계를 테스트할 수 있으나 실제 Securitize compatibility는 공식 API 계약과 provider 인증을 확인하기 전까지 미구현이다.
  • 보수적인 latest-lot clock은 안전하지만 일부 mature lot 매도를 과도하게 막을 수 있다. amount-specific lot allocation/FIFO는 provider 계약이 확정될 때 별도 versioned adapter로 추가한다.
  • PII, 원본 lot 문서와 감사 원장은 온체인에 저장하지 않는다.

Related Files

  • docs/decisions/ADR-008-compliance-seam-decisions.md
  • services/compliance-data/
  • src/registry/AttestedAcquisitionSource.sol
  • src/compliance/elements/Lockup.sol

D013 — Stateful commit은 regulated token 위치에서 실제 이동 방향을 유도한다

Date: 2026-07-29

Context

ctx.buyer와 ctx.seller는 엔진의 검증 대상/상대방 역할이다. RFQ 매도처럼 검증 대상 taker가 RWA를 tokenIn으로 보내는 거래에서도 taker를 buyer 역할에 유지한다. 기존 commit은 항상 seller → buyer로 기록해 실제 tokenIn 이동과 반대였다.

Decision

stateful element의 onTransfer 방향은 regulated token 위치에서 결정한다.

  • regulated token이 tokenOut: seller → buyer, amountOut
  • regulated token이 tokenIn: buyer → seller, amountIn

pre-trade element의 검증 대상 역할과 post-trade 자산 이동 방향을 분리한다.

Consequences

  • RFQ/AMM 매도에서 holder count, surveillance와 후속 stateful element가 실제 RWA 이동 방향을 받는다.
  • buyer/seller 명칭만 보고 실제 token sender/recipient를 추론하면 안 된다.

Related Files

  • src/compliance/ComplianceEngine.sol
  • test/unit/compliance/Engine.t.sol
  • docs/architecture/SKELETON_GUIDE.md

D014 — RFQ 모듈 의미와 통합·배포 표현을 분리한다

Date: 2026-07-29

Context

RFQ SDK의 pricing, risk, signer와 nonce seam은 교체 가능했지만 integrator가 reference demo backend나 저장소 전체 구조를 채택하지 않고 해당 계약을 선택·검증· scaffold하는 공통 표면이 없었다.

Decision

  1. services/rfq가 versioned module capability와 공통 conformance 의미를 소유한다.
  2. services/toolkit은 module ID와 environment variable 이름만 가진 별도 integration manifest와 secret-free generator를 소유한다.
  3. services/cli는 reference service 또는 existing-backend scaffold를 rendering할 뿐 pricing, risk나 compliance 결정을 추가하지 않는다.
  4. services/rfq-demo-backend는 같은 module contract를 사용하는 reference consumer로 유지한다.
  5. Docker Compose는 선택형 export이며 Corner Store SDK의 필수 runtime이 아니다.

Consequences

  • integrator는 필요한 RFQ module만 교체하고 기존 backend에 SDK를 삽입할 수 있다.
  • conformance는 인터페이스 호환성을 증명하지만 production pricing, signer custody, nonce durability, risk 또는 법률 적합성을 인증하지 않는다.
  • module config 값과 secret은 manifest나 generated source에 기록하지 않는다.

Related Files

  • services/rfq/src/modules.ts
  • services/rfq/src/conformance.ts
  • services/toolkit/src/integration.ts
  • services/toolkit/src/scaffold.ts
  • docs/sdk-integration.md

D015 — Production RFQ v1은 non-custodial exact full-fill로 유지한다

Date: 2026-07-30

Context

RFQ v1과 SDK-001은 protected settlement와 교체 가능한 backend module을 제공하지만 production custody, signer rotation, durable nonce, pricing/inventory risk와 partial fill 책임은 열려 있었다. 현재 Adapter는 maker inventory account와 ECDSA signer를 동일 주소로 결합하고 Router의 finite maxAmount도 결제자산 amountIn 축만 검사하므로 그대로 production 경계로 간주할 수 없다.

Decision

  1. production RFQ v1은 protocol non-custodial, atomic exact full-fill을 유지한다. 잔량은 새 quote로 처리하고 partial fill은 새 quote/adapter version으로 분리한다.
  2. maker settlement account와 quote signer를 분리한다. production Adapter는 ECDSA delegate/ERC-1271을 수용하는 versioned maker-authorizer를 fill 시점에 검사한다. signer 추가는 governed/delayed, revoke는 즉시 가능하다.
  3. production nonce는 (chainId, adapter, maker) scope에서 atomic monotonic하게 할당하고 idempotency key와 request hash를 durable하게 저장한다. 예약한 nonce는 장애가 나도 재사용하지 않는다.
  4. pricing/inventory risk는 operator-owned off-chain module이며 stale/missing dependency에서 fail-closed한다. Router의 최신 compliance가 최종 gate다.
  5. compliance maxAmount는 regulated asset quantity에 적용한다. finite cap 활성화 전에 buy/sell 방향에 맞게 Router를 수정한다.
  6. production endpoint는 auth, TLS, rate limit, PII-free audit와 incident reconciliation을 요구한다. Corner Store conformance는 운영·법률 인증이 아니다.

Consequences

  • current exact full-fill quote schema와 non-custodial transfer 원자성은 유지된다.
  • signer authorization, regulated amount cap, durable nonce와 production middleware는 독립 구현 feature로 분리된다.
  • 특정 dealer/custodian/KMS/database vendor와 인허가 적합성은 operator 선택 및 별도 검토로 남는다.

Related Files

  • docs/decisions/ADR-009-production-rfq-policy.md
  • docs/product-specs/production-rfq-policy.md
  • src/execution/adapters/rfq/RFQAdapter.sol
  • src/execution/ExecutionRouter.sol
  • services/rfq/

D016 — Production deployment uses external signer and staged activation

Date: 2026-07-31

Context

Deployment Studio and toolkit-deploy provide local/demo configuration, dry-run and Anvil broadcast paths. Treating that browser-controlled path as production deployment would blur demo fixtures, production ERC-3643 onboarding, legal approval, signer custody and Safe governance.

Decision

Production deployment is a separate operations workflow:

  1. ERC-3643 token and ONCHAINID onboarding evidence is verified as an external issuer trust boundary before Corner Store activation.
  2. Governance authority is verified by Safe proxy address, runtime code hash, expected singleton/mastercopy, owner count M, threshold N, owner list, chain ID, payload target addresses and calldata before signing.
  3. Production signing uses an external signer or Safe-style multisig boundary. Browser applications do not hold production keys and do not broadcast mainnet/production transactions.
  4. Element, Recipe and Asset Compliance Manifest activation requires a legal-approved package. Demo profiles, fixture identities and illustrative recipes are not production approval evidence.
  5. Venue, maker, signer and inventory activation happens only after dry-run, fork simulation, multisig review, bytecode/role/Manifest verification and monitoring readiness.
  6. CLI production broadcast requires a frozen evidence file bound to the current config hash, source commit, successful dry-run and target-chain fork simulation.

Alternatives Considered

  • Extend Deployment Studio into a production broadcaster: rejected because it would put key custody and mainnet mutation behind a browser/local demo control surface.
  • Treat demo scenario and illustrative recipe data as production activation evidence: rejected because legal approval, issuer onboarding and production data-source contracts are separate trust boundaries.
  • Skip Safe owner/threshold verification and rely on an address label: rejected because governance authority depends on the exact owner set, threshold, chain and payload.

Consequences

  • Production deployment docs are separate from local/demo runbooks.
  • Browser UI may support review and evidence display, but not production broadcast.
  • Repository tooling may pass without claiming any deployment transaction or Safe proposal succeeded on a production network.
  • Actual Safe provider, custody vendor, RPC/finality policy and legal approval references remain deployment-specific inputs.

Related Files

  • docs/deployment-production.md
  • docs/architecture/deployment-operations.md
  • docs/deployment-studio.md
  • FEATURES.md
  • PROGRESS.md

D017 — Compliance Core uses immutable versioned policy objects and compiled enforcement

Date: 2026-08-23

Context

Production asset onboarding needs stable references to legal-approved Elements, Recipes and Manifest bindings. Mutable registry overwrites, ambiguous aliases, trade-time override resolution or fabricated generic reason codes would make Safe review and post-deployment reconciliation unreliable.

Decision

  1. Element registration is immutable for a given bytes32 elementId. The registry stores the implementation, metadata hash, version hash and default enforcement action at registration time.
  2. Recipe registration is immutable per (recipeKey, version). The canonical recipeKey is derived as keccak256(abi.encode(RECIPE_KEY_DOMAIN, aliasHash)), where RECIPE_KEY_DOMAIN = keccak256("corner-store.recipe-key.v1") and Toolkit aliases are ASCII-normalized before hashing. The canonical recipe family is bijective with its legacy numeric recipeId: neither recipeId -> recipeKey nor recipeKey -> recipeId may be rebound, and all later versions under the same key continue to use the first registered recipeId.
  3. TokenPolicyRegistry compiles Element rules when a Manifest is registered or semantically updated. Runtime evaluation consumes the compiled binding plan and does not perform unbounded alias or override resolution.
  4. Normal onboarding may only strengthen enforcement (FLAG_ONLY < OPERATOR_REVIEW < BLOCK). FORCE_FLAG_ONLY is not a downgrade escape hatch; it is valid only when the Element's immutable default is already FLAG_ONLY.
  5. Compliance rejection should preserve an Element's exact nonzero reason code. Recipe-scoped code 1 is retained only as a fallback for Elements that return bytes32(0) on failure.
  6. Production Toolkit/CLI v2 onboarding exports canonical alias/key commitments, compiled plan hashes and bounded override calldata, while legacy v1 input and numeric recipeId compatibility remain accepted for existing demos.

Alternatives Considered

  • Mutable in-place Element or Recipe updates: rejected because reviewed Safe payloads and signed quotes could silently point at different policy code.
  • Use raw human-readable aliases in runtime paths: rejected because normalization and collision handling must be resolved before activation.
  • Permit downgrade overrides during normal onboarding: rejected because a token onboarding file should not weaken a legal-approved Element default outside a separate governance process.
  • Always report recipe-scoped generic code 1: rejected because Elements already expose more precise rejection taxonomies needed for audit and operator support.

Consequences

  • New production onboarding should use v2 alias/key and compiled-plan fields.
  • Existing local Anvil/demo v1 configs continue to work through legacy numeric aliases, but v1 artifacts are compatibility inputs, not production approval.
  • Legal approval, ERC-3643/ONCHAINID issuer wiring and TA/KYC provider evidence remain external trust boundaries; compiled plan hashes prove only technical binding consistency.

Related Files

  • src/registry/ElementRegistry.sol
  • src/registry/RecipeRegistry.sol
  • src/registry/TokenPolicyRegistry.sol
  • src/compliance/ComplianceEngine.sol
  • services/toolkit/src/production-onboarding.ts
  • services/cli/src/commands.ts
  • docs/architecture/asset-manifest.md
  • docs/architecture/compliance-policy.md

D018 — Policy audit reuses the Manifest commitment and records a derived checkpoint

Date: 2026-09-22

Context

온체인 policy history만으로는 provider evidence, Element parameter와 reviewed deployment package 원문을 복원할 수 없다. 반대로 모든 자료를 온체인에 저장하면 PII 노출, 비용과 vendor-specific retention 책임이 protocol에 들어온다. 별도 mutable audit registry는 현재 EIP-170 margin이 작은 Registry를 키우고 Manifest와 감사 commitment가 서로 다르게 갱신될 위험도 만든다.

Decision

  1. domain-separated canonical JSON의 SHA-256 digest를 production onboarding schema v4의 ManifestCore.fullManifestHash로 사용한다.
  2. 원문은 PolicyAuditStore port 뒤의 operator-owned immutable store에 보관한다. 저장 전후 hash를 재검증하며 SDK의 local adapter는 reference 구현일 뿐 production WORM/retention 보장을 주장하지 않는다.
  3. artifact는 config/legal/compiled plan, exact binding/override, Element/Recipe, deployment runtime code hash와 PII-free provider evidence reference를 포함한다.
  4. 최종 policyId는 artifact digest를 포함해 계산되므로 artifact 내부에 넣지 않는다. Manifest 승인 후 permissionless Engine checkpoint event가 final policyId, version, artifact digest, status와 history hash를 연결한다.
  5. schema v4 plan은 저장된 artifact 전체가 onboarding config와 일치해야만 생성되고, checkpoint 이후에만 venue/maker activation으로 진행한다. lifecycle mutation 뒤에도 운영자가 checkpoint를 기록하고 reconciliation한다.

Alternatives Considered

  • 모든 감사 데이터를 온체인에 저장: PII/비용/확장성 경계 때문에 거절했다.
  • 새 mutable AuditRegistry에 artifact hash 저장: 이중 source of truth, 권한 표면과 bytecode 비용 때문에 거절했다.
  • artifact에 final policyId 포함: self-referential hash cycle 때문에 불가능하다.
  • local filesystem을 production WORM으로 간주: durability, replication, retention과 access control을 증명하지 못하므로 거절했다.

Consequences

  • Manifest activation transaction 자체가 artifact commitment를 원자적으로 고정한다.
  • checkpoint event는 상태 변경 권한 없이 최종 실행 identity를 연결하고 재현할 수 있다.
  • production operator는 durable/WORM adapter, retention, backup과 접근통제를 별도로 선택·운영해야 한다.
  • 기존 schema v1~v3와 local demos는 호환되지만 새 production readiness gate는 v4다.

Related Files

  • docs/policy-audit.md
  • services/toolkit/src/policy-audit.ts
  • services/toolkit/src/production-onboarding.ts
  • src/compliance/ComplianceEngine.sol

D019 — Element incident recovery uses immutable replacement and normal delays

Date: 2026-09-22

Context

활성 Element에서 치명적 결함이 발견되면 빠른 containment가 필요하지만 기존 Element/Recipe binding을 덮어쓰면 이미 검토한 Manifest, audit artifact와 signed RFQ quote의 의미가 소급 변경된다. 반대로 교체와 재개를 모두 즉시 허용하면 사고 중 검증되지 않은 완화 정책이 production에 적용될 수 있다.

Decision

  1. operator는 영향 asset/venue/global 실행과 Manifest를 즉시 suspend할 수 있다.
  2. replacement는 새 elementId, 새 immutable Element deployment와 새 exact Recipe version으로만 등록한다. 기존 ID/version은 overwrite하지 않는다.
  3. 영향 자산만 full config/override를 보존한 Manifest semantic update로 전환한다. update는 owner/Safe가 예약하고 기존 최소 delay 뒤 operator가 활성화한다.
  4. update activation은 기존 SUSPENDED 상태를 보존한다. artifact/checkpoint, unaffected-asset 불변성, E2E와 stale RFQ quote 거부를 확인한 뒤에만 별도 delayed resume/unpause를 수행한다.
  5. known RFQ nonce는 maker가 즉시 취소하며, 누락된 quote는 교체 뒤 signed policyId mismatch가 settlement를 fail-closed하는 최종 방어선이다.

Alternatives Considered

  • 같은 Element ID의 in-place 교체: 과거 review와 quote 의미를 바꾸므로 거절했다.
  • emergency update/unpause timelock bypass: 신속하지만 결함 상태에서 compliance를 완화할 governance 공격 표면이 커져 거절했다.
  • 모든 공유 Recipe 자산 자동 migration: blast radius와 법률 승인 범위를 불필요하게 확대하므로 거절했다.
  • nonce 취소만 의존: 누락·재시작·동시성으로 모든 발급 nonce를 열거하지 못할 수 있어 policy-bound quote 검증과 함께 사용한다.

Consequences

  • containment는 즉시 가능하지만 검증된 재개에는 두 단계의 normal delay가 필요하다.
  • Factory가 TokenPolicyRegistry를 소유할 때 full update forwarding API가 필요하다.
  • 운영자는 before/after artifact와 checkpoint, pending Safe payload, 영향을 받지 않은 자산의 불변 증거를 보존해야 한다.
  • UPDATE Safe export 자동화는 #108에서 제공하며 그 전에는 reviewed external Safe tooling을 사용한다.

Related Files

  • docs/operations/element-emergency-replacement.md
  • src/factory/CornerStoreFactory.sol
  • test/integration/ElementEmergencyReplacement.t.sol
  • test/integration/RFQFlow.t.sol

D020 — C-01 holding-period recipes cannot use AMM

Date: 2026-10-05

Context

AMM은 pool이 거래 상대방이 되는 지속적 자동 체결 구조라 실제 취득자·처분자와 lot별 보유기간 증빙을 quote 단위로 고정하기 어렵다. 반면 C-01 family는 실제 RWA sender의 acquisition evidence와 거래 시점의 holding period 판단을 요구한다. 환경별 경고나 demo 예외를 허용하면 같은 Recipe가 local/testnet/production에서 서로 다른 의미를 갖고, Safe export가 기술적으로 가능한 조합을 법적으로 허용된 것으로 오해할 수 있다.

Decision

  1. element ID가 C-01- prefix인 규칙을 하나라도 포함한 bound Recipe는 AMM과 결합할 수 없다. 현재 v1/v2뿐 아니라 이후 immutable version에도 적용한다.
  2. bundled buidl-like와 reg-d profile은 RFQ-only를 기본값으로 사용한다.
  3. Toolkit profile validation, CLI onboarding, production onboarding validation, calldata/Safe export가 하나의 compatibility helper를 공유한다. exact Recipe composition을 제공하지 않는 legacy schema v1 AMM input은 fail-closed한다.
  4. CornerStoreFactory는 active/pending compiled rule set을 검사해 onboarding과 delayed Manifest update가 같은 venue compatibility invariant를 따르게 한다. ComplianceEngine도 normal Recipe composition보다 먼저 이 invariant를 적용한다.
  5. AMM adapter와 settlement plumbing 테스트는 DemoAmmReferenceRecipe처럼 C-01을 명시적으로 제외한 demo/test-only policy를 사용한다. 이 Recipe는 Reg D/BUIDL 법률 정책으로 명명하거나 production activation에 사용하지 않는다.

Alternatives Considered

  • 경고만 표시하고 실행 허용: 환경별 의미가 갈리고 실제 거래가 진행되므로 거절했다.
  • current C-01-v2만 차단: 새 version이 자동으로 우회 경로가 되므로 거절했다.
  • Toolkit에서만 차단: raw calldata나 오래된 client가 우회할 수 있어 on-chain backstop을 함께 둔다.
  • AMM 자체를 제거: C-01 없는 정책의 reference/conformance 가치까지 잃으므로 adapter는 유지하고 policy compatibility를 분리했다.

Consequences

  • 기존 Reg D/BUIDL AMM 예시는 RFQ로 이동한다.
  • local full demo는 실제 selected profile을 RFQ로 실행한다. AMM execution plumbing은 C-01-free reference Recipe를 사용하는 별도 integration test로 유지한다.
  • 새로운 Recipe/Element version은 별도 allowlist 갱신 없이 C-01 family 규칙을 상속한다.
  • Factory는 token별 primary venue를 보존하고 pending compiled plan inspection surface를 사용하므로 semantic update도 onboarding과 같은 invariant를 따른다.
  • future venue compatibility matrix가 필요해지면 이 hard invariant 위에 확장하되, C-01 AMM 허용으로 완화하지 않는다.

Related Files

  • services/toolkit/src/policy-compatibility.ts
  • services/toolkit/src/config.ts
  • services/toolkit/src/production-onboarding.ts
  • services/cli/src/commands.ts
  • src/factory/CornerStoreFactory.sol
  • src/compliance/ComplianceEngine.sol
  • src/demo/DemoAmmReferenceRecipe.sol

D021 — AMM execution uses one authenticated buyer role

Date: 2026-10-06

Context

The current AMM product model is self-directed, but its request context exposes separate initiator and buyer fields. Those roles should resolve to one authenticated actor rather than carrying ambiguous execution semantics.

RFQ already requires taker == initiator == buyer. A future delegated-action component may legitimately separate actor and principal, but no such scope-bound authorization exists in the current AMM path.

Decision

  1. The AMM adapter requires a nonzero buyer and exact context.initiator == context.buyer before it calls the pool.
  2. The verified buyer remains the AMM principal and swap recipient.
  3. Token approval remains a payment prerequisite and is not treated as an independent delegation signal.
  4. Future delegated execution must use a separately versioned authorization component that verifies principal, actor, asset, action, amount cap and expiry. It must not weaken this check through an undocumented address convention.

Alternatives Considered

  • Rely only on msg.sender == initiator: rejected because it leaves the AMM actor roles internally inconsistent.
  • Accept different initiator and buyer roles by convention: rejected because the current interface has no explicit delegation scope or expiry contract.
  • Add demo-only delegation now: rejected because the base actor invariant must be fixed before an experimental evidence/delegation seam is introduced.

Consequences

  • Existing self-initiated AMM buy and sell flows remain unchanged.
  • Relayers, agents and brokers cannot initiate AMM trades for a principal until explicit delegation support is implemented.
  • RFQ behavior is unchanged because its adapter already enforces the stronger taker/initiator/buyer equality.

Related Files

  • src/execution/adapters/amm/UniswapV3Adapter.sol
  • test/unit/execution/AMMAdapter.t.sol
  • test/integration/SwapFlow.t.sol
  • docs/architecture/execution-routing.md

D022 — TA/KYC providers plug in through a versioned SPI with isolated demo adapters

Date: 2026-09-29

Context

DATA-002 added a provider-neutral ProviderKycAdapter boundary, but the adapter carried no version, capability or environment metadata. Nothing stopped a deterministic demo adapter from being wired into a production coordinator, and provider timeouts, outages and incompatible payloads collapsed into the same reason. Vendor adapters also had no stable contract to test against across Compliance Core refactors (issue #128).

Decision

  1. TA/KYC providers implement a versioned SPI (KYC_PROVIDER_SPI_VERSION, SemVer) that exposes only normalized requests/assessments, PII-free hashes, freshness timestamps, provider capability/version metadata and typed UNAVAILABLE | TIMEOUT | STALE | INCOMPATIBLE failures. Provider-native payloads, credentials and core internals are not part of the SPI.
  2. @corner-store/compliance-data keeps one npm package with explicit subpath boundaries: root (coordinator, store, SPI), /spi, /demo and /conformance. The demo adapter is not reachable from the root export, and no core module imports it.
  3. KycEvidenceCoordinator requires an explicit mode. It validates and snapshots adapter metadata at construction, refuses a different SPI major or a newer SPI minor, and in production mode refuses any adapter not declared production.
  4. Results whose providerId, schema version or optional facts fall outside the declared metadata fail closed as PROVIDER_INCOMPATIBLE. Coordinator-enforced and adapter-reported timeouts fail closed as PROVIDER_TIMEOUT.
  5. One conformance suite validates any adapter against the SPI and is run for both the demo adapter and a production-style example adapter. Vendor adapters stay optional and outside the core.

Alternatives Considered

  • Separate npm packages for SPI, demo and conformance: rejected for now because the package is still private and unreleased; subpath exports give the same import boundary with less release overhead and can be split later without changing the SPI.
  • Detect demo adapters with instanceof: rejected because a second copy of the package would bypass the check; the declared environment metadata is validated structurally instead.
  • Infer production mode from NODE_ENV or similar: rejected because an implicit default could silently accept a demo adapter; the mode must be stated by the operator.

Consequences

  • Existing adapters must add metadata, and coordinators must pass mode. Timeouts that were reported as PROVIDER_UNAVAILABLE are now PROVIDER_TIMEOUT.
  • The evidence hash domain and store semantics are unchanged, so previously materialized evidence remains valid.
  • The declared environment is an operator attestation, not proof. Production readiness still depends on operator-supplied provider credentials, durable store, audit sink and review.

Related Files

  • services/compliance-data/src/kyc-spi.ts
  • services/compliance-data/src/kyc.ts
  • services/compliance-data/src/kyc-demo.ts
  • services/compliance-data/src/kyc-conformance.ts
  • services/compliance-data/examples/http-kyc-provider-adapter.ts
  • services/compliance-data/README.md

D028: Context authority is authenticated before policy evaluation

Date: 2026-11-11

Context

Policy evaluation consumes actor, flow and affiliate context. Caller-provided seller/flow/affiliate fields alone are insufficient authority for those inputs. Issue #157 needs a versioned authentication boundary while preserving deployed contracts and the public RFQ v2 runtime.

Decision

  1. Separate ExecutionRouterV2 authenticates registration, type, implementation review and runtime/configuration evidence before Engine evaluation. Its view-only adapter preflight validates the supplied context without replacing it or returning a generic hash as authority.
  2. RFQ actors, token legs, exact amounts and venue derive from a signed quote; AMM seller/venue/target derive from the registered pool and canonical tokens. Caller authentication stays with the Router. Settlement repeats validation and retains measured exact fill, atomic rollback, commit and existing events.
  3. Current pinned A-06 evidence authenticates the actual sender for each leg with compiled affiliate consumers: buyer for tokenIn, seller for tokenOut. RFQ signs the exact leg/aggregate commitment specified in docs/product-specs/execution-context-provenance.md. A-06 remains operator-attested evidence rather than independent fact finding.
  4. Venue evidence is separate from unchanged VenueConfig. It pins versions, adapter/source/policy runtime hashes and final configuration. Re-registration clears evidence; every AMM pool edit invalidates all venues on that adapter.
  5. Implementation approval reviews immutable code and dependencies explicitly. Self-declared capability/runtime hashes cannot prove correctness or immutability. Governance-approved malicious code remains a trust boundary.
  6. V3 deployments admitting affiliate RFQ sells must use the new immutable EngineSelectionV2 (B-04-v2) wherever B-04 applies. It resolves the security recipient per asset through AssetFlow: buyer for tokenOut, seller for tokenIn, and checks that recipient's MM claim. Register the new ID and bind it through an opt-in exact Recipe/Manifest update; existing B-04-v1, tests, recipes and defaults stay unchanged. Schema 6 activation rejects any active compiled B-04-v1 rule, including non-blocking rules, and unavailable/malformed compiled-policy reads. Policies without B-04 remain supported.
  7. Deploy a separate ComplianceEngine for each v3 Router stack. Its single onlyRouter binding cannot serve both legacy Router and RouterV2. Schema 6 REGISTER plans include unsigned Engine.setRouter(RouterV2) before adapter wiring and final evidence pinning; UPDATE verifies existing wiring without rebinding. Activation requires both RouterV2.engine() == Engine and Engine.router() == RouterV2, rejecting mismatched or unavailable reads.

Alternatives Considered

  • Authenticate only after evaluation: leaves policy inputs unauthenticated at the point of evaluation.
  • Replace context inside the adapter: creates disagreement with already-bound decisions and obscures field ownership.
  • Let callers choose affiliate booleans or supply arbitrary hashes: provides no current-source or actual-sender authentication.

Consequences

  • Unsupported/mismatched context and missing/drifting evidence fail closed. ERC-3643/ONCHAINID remain external token/identity boundaries; non-Router paths do not gain Corner Store policy enforcement.
  • The following implemented defaults remain open items, team to confirm: conditional primary distribution from the unique active compiled C-01-v2 distributor; matching statuses for evidence-requiring pairs; immediate invalidation on any commitment change, including same-status refresh; and reviewed immutable-only activation without proxy-aware verification. Opt-in timing is recorded in D029.

Related Files

  • docs/product-specs/execution-context-provenance.md
  • src/execution/ExecutionRouterV2.sol
  • src/execution/ContextEvidence.sol
  • src/execution/VenueRegistry.sol
  • src/interfaces/execution/IExecutionContextVerifier.sol
  • services/toolkit/src/venue-context.ts

D029: RFQ v3 migrates through separate deployments and explicit wire versions

Date: 2026-11-11

Context

Context provenance requires signed flow and affiliate evidence. Reinterpreting existing RFQ v2 signatures, APIs, records or public Monad artifacts would break existing consumers and deployed settlement.

Decision

  1. Deploy ExecutionRouterV2 and RFQAdapterV3 separately. V3 uses the ordered RFQQuoteV3 type and CornerStoreRFQ domain version 3, with chain ID and the new adapter as verifying contract. Only flowType and affiliateEvidenceHash are added before nonce. Never convert v2 signatures.
  2. Preserve the legacy Router ABI/events, RFQ v2 type/domain/builders, /rfq/quote responses and live Monad runtime/artifacts. Opt into new SDK exports, /rfq/v3/quote, host capability/readiness and explicit CLI bindings.
  3. Persist new coordinator records at schema 2 with quote version, domain and context evidence; read legacy records under their original meanings. Revalidate RESERVED evidence/domain/nonce before signing and never silently re-sign PUBLISHED quotes. Legacy-only stores continue to write schema 1.
  4. Onboarding schema 6 adds explicit Router/runtime, immutable venue and source authority evidence. Legacy schemas 1-5 have explicit parsers and reject v6-only fields. Pin final configuration after wiring/pool edits and verify post-state before activation. Deployment/onboarding helpers emit unsigned intents only.
  5. Keep reference/operator signing on one locally stored env/file key. Key management, multisig and custody expansion remain deferred. No registry contract for quote conversion, package publication or public deployment is introduced by this feature.

Alternatives Considered

  • Change v2 types/defaults in place: breaks signature and API compatibility.
  • Registry-based quote reinterpretation: adds authority/state without preserving the original signed meaning; the approved plan selects versioned typed data.
  • Rewrite persisted records or infer v3 addresses from legacy artifacts: hides domain/deployment mismatches and risks signing against the wrong contract.

Consequences

  • Operators preserve v2 artifacts, expire/cancel old quotes and request fresh v3 signatures after new deployments and schema 6 verification. Package/schema/ capability/ABI/domain compatibility is published in docs/sdk-versioning.md.
  • Package versions remain 0.1.0 in this unpublished branch. Publication requires the normal version/release gate; no release is implied here.
  • Open item, team to confirm: migration timing remains opt-in, with separate deployments and RFQ v2 retained on Monad. D028's remaining defaults also remain open. No migration is performed on an existing public deployment.
  • The v3 live E2E joins both legacy Anvil profiles as a documented manual delivery/release gate. Existing CI continues its repository/container gates.

Related Files

  • docs/sdk-versioning.md
  • docs/product-specs/production-rfq-policy.md
  • services/rfq/src/eip712.ts
  • services/rfq/src/coordinator.ts
  • services/rfq-host/src/server.ts
  • services/toolkit/src/production-onboarding.ts
  • scripts/e2e-context-provenance.sh

D030: Production RFQ bounds lifetime and authorizes products before pricing

Date: 2026-11-11

Context

Issue #155 requires bounded firm-quote exposure and explicit product support before pricing, inventory, risk or signing. A policy resolver alone can neither prove local product approval before RPC calls nor distinguish denial from outage. Re-resolving policy on a retry can change the request's authoritative identity.

Decision

  1. Production coordinators use a local operator catalog of maker, ordered pair, venue, execution-bound policy ID, quote capability and flow. Bound catalogs to 1-256 entries, reject malformed/ambiguous entries and snapshot normalized values at construction. Hosts require a catalog for each enabled endpoint. After bounded body parsing, hosts authenticate and bind the taker, then apply shared limiting before TTL/product authorization. TTL/product rejection still precedes readiness, store, policy, pricing, risk, reservation and signing. Authentication/rate-limit rejection auditing and incidents retain parent behavior.
  2. Default TTL is 60 seconds and default maximum is 300 seconds. Operator tuning requires positive safe integers with default <= maximum <= 3600 seconds. Invalid configuration fails startup; invalid/above-maximum request TTL fails before quote work, after host authentication/rate limiting. Never clamp a client's TTL silently.
  3. For a new request, resolve the current policy server-side and require an exact catalog match before pricing. Persist the authoritative authorization schema 1 (including chain and adapter) atomically with request, nonce and lease. Replays/conflicts use the original authorization/policy/expiry; no policy refresh, repricing or replacement signature for a published quote. RESERVED recovery retains freshness/context revalidation. Current local tuple support and TTL limits still gate every attempt. Both evidence APIs compare current catalog policy only for new requests; retries validate the persisted grant.
  4. Distinguish invalid input (400), product denial (403), conflict (409), terminal policy/configuration failure (500) and retryable dependency failure (503). Known resolver denials/configuration errors use typed coordinator codes; arbitrary provider exceptions are unavailable. Diagnostics and metric labels use bounded, redacted reason/module values and never raw exception messages. Expected terminal unsigned replays use TERMINAL_REPLAY and retain the bounded 400 invalid_request response; unexpected internal errors remain 500.
  5. Preserve deployed contracts, quote types/events/success responses and protected public Monad v2 paths. Legacy non-production quote() and lightweight SDK paths remain available. Both production evidence APIs require a catalog. Do not backfill grants for older records: drain/expire and use a fresh request namespace/store. Bootstrap API shape is validated; runtime env schema stays 1.

Consequences

  • Operators own product approval and refresh catalogs after approved policy changes. Approval is not independent verification of ERC-3643/ONCHAINID facts or a substitute for current on-chain fill-time checks.
  • Removing a tuple disables retries; changing its policy never rewrites an old authorization. A lower TTL ceiling may reject an older request.
  • The local context E2E explicitly configures 600s default/maximum and both versions/directions. No public deployment or key-management change is included.

Related Files

  • docs/product-specs/production-rfq-policy.md
  • services/rfq/src/productAuthorization.ts
  • services/rfq/src/coordinator.ts
  • services/rfq-host/src/server.ts
  • services/rfq-host/README.md

D031: Identity topology is an explicit per-recipe commitment

Date: 2026-11-11. Issue #159 decision 24. Status: P1 guard implemented; full MEMBER support scheduled as separate November P2 work.

Context

New identity policies must not silently choose a topology or allow an alternative Recipe to bypass it. Legacy policy tuples and deployments must keep their meaning.

Decision

Use opt-in production onboarding schema 7 with recipes[].identityPolicy declaring RFQ/TSV and DIRECT. RFQ has no default; TSV is fixed to DIRECT. Reject unset, unknown and MEMBER values until the separate P2 implementation. Commit the exact 64-byte abi.encode(uint8 track, uint8 topology) through required A-04-v2 ManifestPolicyConfig parameters, preserving shared Manifest/RecipeBinding tuples. Use ManifestPolicyConfig schema 1 for legacy configurations, schema 2 for RFQ and schema 3 for TSV. New schema 7 RFQ onboarding requires schema 2 and at least one matching REQUIRED_BLOCKING A-04-v2 RFQ policy; omission, a TSV substitution and mixed RFQ/TSV tracks fail closed. Legacy schema 1 Manifests retain their meaning. Require REQUIRED_BLOCKING bindings and BLOCK enforcement, including updates and mixed legacy/new compositions. Retain every schema 6 context check in schema 7. Schemas 1-6 keep their meaning and cannot select A-04-v2; schema 7 identity recipes cannot substitute A-04-v1.

Consequences

Full-word decoding rejects noncanonical words, trailing data and malformed lengths. The live deployment exposed an EIP-170 size failure; equivalent compact validation now leaves TokenPolicyRegistry at 24,570 bytes, only 6 bytes below the limit. The deployed-size and composition/fuzz regressions must remain passing. MEMBER institution/attestation support and wallet sanctions in both modes are scheduled, not implemented. A TSV track declaration alone is not launch readiness.

Related Files

  • docs/product-specs/identity-policy-topology.md
  • services/toolkit/src/identity-policy.ts
  • src/compliance/libraries/IdentityPolicy.sol
  • src/registry/TokenPolicyRegistry.sol
  • test/unit/registry/IdentityPolicyComposition.t.sol

D032: External attestations require separate operator acceptance

Date: 2026-11-11. Issue #159 decision 25. Status: P1 implemented.

Context

Issuer and delegation provenance must be explicit without expanding A-04-v1's five-field KycClaim ABI or manufacturing valid evidence when binding a wallet.

Decision

Deploy a separate A-04-v2 implementing IIdentityEvidenceV2. Its evidence binds wallet, identity, asset and binding generation to issuer ID, issuedAt, expiry, trust-basis commitment, attestation type and keyed evidence commitment. Operator acceptance is a decision based on evidence the operator accepted; external attestations do not replace it. SPI 2.0.0 requires explicit acceptance and strict audit before publishing eligible evidence. Preserve v1 exports and stores.

Only authorized operators/owner manage issuer trust and evidence, with change events. Trade checks read current issuer trust and basis equality. Binding creates no evidence; unbind/rebind invalidates prior records. Missing, expired, unsupported, untrusted, mismatched or revoked evidence fails closed. Counterparty screening is an explicit operator setting with the same pipeline.

Consequences

Restoring the exact trust basis can restore otherwise valid unexpired evidence; revoke individual records when reinstatement is unwanted. ERC-3643/ONCHAINID and provider accuracy remain external trust boundaries. The contract does not verify external signatures or recompute HMAC. The in-process reference store requires a transactional durable replacement in production. A-11 arithmetic is unchanged.

Related Files

  • docs/product-specs/identity-evidence-v2.md
  • src/interfaces/compliance/IIdentityEvidenceV2.sol
  • src/compliance/elements/IdentityUniquenessV2.sol
  • services/compliance-data/src/kyc-v2.ts
  • test/unit/compliance/elements/IdentityEvidenceV2.t.sol

D033: Compliance-data owns one local key for v2 evidence commitments

Date: 2026-11-11. Issue #159 decision 26. Status: keyed commitments implemented; venue pseudonyms and private wallet mapping scheduled as separate P2 work.

Context

Unkeyed identity-derived references permit outsiders to recompute guesses. Operator-api is a read-only public-commitment boundary, not an evidence processor.

Decision

Use domain-separated HMAC-SHA-256 for v2 identity, source, assessment and evidence commitments over canonical JSON. Load exactly one 32-byte hex key from local env or file in the compliance-data runtime, and inject only a restricted hashing capability into adapters, coordinator, store validation and calldata translation. The coordinator rekeys every provider-controlled identity, request, source and assessment reference before public audit, persistence, acceptance or calldata export, even if the adapter supplied an opaque or keyed-looking value. Missing/malformed/unreadable/ambiguous configuration fails startup; no unkeyed fallback. Operator-api never receives the key. On-chain acceptance receives only public enforcement fields and commitments through unsigned exported calldata.

Consequences

V2 uses separate domains, SPI types and persisted records; no automatic v1 hash migration. Raw evidence, provider case references, LEI and keys remain off-chain. Same-assessment replay/conflict and monotonic revocation remain validated by the store. Key management, rotation, KMS/HSM, custody and multisig remain deferred. Venue-specific pseudonyms, private wallet mappings and same-identity blocking are scheduled before any TSV launch, not provided by keyed commitments alone.

Related Files

  • services/compliance-data/src/kyc-hmac-v2.ts
  • services/compliance-data/src/kyc-calldata-v2.ts
  • services/compliance-data/examples/http-kyc-provider-adapter-v2.ts
  • services/compliance-data/test/kyc-v2.ts
  • docs/product-specs/identity-p2-schedule.md

D034: Prove the existing self-directed settlement identity binding

Date: 2026-11-11. Issue #159 decision 27. Status: P1 proofs implemented; settlement-asset cards scheduled as separate November P2 work.

Context

AMM-002 / #143 already binds execution actors on the Router path. The requested check needs explicit identity-to-token-leg evidence for RFQ v2/v3 and AMM.

Decision

Add named test_settlementLegBoundToPermittedIdentity_* invariants for buys and sells without changing settlement contracts. Assert the screened wallet/identity, exact investor/counterparty token deltas and zero Router/adapter custody. Actor mismatch and revoked identity/evidence must leave balances, nonces and surveillance unchanged; explicit restoration permits the failed request to retry once.

Register opt-in RegD506cRecipeV4 (family 1, version 4) replacing only A-04-v1 with A-04-v2. Retain B-02-v2 and C-01-v2, so this recipe remains incompatible with AMM. Use isolated fixtures and a live provider-evidence-to-calldata-to-settlement gate.

Consequences

The 42 named invariants use real ERC-3643/ONCHAINID. Their AMM pool is a fixed-rate callback mock with a separate C-01-free test recipe; canonical Uniswap regressions retain their existing policy. The live identity gate covers 40 RFQ v2/v3 cases with bilateral screening enabled explicitly. These proofs cover self-directed Router execution, not delegated transfers or transfers outside the Router. Cards describing issuer, AML-owner label and freeze scope remain unimplemented.

Related Files

  • docs/product-specs/identity-settlement-binding.md
  • src/compliance/recipes/RegD506cRecipeV4.sol
  • test/integration/IdentitySettlementBinding.t.sol
  • scripts/e2e-identity-evidence.sh
  • script/IdentityEvidenceFixture.s.sol

D035: LEI is optional private evidence, never an eligibility requirement

Date: 2026-11-11. Issue #159 decision 28. Status: P1 implemented.

Context

Legal-entity participants may supply an identifier without imposing a new policy requirement or changing eligibility/sanctions behavior for existing participants.

Decision

Allow optional lei in v2 off-chain evidence. Validate the 20-character uppercase alphanumeric format ending in two digits and MOD-97-10 checksum. Include a supplied value in canonical evidence commitments and store round trips. Omission is valid; no policy requires LEI or treats it as a substitute for eligibility, beneficial-ownership or sanctions facts.

Consequences

LEI stays out of public calldata, events, artifacts and audit records. V1 evidence shapes and all on-chain tuples remain unchanged. Tests cover omission, valid values, malformed length/characters/checksum, commitment changes and persistence.

Related Files

  • services/compliance-data/src/kyc-spi-v2.ts
  • services/compliance-data/src/kyc-hmac-v2.ts
  • services/compliance-data/test/kyc-v2.ts
  • docs/product-specs/identity-evidence-v2.md

D036: Jurisdictional sanctions bundles require a separate opt-in A-01-v2

Date: 2026-11-11. Issue #159 decision 29. Status: design scheduled for November P2; no sanctions implementation in DATA-004.

Context

A-01-v1 has one currentListVersion. Per-jurisdiction list bundles need independent list identities/versions without reinterpreting deployed claims or recipes.

Decision

Schedule one separate PR for A-01-v2 with recipe-selected list bundles and (listId, version) entries. A version update invalidates stale claims independently for each list. TSV must include OFAC and cannot remove it through configuration or updates. Missing required-list claims fail closed. A local SDN-file import is sufficient; oracle/vendor integration is optional, not a prerequisite.

Consequences

Acceptance tests must cover independent invalidation, missing claims and OFAC omission/removal rejection. Preserve A-01-v1's single-version behavior until explicit opt-in. Wallet screening remains required in both future topologies. DATA-004 does not claim jurisdictional list support or TSV launch readiness. Dates and assignees for the four P2 PR slots remain for team confirmation.

Related Files

  • docs/product-specs/identity-p2-schedule.md
  • docs/compliance/spec-sheets/A-01_sanctions.spec.md
  • docs/ROADMAP.md

D037: Versioned complete production commitments require clean Git for broadcast

Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.

Context

A manual source list omitted the imported production deployer. HEAD alone could not distinguish changed sources or a copied source-only bundle from a clean release, and did not commit the compiler/build/orchestration inputs.

Decision

Production evidence version 2 uses canonical domain-separated SHA-256 source, build and evidence identities. Resolve compiler inputs from the production entry point; include the deployer, transitive contracts, exact configuration/remappings, orchestration, lockfiles, tool/dependency identities, compiler settings and creation/runtime bytecode commitments. Compile a captured isolated workspace, exclude inherited build overrides and verify copied bytes before execution.

Record HEAD plus explicit clean/dirty/source-only/unavailable provenance, with staged, unstaged, untracked and recursive submodule evidence. Dirty, unavailable and source-only provenance permits diagnostics but blocks production broadcast. Before granting clean provenance, compare captured bytes with HEAD blobs, following committed submodule gitlinks independently of index visibility flags. Bind canonical configuration, deployment ID, chain and wiring into evidenceId; plans, unsigned exports, review evidence and deployment records must agree.

Consequences

Offline source hashing requires the pinned Forge/Solc toolchain. Repository, package and runtime copies preserve source/build commitments, but a source-only package cannot claim clean Git through an upstream commit string. New broadcast requires independently reviewed clean Git-backed inputs. Exact tool/runtime changes require a new identity and review. Key management, custody and multisig expansion remain deferred; the existing local Foundry account needs no vendor.

Related Files

  • services/toolkit/src/production-evidence.ts
  • services/toolkit/src/production.ts
  • services/cli/scripts/prepare-package.mjs
  • docs/deployment-production.md

D038: Production envelopes publish exclusively after validation

Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.

Context

Overwriting copies could replace reviewed artifacts, and exclusive writes alone could expose incomplete files. Interruption after broadcast needs a recovery path that preserves evidence without repeating transactions.

Decision

Reserve a vacant destination before signing/broadcast. Generate in a unique sibling operation directory; the production Solidity script writes only a candidate inside its captured workspace. Validate successful canonical receipts, receipt-derived addresses, exact transaction inputs/order, reconstructed runtime bytecode, ownership/operator/wiring and Safe state before publication.

Reservation setup is transactional before the operation is returned to the caller. A failure while writing operation pointers, probing hard-link/fsync semantics or performing the final vacancy check removes the reservation and staging directory. If filesystem cleanup itself fails, the typed error reports the exact staging and reservation paths and marks cleanup incomplete; signing or broadcast has not started and the incomplete setup is not recoverable as an execution journal.

Require the staging/output directories and every ancestor to be owned by the current uid or root. Reject group/world write permissions on staging/output; allow writable ancestors only with the sticky bit, which protects operator-owned entries from other users. Reject foreign ownership even on sticky ancestors and reject application symlinked ancestry. The existing macOS /tmp and /var system aliases have their /private target ancestry checked too. Check existing output ancestry before creating directories, then check the output directory before reserving anything. Check staging on creation and recheck both paths at publication/recovery, naming the offending path on failure.

This StrictModes-like precondition is the filesystem trust boundary: publication is safe against other local principals, with root trusted. Concurrent operator uid processes are out of scope because they already hold the operator's signing material. Node has no fd-based linkat/unlinkat; path checks cannot eliminate replacement races against writers within that trust boundary.

Publish by exclusive no-follow creation and file fsync, validate through a no-follow descriptor held across the no-replacement hard link, then verify the final regular file's device, inode and size. On mismatch, attempt cleanup only after verifying the output directory/ancestry again and rechecking the observed entry's identity. Cleanup and its parent fsync are best effort, preserving the original publication error. The separate identity check and unlink do not protect against same-uid replacement immediately before unlink. Parent fsync, staging-link cleanup and another fsync complete publication. Never use a replacing rename; unsupported semantics fail closed. Apply the same publisher to signable exports. The raw-byte publisher preserves imported signed bytes without reserialization.

Persist immutable journal events. Recovery rebuilds and revalidates staged commitments, receipts and chain state before publication/cleanup. It never signs, automatically rebroadcasts or overwrites an existing final artifact.

Consequences

Pre-link failure leaves no final. Post-link interruption may leave a complete final, which recovery verifies before cleanup. Failed broadcast/verification retains the captured workspace and journal. Missing evidence/RPC access blocks recovery. Broadcast uses Foundry --slow to preserve transaction/hash association. Local SIGKILL and injected I/O tests do not establish power-loss durability or support for untested filesystems.

Related Files

  • services/toolkit/src/production-publication.ts
  • services/toolkit/src/production-chain.ts
  • services/cli/src/commands.ts
  • script/DeployProductionCore.s.sol

D039: Preserve legacy readers and require version 2 for new production releases

Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.

Context

Existing public-testnet records and consumers must remain usable while stronger production evidence becomes mandatory for new deployments.

Decision

Keep legacy artifacts and review files in their original schema and readable through existing readers. Do not rewrite or upgrade published records. New production deployments require evidence version 2. Version 1 review evidence cannot authorize a new production deployment.

Version 2 verification requires the reviewed evidenceId, rebuilt local source/build/configuration commitments and an independently trusted expected recordDigest. The record binds the script artifact digest, transaction inputs, receipts and evidence identity without circular hashes. A version 2 expectation cannot fall back to legacy verification.

Consequences

Compatibility tests enumerate existing public records, pin the published Monad record hash, read exact files through the CLI and read-only Operator API and compare bytes afterward. No live-chain readiness is needed to prove readability. Public Monad runtime, deployment infrastructure and deployed contracts remain unchanged. Legacy readability does not imply version 2 verification guarantees.

Related Files

  • scripts/test-production-legacy-artifacts.mjs
  • services/cli/src/commands.ts
  • services/toolkit/examples/production-evidence.example.json
  • services/toolkit/examples/production-evidence-v2.example.json

D043: Primary Distributor Authority for EXEC-002

Status

Pending team decision. C-01-v2-only support is a known implementation limitation, not an approved permanent product boundary.

Context and Options

RFQAdapterV3 and OnchainRFQContextResolver authenticate primary distributors only from exact active compiled C-01-v2 parameters. Primary assets without C-01 or using another C-01 version fail closed. The team must choose:

  1. Add a Manifest/policy-config distributor commitment independent of C-01.
  2. Explicitly approve C-01-v2-only primary-distribution support.

PR #163 documents the limitation without redesigning distributor authority. The owner resolved affiliate evidence separately: require it only for active compiled A-06/B-04 consumers, and bind the pinned source to the exact registered A-06-v1 implementation at activation and runtime. Existing required-evidence failure behavior remains fail closed.