Skip to content

Commit fe278b2

Browse files
macgyver13macgyver13
committed
BIP-375: update documentation
Update Test Vectors section Add README.md to explain validation tooling and dependencies
1 parent e9f045c commit fe278b2

2 files changed

Lines changed: 182 additions & 1 deletion

File tree

‎bip-0375.mediawiki‎

Lines changed: 150 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,156 @@ Silent payment capable PSBTs are backwards compatible with PSBTv2 once all outpu
249249

250250
==Test Vectors==
251251

252-
Todo
252+
A [[bip-0375/bip375_test_vectors.json|collection of test vectors in JSON format]] is provided. Each test vector contains a base64-encoded PSBT string, which alone can be used to verify sending Silent Payments with PSBTs.
253+
Validation is performed in 4 sequential checks. This [[bip-0375/validator/validate_psbt.py|Python implementation]] demonstrates the validation logic for each:
254+
255+
# '''PSBT Structure''' - Verify BIP375 field requirements
256+
# '''ECDH Coverage''' - Verify ECDH share presence and correctness using BIP374 DLEQ
257+
# '''Input Eligibility''' - Verify input constraints when silent payment outputs are present
258+
# '''Output Scripts''' - Verify output scripts match silent payment derivation
259+
260+
Valid PSBTs are organized into 2 categories:
261+
# '''Can Finalize''' - Signed and ready to finalize
262+
# '''In Progress''' - Incomplete but valid
263+
264+
Use the provided [[bip-0375/test_runner.py|test runner]] to validate each test vector. See the [[bip-0375/README.md|README]] for more details.
265+
266+
===Invalid PSBTs===
267+
268+
{|
269+
! Category
270+
! Description
271+
|-
272+
| PSBT Structure
273+
| missing PSBT_OUT_SP_V0_INFO field when PSBT_OUT_SP_V0_LABEL set
274+
|-
275+
| PSBT Structure
276+
| incorrect byte length for PSBT_OUT_SP_V0_INFO field
277+
|-
278+
| PSBT Structure
279+
| incorrect byte length for PSBT_IN_SP_ECDH_SHARE field
280+
|-
281+
| PSBT Structure
282+
| incorrect byte length for PSBT_IN_SP_DLEQ field
283+
|-
284+
| PSBT Structure
285+
| PSBT_GLOBAL_TX_MODIFIABLE field is non-zero when PSBT_OUT_SCRIPT set for sp output
286+
|-
287+
| PSBT Structure
288+
| missing PSBT_OUT_SCRIPT field when sending to non-sp output
289+
|-
290+
| PSBT Structure
291+
| empty PSBT_OUT_SCRIPT field when sending to non-sp output
292+
|-
293+
| ECDH Coverage
294+
| only one ineligible P2MS input when PSBT_OUT_SCRIPT set for sp output
295+
|-
296+
| ECDH Coverage
297+
| missing PSBT_IN_SP_ECDH_SHARE field for input 0 when PSBT_OUT_SCRIPT set for sp output
298+
|-
299+
| ECDH Coverage
300+
| missing PSBT_IN_SP_DLEQ field for input when PSBT_IN_SP_ECDH_SHARE set
301+
|-
302+
| ECDH Coverage
303+
| missing PSBT_GLOBAL_SP_DLEQ field when PSBT_GLOBAL_SP_ECDH_SHARE set
304+
|-
305+
| ECDH Coverage
306+
| invalid proof in PSBT_IN_SP_DLEQ field
307+
|-
308+
| ECDH Coverage
309+
| invalid proof in PSBT_GLOBAL_SP_DLEQ field
310+
|-
311+
| ECDH Coverage
312+
| missing PSBT_IN_BIP32_DERIVATION field for input when PSBT_IN_SP_DLEQ set
313+
|-
314+
| ECDH Coverage
315+
| output 1 missing ECDH share for scan key with one input / three sp outputs (different scan keys)
316+
|-
317+
| ECDH Coverage
318+
| input 1 missing ECDH share for output 1 with two inputs / two sp outputs (different scan keys)
319+
|-
320+
| ECDH Coverage
321+
| input 1 missing ECDH share for scan key with two inputs / one sp output
322+
|-
323+
| Input Eligibility
324+
| segwit version greater than 1 in transaction inputs with sp output
325+
|-
326+
| Input Eligibility
327+
| non-SIGHASH_ALL signature on input with sp output
328+
|-
329+
| Output Scripts
330+
| P2TR input with NUMS internal key cannot derive sp output
331+
|-
332+
| Output Scripts
333+
| PSBT_OUT_SCRIPT does not match derived sp output
334+
|-
335+
| Output Scripts
336+
| two sp outputs (same scan / different spend keys) not sorted lexicographically by spend key
337+
|-
338+
| Output Scripts
339+
| k values assigned to wrong output indices with three sp outputs (same scan / spend keys)
340+
|}
341+
342+
===Valid PSBTs===
343+
344+
{|
345+
! State
346+
! Description
347+
|-
348+
| Can Finalize
349+
| one input single-signer
350+
|-
351+
| Can Finalize
352+
| two inputs single-signer using global ECDH share
353+
|-
354+
| Can Finalize
355+
| two inputs single-signer using per-input ECDH shares
356+
|-
357+
| Can Finalize
358+
| two inputs / two sp outputs with mixed global and per-input ECDH shares
359+
|-
360+
| Can Finalize
361+
| one input / one sp output with both global and per-input ECDH shares
362+
|-
363+
| Can Finalize
364+
| three sp outputs (different scan keys) with multiple global ECDH shares
365+
|-
366+
| Can Finalize
367+
| one P2WPKH input / two mixed outputs - labeled sp output and BIP 32 change
368+
|-
369+
| Can Finalize
370+
| one input / two sp outputs - output 0 has no label / output 1 uses label=0 convention for sp change
371+
|-
372+
| Can Finalize
373+
| two sp outputs - output 0 uses label=3 / output 1 uses label=1
374+
|-
375+
| Can Finalize
376+
| two mixed input types - only eligible inputs contribute ECDH shares (P2SH excluded)
377+
|-
378+
| Can Finalize
379+
| two mixed input types - only eligible inputs contribute ECDH shares (NUMS internal key excluded)
380+
|-
381+
| Can Finalize
382+
| three sp outputs (same scan key) - each output has distinct k value
383+
|-
384+
| Can Finalize
385+
| three sp outputs (same scan key) / two regular outputs - k values assigned independently of output index
386+
|-
387+
| In Progress
388+
| two P2TR inputs, neither is signed
389+
|-
390+
| In Progress
391+
| one P2TR input / one sp output with no ECDH shares when PSBT_OUT_SCRIPT field is not set
392+
|-
393+
| In Progress
394+
| two inputs / one sp output, input 1 missing ECDH share when PSBT_OUT_SCRIPT field is not set
395+
|-
396+
| In Progress
397+
| one input / two sp outputs, input 0 missing ECDH share for output 0 when PSBT_OUT_SCRIPT field is not set
398+
|-
399+
| In Progress
400+
| large PSBT with nine mixed inputs / six outputs - some inputs signed
401+
|}
253402

254403
==Rationale==
255404

‎bip-0375/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# BIP-375 Validation Reference
2+
3+
A reference validation implementation for BIP-375: Sending Silent Payments with PSBTs.
4+
5+
## Core Files
6+
- **`validator/bip352_crypto.py`** - Silent payment output script derivation
7+
- **`validator/inputs.py`** - PSBT input utility functions
8+
- **`validator/psbt_bip375.py`** - BIP-375 specific PSBT/PSBTMap extensions
9+
- **`validator/validate_psbt.py`** - Main BIP-375 validation functions
10+
- **`test_runner.py`** - Test infrastructure (executable)
11+
12+
## Dependencies
13+
- **`deps/bitcoin_test/psbt.py`** - Bitcoin test framework PSBT module - [PR #21283](https://github.com/bitcoin/bitcoin/pull/21283)
14+
- **`deps/bitcoin_test/messages.py`** - Bitcoin test framework primitives and message structures
15+
- **`deps/dleq.py`** - Reference DLEQ implementation from BIP-374
16+
- **`deps/secp256k1lab/`** - vendored copy of [secp256k1lab](https://github.com/secp256k1lab/secp256k1lab/commit/44dc4bd893b8f03e621585e3bf255253e0e0fbfb) library at version 1.0.0
17+
18+
## Testing
19+
20+
### Run Tests
21+
22+
```bash
23+
python test_runner.py # Run all tests
24+
python test_runner.py -v # Verbose mode with detailed validation status
25+
python test_runner.py -vv # More verbose with validation check failure reason
26+
27+
python test_runner.py -f vectors.json # Use custom test vector file
28+
```
29+
30+
### Generating Test Vectors
31+
32+
Test vectors were generated using [test_generator.py](https://github.com/macgyver13/bip375-test-generator/)

0 commit comments

Comments
 (0)