did-btcr2-js

Architecture Decision Records

Each ADR captures one significant architectural decision: the context, the alternatives considered, the chosen path, and the trade-offs accepted. ADRs are numbered in chronological order of when the decision was made.

# Date Title
001 2025-02-19 Monorepo Package Boundaries
002 2025-03-14 JCS Canonicalization and bip340-jcs-2025 Cryptosuite
003 2025-03-14 Bech32m DID Identifier Encoding
004 2025-08-23 Rename did:btc1 to did:btcr2
005 2025-09-18 Bitcoin Package Extraction and Browser Decoupling
006 2025-09-26 API Package Boundary
007 2025-10-28 KMS Package Boundary
008 2025-11-12 Aggregation Subsystem Inception
009 2025-11-25 Sans-I/O Foundation at the Bitcoin Transport Layer
010 2026-02-13 did:btcr2 v0.2 Spec Alignment and Spec-Tracking Policy
011 2026-03-06 Test Vector Generation Methodology
012 2026-03-13 KMS Dual Signing, URN Identifiers, and Watch-Only KeyEntry
013 2026-03-17 CLI Per-Command Modules with Dependency Injection
014 2026-03-17 Canonicalization Functions, toJSON Convention, and base64urlnopad Default
015 2026-03-20 Keypair Security Hardening and Noble / Scure Migration
016 2026-03-25 Sans-I/O Resolver State Machine
017 2026-03-27 Optimized Sparse Merkle Tree as the Aggregate-Beacon Primitive
018 2026-03-28 Beacon Hierarchy (Singleton, CAS, SMT)
019 2026-03-30 Browser Compatibility Constraint and @noble / @scure Dependency Policy
020 2026-04-06 Aggregation Layered Architecture
021 2026-04-08 tsconfig Normalization and CJS via tsup
022 2026-04-08 Split User Docs from Contributor Docs
023 2026-04-10 CAS Read Path: Helia vs HTTP Gateway
024 2026-04-10 API Facade: Lazy Construction and Layered Configuration
025 2026-04-13 Sans-I/O Updater State Machine for the DID Write Path
026 2026-04-14 Drop bitcoinjs-lib; @scure/btc-signer for Bitcoin Primitives
027 2026-04-14 Aggregation Protocol Security Hardening and Threat Model
028 2026-04-22 HTTP/REST as an Additive Transport for Aggregation
029 2026-04-22 TLS-Only Confidentiality for HTTP Transport
030 2026-04-22 Fetch-Based SSE over Native EventSource
031 2026-04-22 Permissive CORS Default for HTTP Transport
032 2026-04-22 Sans-I/O handleRequest / handleSse Primitives
033 2026-05-18 Rename @did-btcr2/kms to @did-btcr2/key-manager
034 2026-05-21 KeyManager.canExport Capability Pattern
035 2026-06-15 SMT Proof Wire Format: base64url no-pad and the Zero-Node Collapsed Bitmap
036 2026-06-16 Adopt the Zero-Hash SMT Model per algorithms.html
037 2026-06-19 Rename Beacon to SinglePartyBeacon and the Two-Axis Beacon Model
038 2026-06-20 MuSig2 Key Custody: Bounded, Zeroized Secrets at the Participant Boundary
039 2026-06-21 Cohort Condition Model
040 2026-06-22 Multi-Cohort Aggregation Service Runner
041 2026-06-23 Cooperative Non-Inclusion Signaling for Aggregate Beacons (superseded by 042)
042 2026-06-23 Fault-Tolerant Aggregate Beacon Output (Hybrid Taproot)
043 2026-06-24 k-of-n Fallback Signing Protocol for Aggregate Beacons
044 2026-06-24 Beacon Change Output - Caller-Supplied Address to End Beacon-Address Reuse
045 2026-06-24 Analytical-vsize Dynamic Fees for the Aggregation Beacon Broadcast
046 2026-06-24 Extract the Aggregation Subsystem into @did-btcr2/aggregation
047 2026-06-25 CLI Secret-Key Custody via an Encrypted File-Backed Keystore
048 2026-06-25 CLI Configuration and Profile Model: Writable Config with Identity and Aggregation Profiles
049 2026-06-25 Default Keypair Generation in the create Command
050 2026-06-26 Split the Aggregation Package into Core, Participant, and Service Subpath Exports
051 2026-06-26 Verify the Signing Key Against the Named Verification Method in Updater.sign
052 2026-06-26 Cross-Process File Locking for the CLI Keystore
053 2026-06-27 Bitcoin Service Defaults Belong to the SDK, Not the Sans-I/O Transport
054 2026-06-27 Make the bip340-jcs-2025 Cryptosuite Method-Agnostic
055 2026-06-27 Harden the Resolver provide() Trust Boundary
056 2026-06-27 Validate the Beacon Signal Output Format and Document the CAS Announcement Hash Chain
057 2026-06-28 Extensible @context and Uniform Multikey Enforcement in DID Document Validation
058 2026-06-29 Remove the Legacy Helia CAS Read Path and Shrink the Method Bundle
059 2026-06-29 Beacon Discovery Is Unbounded by Default, With an Opt-In Round Cap
060 2026-06-29 Carry the Version Counter and Update-Hash History Across Resolver Discovery Rounds
061 2026-06-30 Remove the Unused Public Document Wrapper Class
062 2026-06-30 Harden did:btcr2 Identifier Encoding and Decoding
063 2026-07-01 Harden Beacon UTXO Selection (Confirmed, Non-Dust, Deepest-First, Deterministic)
064 2026-07-02 FOSS In-Repo Coverage Reporting and a Dependency-Audit Gate
065 2026-07-02 Adopt Changesets for Per-Package Changelogs with Manual Publishing
066 2026-07-02 Trustless Transport Authentication for EXTERNAL (x1) DIDs via In-Band Genesis Documents
067 2026-07-02 Resolver Duplicate-Update Confirmation - Conditional Increment and Compare-Only History
068 2026-07-06 versionTime Evaluation Order for Duplicates and Guarded Duplicate Confirmation
069 2026-07-06 Fetch-Based CAS Executors Replace the In-Process IPFS Dependency
070 2026-07-07 Beacon Broadcasts Return Structured Artifacts and CAS Publication Precedes the On-Chain Spend
071 2026-07-07 A CAS Publication Policy for the API Update Path (publishToCas), Writable-CAS Capability Detection, and Enriched Update Results
072 2026-07-07 CLI Writable-CAS Configuration and an Opt-In –publish-to-cas Flag
073 2026-07-07 CAS Publication Is Opt-In - Default publishToCas to ‘never’ and Make ‘auto’ Non-Blocking
074 2026-07-07 CLI Configuration Resolution Correctness and Safety
075 2026-07-07 CLI Configuration Validation and Introspection
076 2026-07-07 CLI Bitcoin and CAS I/O Passthrough Knobs
077 2026-07-07 CLI Secret Handling for Bitcoin RPC Credentials
078 2026-07-07 Wire the Advertised-but-Dead Bitcoin RPC and Profile-Identity Config Surface
079 2026-07-08 Consolidate CLI State Under a Single ~/.btcr2 Home Directory
080 2026-07-08 Keystore Lifecycle, a Confirmed First Passphrase, and Opt-In Dev Keystores
081 2026-07-14 A Session Unlock Agent for the Encrypted Keystore
082 2026-07-14 Per-Network Presets for Human-Facing Faucet and Explorer Links
083 2026-07-14 A btcr2 quickstart Command that Composes Onboarding into One Step
084 2026-07-16 Publish the Coverage Badge from CI to a Dedicated Branch
085 2026-07-17 Typed Errors Across Core Packages, Enforced by Lint
086 2026-08-19 Beacon Signal Recognition - Decode the Serialized Script and Require a Beacon Spend
087 2026-08-19 The Bitcoin RPC Password Has No Command-Line Flag
088 2026-08-19 Enforce capabilityInvocation Membership When Resolution Applies an Update
089 2026-08-19 Aggregation Signing Preconditions for Cohort Members
090 2026-08-19 Bind a Message’s Claimed Sender to Its Authenticated Key on Every Aggregation Receive Path
091 2026-08-21 Inject the DID into Beacons, and Resolve Relative DID URLs to Absolute Before Comparing
092 2026-08-22 Apply the Relative DID URL Rule to the Write Path and to Proof References
093 2026-08-27 A New DID Inherits the Network of the Configured Bitcoin Connection
094 2026-08-28 Deactivation Is an Ordinary Update Carrying the Deactivation Patch
095 2026-08-28 Derive the Initial Document and Beacon Addresses Offline at the Facade
096 2026-08-28 The Facade Produces Signers, and the Write Path Is Importable from the API Alone
097 2026-08-28 Resolution Failures Carry Their Root Cause
098 2026-08-31 Update Source Resolution Accepts the Caller’s Resolution Options
099 2026-09-02 A Facade with No Bitcoin Connection Mints Regtest Identifiers
100 2026-09-02 The Update Path Refuses a Deactivated Source Document
101 2026-09-03 A Write’s Source Pair Is Accepted Whole or Not at All
102 2026-09-03 The Funding Guard Applies the Beacon’s Spendability Rule
103 2026-09-03 A DID and Its Bitcoin Connection Must Name the Same Network
104 2026-09-03 The Update Path Derives an Omitted Verification Method and Beacon
105 2026-09-04 Resolution Processes Only Beacon Signals With at Least minConf Confirmations
106 2026-09-07 The cli Write Commands Take the Identifier and Resolve the Source Through the api
107 2026-09-08 Identifier Validation Returns a Report, and the cli Exposes It as identifier decode and identifier validate
108 2026-09-09 The api Builds a Genesis Document from a Spec, and the cli Exposes It as genesis build
109 2026-09-09 A BTCR2 Update Carries the Pinned @context Array, and the Resolver Rejects Any Other Array
110 2026-09-09 Resolution Reports the Required Document Metadata and DID Resolution Error Codes
111 2026-09-10 The Resolver Processes One Update per Pass, Validates the Resolution Options, and Compares versionTime with the Block mediantime
112 2026-09-10 The Update Paths Check the Proof Fields and the Proof Time Window, Accept an Embedded Verification Method, Apply the JSON Patch Strictly, and Raise INVALID_DID_UPDATE
113 2026-09-11 The Test-Suite Submodule and the Test-Vector Pipeline Live in the api Package, One Generator Writes the Fixed Vector Layout, and Vectors Must Verify, Not Match Byte for Byte
114 2026-09-15 The Resolver Ignores the Signals of a Beacon Address That an Applied Update Removed
115 2026-09-15 The Vector Corpus Holds No Pipeline State, signals.json Records the Anchored Signals, and Two Recipes Cover a Duplicate Signal and a Removed Beacon Address
116 2026-09-15 The Anchor Step Broadcasts One Round per Command, and No Pipeline Script Mines a Block
117 2026-09-15 The Regtest Vectors Publish the CAS Objects to a Kubo Node in the Polar Stack, and the Public Networks Use an External IPFS Node
118 2026-09-21 The Resolver Keys the Processed Beacon Signals by Beacon Address, Not by Service Id
119 2026-09-21 The api Takes a Separate Signer for the Beacon Transaction Input
120 2026-09-22 The SMT Follows the Leaf Values, the Proof Bit Sequence, and the Signal Results of Spec PR 365
121 2026-09-22 A Vector Pass Adds Recipes to Anchored Sets, the SMT Recipes Cover the Four Leaf Values, and signals.json Records the Chain Tip
122 2026-09-23 The api Exports the Steps of a Vector Tool, and the SMT Verifier Rejects an Empty Sibling in hashes
123 2026-09-24 updateDid and deactivateDid Follow the Signatures of the Specification
124 2026-09-25 The Default Config Works in a Browser: No Preflight, Fresh Chain Data, and a CORS Gateway
125 2026-09-25 config doctor Checks the Request Path of the Commands
126 2026-09-28 The cli Requires Node.js 24.7 for the Native argon2, and the Keystore Checks the Passphrase Once for Each Seal
127 2026-09-28 The Key Flags of create, update, and deactivate, and One Default Key