diff --git a/.gitignore b/.gitignore index d939d2a572..3e503ce3ef 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,7 @@ bip-0174/coinjoin-workflow.pdf bip-0174/multisig-workflow.aux bip-0174/multisig-workflow.log bip-0174/multisig-workflow.pdf + +# BIP-445 research materials sanitation +# Ignore local/generated copies of the internal research dossier. +docs/bip445-research/ diff --git a/docs/bip445-research/BIP445-SOURCE-RESEARCH-REPORT.md b/docs/bip445-research/BIP445-SOURCE-RESEARCH-REPORT.md new file mode 100644 index 0000000000..e52be8dd9c --- /dev/null +++ b/docs/bip445-research/BIP445-SOURCE-RESEARCH-REPORT.md @@ -0,0 +1,169 @@ +# BIP-445 Source-Evidence Research Report + +**Status:** READ-ONLY RESEARCH ARTIFACT — NOT A PUBLIC COMMENT + +This document records findings from a read-only inspection of `bitcoin/bips` PR #2070 and related sources. It corrects earlier hypotheses and identifies which technical surfaces are supported by current source. + +--- + +## 1. Scope + +- Primary PR: `bitcoin/bips#2070` +- PR head: `siv2r:bip-frost-signing` +- PR head SHA: `f7de4568f2497b40bd85bb8fb40da32c05b68d72` +- Fork private dossier: `vitrixLab/bips#1` +- No upstream writes, comments, or PRs were performed. + +--- + +## 2. Methodology + +LLM-generated hypotheses were used only as starting points. Each hypothesis was independently verified against normative BIP text, reference implementation, test-vector architecture, and related BIPs/RFCs before being recorded as a finding. + +Evidence states used: + +- `VERIFIED` — direct source evidence found and checked +- `SUPPORTED` — strong documentary support, not fully independently reproduced +- `UNVERIFIED` — plausible but insufficient evidence +- `UNKNOWN` — evidence insufficient to determine +- `CONFLICT` — sources disagree or source does not support prior claim +- `WITHDRAWN` — prior public/private claim removed after negative evidence + +--- + +## 3. Key Verified Findings + +### 3.1 Nonce coefficient `b` is signer-set bound via count prefix + +Specification and implementation use: + +```text +hash_BIP0445/noncecoef( + bytes(4, u) || + ser_ids || + aggnonce || + xbytes(Q) || + m +) +``` + +Changelog `0.8.0` explicitly records adding the signer-count prefix to prevent ambiguous `(ids, aggnonce, Q, m)` concatenation. + +**Status:** `VERIFIED` + +--- + +### 3.2 Deterministic signing binds `my_id` and signer identifiers + +Deterministic nonce includes: + +```text +secshare_ +my_id +len(ids) +serialize_ids(ids) +aggothernonce +... +``` + +Changelog `0.4.2` records binding `my_id` and signer IDs. + +**Status:** `VERIFIED` + +--- + +### 3.3 Error/blame boundary is explicit + +- `ValueError` — malformed setup/config input, such as invalid `SignersContext`. +- `InvalidContributionError` — malicious runtime protocol contributions by signer or coordinator. + +**Status:** `VERIFIED` + +--- + +### 3.4 Arbitrary tweaks are explicitly an open security question + +Specification distinguishes Bitcoin-derived tweaks from arbitrary adversarial tweaks and states that accepting arbitrary tweaks may negatively affect security. The authors explicitly identify this as an open question. + +**Status:** `VERIFIED` as a normative statement. It is not evidence of an actual exploit. + +--- + +### 3.5 BIP-340 challenge is inherited + +Challenge uses: + +```text +BIP0340/challenge(R.x-only || Q.x-only || msg) +``` + +This preserves Taproot/BIP340 compatibility. + +**Status:** `VERIFIED` + +--- + +### 3.6 ChillDKG interoperability is already tracked + +`BlockstreamResearch/bip-frost-dkg#157` explicitly tracks aligning `DKGOutput` with BIP-445 expected input. + +**Status:** `VERIFIED` as an existing issue. It is not a novel research discovery. + +--- + +## 4. Withdrawn / Rejected Claims + +### 4.1 Absent vs zero-length message semantics + +Earlier hypothesis that BIP-445 must distinguish an absent message from a zero-length message is not supported. + +Maintainer response: "The message is a mandatory argument and thus always present." + +Current source confirms `m` is a mandatory byte-array session parameter. `NonceGen`'s optional `msg` is a separate defense-in-depth input. + +**Status:** `WITHDRAWN` / `CONFLICT` with earlier claim. + +--- + +## 5. Evidence Table + +| Claim | Source | Status | +|---|---|---| +| Nonce coefficient includes signer count prefix | `bip-0445.md`, implementation | `VERIFIED` | +| Deterministic nonce binds signer subset | implementation, changelog 0.4.2 | `VERIFIED` | +| Serialization ambiguity addressed | changelog 0.8.0 | `VERIFIED` | +| Error/blame semantics specified | implementation | `VERIFIED` | +| Arbitrary tweak security open | spec tweaking section | `VERIFIED` | +| BIP340 challenge inherited | spec + BIP340 | `VERIFIED` | +| ChillDKG alignment tracked | issue #157 | `VERIFIED` / non-novel | +| Absent vs empty message defect | spec + maintainer | `WITHDRAWN` | +| Exact test vector count (68 → 250) | vectors summary | `UNKNOWN` without independent count | +| Coordinator can cause abort | spec | `VERIFIED` | +| Coordinator can forge | spec normative claim | `VERIFIED` as claim | +| BIP327 tweak context reused | spec | `VERIFIED` | + +--- + +## 6. Source Paths Used + +```text +bip-0445.md +bip-0445/python/frost_ref/signing.py +bip-0445/python/gen_vectors.py +bip-0445/python/vectors/* +bip-0340.mediawiki +bip-0327.mediawiki +RFC 9591 +``` + +--- + +## 7. Repository Safety + +- `bitcoin/bips`: no writes +- PR #2070: no comments/reviews +- `vitrixLab/bips`: only dossier files updated +- No merge +- No upstream contribution + +This report is private research, not a public BIP comment. diff --git a/docs/bip445-research/FUTURE-RESEARCH-ROADMAP.md b/docs/bip445-research/FUTURE-RESEARCH-ROADMAP.md new file mode 100644 index 0000000000..4651a9397e --- /dev/null +++ b/docs/bip445-research/FUTURE-RESEARCH-ROADMAP.md @@ -0,0 +1,76 @@ +# Future BIP-445 Research Roadmap + +## Phase A — Security hardening + +### A1. Formal coordinator/threat-model section + +Document the coordinator's capabilities, honest-but-curious versus malicious behavior, participant assumptions, identifiable-abort conditions, and the security consequences of coordinator manipulation. + +### A2. Signer-subset/session-binding regression vectors + +Create permanent regression vectors covering signer-set changes, session separation, deterministic nonce derivation, and cross-session transcript binding. The objective is to make the signer-subset invariant executable rather than merely descriptive. + +### A3. Serialization/domain-separation table + +Build a table for every hash input and transcript component showing its fields, ordering, framing, length/count encoding, and domain-separation purpose. Use it to detect ambiguous concatenations systematically. + +### A4. Explicit arbitrary-tweak security boundary + +State exactly which tweak classes are covered by the construction and which attacker-supplied or arbitrary tweak scenarios require separate analysis. Avoid claims broader than the demonstrated model. + +### A5. Formal identifiable-abort assumptions + +Specify when an abort is attributable to the coordinator, a signer, malformed input, or an unavoidable protocol condition, and what participants can actually identify from the available evidence. + +## Phase B — Interoperability + +### B1. Cross-implementation test harness + +Build a harness that compares independent implementations over identical transcripts, signer subsets, messages, tweaks, failures, and serialization boundaries. + +### B2. Canonical conformance vectors + +Define a canonical set of positive, negative, boundary, and adversarial vectors. Coverage should be organized by protocol property rather than only total vector count. + +### B3. C/Rust/C++ API mapping guidance + +Map the specification's conceptual objects and operations onto representative C, Rust, and C++ APIs, documenting ownership, serialization, error handling, and type-boundary assumptions. + +### B4. Error/blame semantics specification + +Develop explicit guidance separating setup/configuration failures from malicious or invalid runtime contributions, including how an implementation should expose or suppress blame information. + +### B5. Reference implementation ↔ pseudocode consistency checks + +Systematically compare pseudocode, normative prose, reference implementation, and tests so that semantic drift is detected before it becomes an interoperability issue. + +## Phase C — Ecosystem architecture + +### C1. Reusable tweak-context abstraction + +Research whether Bitcoin signing BIPs can share a common tweak-context abstraction that preserves explicit domain separation, signer/session binding, and clearly scoped threat assumptions. + +### C2. Arbitrary/agnostic tweaking research + +Investigate broader arbitrary or agnostic tweaking models without assuming that results from one construction transfer automatically to another. + +### C3. Expanded ROAST/FROST integration guidance + +Map the relevant interaction points among BIP-445, FROST, ROAST, DKG outputs, and signing-session state. Focus on concrete interface and transcript compatibility rather than conceptual similarity alone. + +### C4. Additional implementations and independent audits + +Seek independent implementations and audit perspectives before making strong ecosystem-level security or interoperability claims. + +## Research gate for all phases + +Each completed phase should produce evidence that can survive the same public-comment gate: + +- exact specification reference; +- implementation/API reference; +- reproducible trace, vector, or test; +- prior-art/tracking check; +- explicit falsification attempt; and +- clear evidence state. + +The roadmap therefore treats documentation quality and verification discipline as part of the technical work, not as a separate editorial step. diff --git a/docs/bip445-research/LESSONS-LEARNED.md b/docs/bip445-research/LESSONS-LEARNED.md new file mode 100644 index 0000000000..bc7287077b --- /dev/null +++ b/docs/bip445-research/LESSONS-LEARNED.md @@ -0,0 +1,45 @@ +# Lessons Learned + +## 1. LLM output is a hypothesis generator, not protocol evidence + +LLM-assisted review is useful for finding candidate questions, edge cases, and relationships across documents. It is not sufficient evidence for a public protocol criticism. Every candidate claim requires independent verification against the normative specification, implementation/API behavior, and a concrete reproducible trace or vector. + +## 2. Review volume does not substitute for technical depth + +A large number of comments can create noise without increasing review quality. Future review should prioritize a few technically substantial findings over broad issue enumeration. + +## 3. Withdrawn claims should not be defended + +Once a claim is contradicted by the actual interface or implementation, the correct action is to withdraw it and record why it failed. Continuing to defend a falsified hypothesis weakens both the review and the evidence process. + +## 4. A non-novel point is not necessarily a wrong point + +The ChillDKG interoperability observation was valid as an interoperability concern, but it was already tracked in `BlockstreamResearch/bip-frost-dkg#157`. Future review must distinguish **incorrect**, **already tracked**, **already fixed**, and **newly demonstrated**. + +## 5. Verify exact API semantics before semantic critique + +The absent-versus-empty-message proposal failed because the message argument is mandatory and always present. Before constructing a semantic distinction, identify the precise function signature, normative argument requirements, and implementation path. + +## 6. Future public participation should clear a higher evidence bar + +A future public comment should be grounded in one extremely hard-to-dismiss technical point: exact specification text, exact implementation behavior, a minimal reproduction or vector, and an explanation of why existing tracking or documentation does not already resolve it. + +## 7. Research state must remain explicit + +The dossier uses evidence states so that an interesting hypothesis cannot silently become a finding. `UNVERIFIED`, `UNKNOWN`, and `CONFLICT` are legitimate research states and should remain visible until the evidence changes. + +## 8. The practical operating model + +The resulting working model is: + +```text +Generate broadly with LLM assistance + ↓ +Narrow aggressively through falsification + ↓ +Verify specification + implementation + trace + ↓ +Check prior art / existing tracking + ↓ +Publish only durable findings +``` diff --git a/docs/bip445-research/MAINTAINER-FEEDBACK.md b/docs/bip445-research/MAINTAINER-FEEDBACK.md new file mode 100644 index 0000000000..928d6b9a7e --- /dev/null +++ b/docs/bip445-research/MAINTAINER-FEEDBACK.md @@ -0,0 +1,34 @@ +# Maintainer Feedback + +This record preserves the significant maintainer feedback that changed the research process. Quotes below are recorded from the review discussion as supplied for this dossier; they are retained for methodological analysis, not to imply endorsement of this document. + +## Admin 1 + +> “The message is a mandatory argument and thus always present.” + +**Classification:** Technical correction. + +The response invalidates the proposed absent-versus-zero-length message distinction because the interface requires the message argument to be present. The lesson is that an intuitive semantic distinction cannot be treated as a protocol issue without first checking the exact API contract and normative argument requirements. + +The same review history also identified the ChillDKG interoperability point as an already-tracked matter rather than a new issue. That makes the contribution non-novel on that point, not necessarily technically wrong. + +## Admin 2 + +> “the contributions from @vitrixLab read like low-quality slop to me.” + +> “Please either step up the quality of your contributions or cease posting in this repository.” + +**Classification:** Process/credibility warning. + +The practical response is to pause public participation and raise the verification threshold. The warning is treated as feedback on contribution quality and review process, not as evidence that every substantive research point was incorrect. + +## Methodological response + +The appropriate response to this feedback is not to defend withdrawn claims. Instead: + +1. preserve the correction in the evidence record; +2. distinguish invalid claims from valid but non-novel observations; +3. verify future claims against normative text and implementation before publication; and +4. return to public review only with a small number of technically hard-to-dismiss points. + +No maintainer endorsement of this dossier is claimed or implied. diff --git a/docs/bip445-research/METHODOLOGY.md b/docs/bip445-research/METHODOLOGY.md new file mode 100644 index 0000000000..4d4b17aae7 --- /dev/null +++ b/docs/bip445-research/METHODOLOGY.md @@ -0,0 +1,90 @@ +# Corrected BIP-445 Research Methodology + +## Core rule + +LLM-assisted hypothesis generation must be separated from independent technical verification: + +```text +LLM-assisted hypothesis generation + ↓ +Independent verification against normative text, implementation, and protocol traces + ↓ +Only verified findings become public comments +``` + +The purpose of this separation is not to prohibit LLM assistance. It is to prevent plausible language-model inferences from being promoted directly into claims about a protocol's security, API semantics, interoperability, or correctness. + +## Public-comment gate + +For every proposed public BIP-445 comment, answer all of the following: + +1. **Exact normative target:** What exact normative text is being challenged? +2. **Implementation/API evidence:** What exact implementation or API behavior establishes the claimed problem? +3. **Concrete trace:** What concrete input/output pair, transcript, test vector, or protocol trace demonstrates it? +4. **Specification status:** Is the behavior genuinely unspecified, or is the criticism only an expectation that is not stated by the specification? +5. **Existing work:** Has the matter already been discussed, fixed, or tracked elsewhere? +6. **Expert falsifiability:** Could an expert familiar with the code immediately falsify the claim? +7. **Minimal reproduction:** Can a minimal reproducible example be supplied? + +If any answer is missing or weak, the item remains **private research** and is not posted as public protocol criticism. + +## Observation versus inference + +Review-derived observations and independent inferences must remain distinct. + +- A **review-derived observation** is directly grounded in an observed specification passage, implementation behavior, test vector, or existing discussion. +- An **independent inference** is a hypothesis derived from those materials but requiring additional verification. + +An inference can be useful research even when it is ultimately false. The error occurs when the inference is represented publicly as though it were already established. + +## Evidence state vocabulary + +| State | Meaning | +|---|---| +| `VERIFIED` | Directly established by normative text, implementation, and/or a reproducible technical trace sufficient for the claim. | +| `SUPPORTED` | Strongly supported by authoritative discussion or evidence, but not necessarily independently reproduced in full. | +| `UNVERIFIED` | Plausible hypothesis lacking sufficient evidence. Remains private. | +| `UNKNOWN` | Available evidence is insufficient to determine the claim. | +| `CONFLICT` | Authoritative sources or observations disagree; investigation is required. | +| `OBSOLETE` | The claim may once have been applicable but no longer reflects the current design or implementation. | +| `CURRENT` | The statement reflects the currently observed design state after verification; it is not itself a substitute for evidence. | + +These states must not be collapsed into one another. + +> **UNVERIFIED ≠ VERIFIED** +> +> **UNKNOWN ≠ FAILURE** +> +> **CONFLICT ≠ SUCCESS** + +## Verification sequence + +### 1. Read the normative specification + +Quote or identify the exact text that allegedly creates the issue. Determine whether the disputed behavior is mandatory, optional, undefined, or simply absent from the document. + +### 2. Inspect implementation/API behavior + +Map the specification statement to the relevant function, argument, data structure, serialization routine, or error path. Record what the implementation actually does rather than what it appears likely to do. + +### 3. Reproduce the behavior + +Use the smallest concrete example capable of distinguishing the proposed failure mode from normal behavior. Prefer deterministic vectors, transcripts, or tests over prose reasoning. + +### 4. Search existing discussion and tracking + +Determine whether the point is already fixed, clarified, accepted as a design trade-off, or tracked in another project or issue. A non-novel observation can still be useful research, but it should not be represented as a new discovery. + +### 5. Attempt falsification + +Actively try to disprove the candidate claim. In particular, ask what a maintainer or implementation expert would point to as the shortest counterexample. + +### 6. Decide publication status + +Only a claim that survives the preceding checks should become a public review comment. Otherwise retain it as a private research item with its current evidence state and the missing verification step recorded. + +## Review-quality objective + +The objective is not to maximize the number of comments. The objective is to produce a small number of technically durable observations that are difficult to dismiss because the specification text, implementation behavior, and concrete evidence all align. + +A future public review should therefore optimize for **depth, reproducibility, and falsifiability**, rather than comment volume. diff --git a/docs/bip445-research/README.md b/docs/bip445-research/README.md new file mode 100644 index 0000000000..c634f55bc3 --- /dev/null +++ b/docs/bip445-research/README.md @@ -0,0 +1,33 @@ +# BIP-445 Research Methodology Dossier + +## Purpose + +This directory is an internal research dossier documenting methodology, evidence status, review findings, maintainer feedback, lessons learned, and future research directions related to BIP-445 and review of bitcoin/bips PR #2070. + +This is **not an official BIP contribution**. It is a private evidence record maintained in the `vitrixLab/bips` fork. No merge to `bitcoin/bips` is implied or requested by this dossier. + +The dossier is based on review of PR #2070 and its associated discussion. Maintainer feedback exposed weaknesses in presenting LLM-assisted hypotheses as public protocol criticism without sufficient independent verification. The resulting response is a pause in public commenting and a pivot to private, evidence-first research. + +## Scope + +The dossier records: + +- the corrected methodology for LLM-assisted protocol review; +- technical findings and their evidence status; +- maintainer responses and their significance for review quality; +- lessons for future public participation; and +- a staged roadmap for security, interoperability, and ecosystem research. + +## Evidence discipline + +LLM output is treated as hypothesis generation only. A candidate observation does not become a public claim until it has been checked against normative text, implementation/API behavior, and concrete protocol evidence. + +The statuses used throughout this dossier are deliberately conservative: `VERIFIED`, `SUPPORTED`, `UNVERIFIED`, `UNKNOWN`, `CONFLICT`, `OBSOLETE`, and `CURRENT`. + +## Repository boundary + +All work represented by this dossier is confined to the `vitrixLab/bips` fork. The intended publication unit is a fork-level draft PR only. No upstream PR, issue, branch, or discussion is modified by this documentation. + +## Reports + +- [BIP-445 Source-Evidence Research Report](BIP445-SOURCE-RESEARCH-REPORT.md) diff --git a/docs/bip445-research/REVIEW-FINDINGS.md b/docs/bip445-research/REVIEW-FINDINGS.md new file mode 100644 index 0000000000..b09164912a --- /dev/null +++ b/docs/bip445-research/REVIEW-FINDINGS.md @@ -0,0 +1,48 @@ +# BIP-445 Review Findings + +This file separates technically useful observations from claims that were rejected, already tracked, or remain questions. Status is intentionally conservative. + +| Finding | Evidence status | Research record | +|---|---|---| +| **Coordinator trust boundaries:** identifiable aborts may depend on coordinator honesty. | `SUPPORTED` | Supported by the review discussion. The issue is retained as a threat-model/design question rather than stated as a demonstrated protocol failure. | +| **Signer-set binding:** deterministic nonce generation must bind to the active signer subset to prevent cross-session secret recovery. | `CURRENT` | The point was fixed by the PR author and is retained here as a design rule established through the review process. | +| **Serialization/domain separation:** noncecoef concatenation had an ambiguity risk and was fixed by adding a signer-count prefix. | `VERIFIED` | Recorded as a concrete discussion fact: the serialization concern was real and the author changed the construction. | +| **Arbitrary tweaks:** attacker-supplied tweaks raise an open security question; the statement needs a bounded security boundary. | `CURRENT` | Adopted as a clarification in the PR. The research position is to avoid overgeneralizing the security guarantee beyond the specified tweak model. | +| **Interoperability boundary with ChillDKG:** DKGOutput alignment is relevant to interoperability. | `SUPPORTED` | Valid interoperability observation, but already tracked in `BlockstreamResearch/bip-frost-dkg#157`; therefore non-novel rather than a new upstream finding. | +| **Message semantics:** an absent-vs-zero-length message distinction was proposed. | `OBSOLETE` | Withdrawn after maintainer correction. The message argument is mandatory and always present, so the proposed absent-message distinction does not apply to the reviewed interface. | +| **Error/blame semantics:** distinguish setup errors from malicious runtime contributions. | `SUPPORTED` | Retained as design guidance for specification and implementation clarity; it should be tied to concrete failure paths before becoming a normative criticism. | +| **Test-vector expansion:** coverage increased from 68 to 250 cases. | `VERIFIED` | Factual observation from the review history. The remaining research question is whether the vectors provide structured conformance coverage across all relevant dimensions. | + +## Interpretation notes + +### Coordinator trust boundaries + +The useful research question is not simply whether a coordinator can cause an identifiable abort. The stronger question is which assumptions the protocol makes about coordinator behavior, what participants can detect, and which failure modes are attributable to coordination versus participant inputs. + +### Signer-set binding + +The corrected design rule is that deterministic nonce material must be bound to the actual signer subset/session context relevant to the signing transcript. The point is retained as a security invariant, not as an unresolved criticism. + +### Serialization and domain separation + +The noncecoef concatenation issue demonstrates why hash-input structure should be audited explicitly. Any concatenation that can admit ambiguous decompositions should be represented with explicit framing, length, count, or another unambiguous domain-separation mechanism. + +### Arbitrary tweaks + +The appropriate future question is the exact security boundary of attacker-supplied tweaks. The dossier does not assert that arbitrary tweaking is universally insecure or universally safe. It records the need for a bounded statement tied to the actual construction and threat model. + +### ChillDKG interoperability + +The DKGOutput alignment point is retained because interoperability is important, while explicitly recording that it is already tracked elsewhere. The correct lesson is that a valid observation may still be non-novel. + +### Message semantics + +The absent-versus-empty-message hypothesis is intentionally retained only as a failure-analysis example. It is not a current finding. The mandatory-message-interface correction supersedes the earlier inference. + +### Error and blame semantics + +A useful specification should make clear which failures occur during setup and which can arise from malicious or invalid runtime contributions. This can improve implementation behavior and test design without necessarily constituting a protocol defect. + +### Test vectors + +The increase from 68 to 250 cases is useful evidence of expanded testing. A separate conformance matrix is still warranted so coverage can be evaluated by property, signer-set cardinality, transcript state, serialization boundary, tweak class, and expected failure mode rather than by raw vector count alone.