bip388 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Feenstra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# bip388
+
+TypeScript library for building Bitcoin scripts and BIP-388 wallet policies, with first-class support for Ledger hardware wallets.
+
+## Install
+
+```bash
+npm install bip388
+```
+
+## Features
+
+- **BIP-388 Wallet Policies** - Descriptor templates with key placeholders for Ledger registration
+- **BIP-379 Miniscript** - Typesafe miniscript fragment builders
+- **HTLCs** - Hash Time-Locked Contracts for both Taproot and SegWit
+- **Multisig** - k-of-n multisig for Taproot and SegWit
+
+## Quick Start
+
+### Taproot HTLC
+
+```typescript
+import { taprootHtlc } from "bip388";
+
+const htlc = taprootHtlc({
+  payee: {
+    xpub: "tpub...",
+    fingerprint: "3442193e",
+    originPath: "86'/1'/0'",
+  },
+  payer: {
+    xpub: "tpub...",
+    fingerprint: "3442193e",
+    originPath: "86'/1'/1'",
+  },
+  secretHash: "deadbeef...",
+  timelock: 800000,
+  network: "testnet",
+});
+
+// Address to fund
+console.log(htlc.address);
+
+// BIP-388 policy for Ledger
+console.log(htlc.policy?.template);
+// => tr(@0/**,{and_v(v:sha256(...),pk(@1/**)),and_v(v:after(800000),pk(@2/**))})
+
+// Witness for spending with preimage
+const witness = htlc.witness.secret(signature, preimage);
+
+// Witness for timeout refund
+const witness = htlc.witness.timeout(signature);
+```
+
+### SegWit HTLC
+
+```typescript
+import { segwitHtlc } from "bip388";
+
+const htlc = segwitHtlc({
+  payee: { xpub: "tpub...", fingerprint: "...", originPath: "..." },
+  payer: { xpub: "tpub...", fingerprint: "...", originPath: "..." },
+  secretHash: "deadbeef...",
+  timelock: 800000,
+  network: "testnet",
+});
+
+console.log(htlc.address); // tb1q...
+```
+
+### Taproot Multisig (2-of-3)
+
+```typescript
+import { taprootMultisig } from "bip388";
+
+const multisig = taprootMultisig({
+  threshold: 2,
+  keys: [
+    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
+    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
+    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
+  ],
+  network: "testnet",
+});
+
+console.log(multisig.address);
+console.log(multisig.policy?.template);
+// => tr(@0/**,sortedmulti_a(2,@1/**,@2/**,@3/**))
+
+// Build witness with signatures (empty buffer for non-signers)
+const witness = multisig.witness([sig1, sig2, Buffer.alloc(0)]);
+```
+
+### SegWit Multisig
+
+```typescript
+import { segwitMultisig } from "bip388";
+
+const multisig = segwitMultisig({
+  threshold: 2,
+  keys: [key1, key2, key3],
+  network: "testnet",
+});
+
+console.log(multisig.policy?.template);
+// => wsh(sortedmulti(2,@0/**,@1/**,@2/**))
+```
+
+## Key Types
+
+Keys can be either `XpubKey` (for BIP-388 policy generation) or `RawKey` (just a pubkey):
+
+```typescript
+// XpubKey - enables BIP-388 policy generation
+const xpubKey: XpubKey = {
+  xpub: "tpub...",
+  fingerprint: "3442193e", // master fingerprint
+  originPath: "86'/1'/0'", // derivation path
+  index: 0, // optional, default 0
+  change: 0, // optional, 0=receive, 1=change
+};
+
+// RawKey - no policy generated
+const rawKey: RawKey = {
+  pubkey: "02abc...", // 33-byte compressed or 32-byte x-only
+};
+```
+
+When all keys are `XpubKey`, a `WalletPolicy` is generated for Ledger registration. When using `RawKey`, `policy` will be `null`.
+
+## Miniscript Fragments
+
+Build miniscript expressions directly:
+
+```typescript
+import { pk, sha256, and_v, or_i, older, after, multi_a } from "bip388";
+
+// pk(@0/**)
+pk(keyPlaceholder(0));
+
+// and_v(v:sha256(H),pk(@0/**))
+and_v(sha256("deadbeef..."), pk(keyPlaceholder(0)));
+
+// or_i(and_v(v:sha256(H),pk(@0/**)),and_v(v:after(144),pk(@1/**)))
+or_i(
+  and_v(sha256("..."), pk(keyPlaceholder(0))),
+  and_v(after(144), pk(keyPlaceholder(1))),
+);
+
+// multi_a(2,@0/**,@1/**,@2/**) - Taproot
+multi_a(2, [keyPlaceholder(0), keyPlaceholder(1), keyPlaceholder(2)]);
+```
+
+## Low-Level Scripts
+
+For direct Bitcoin Script building:
+
+```typescript
+import {
+  pkScript,
+  pkhScript,
+  multiScript,
+  cltvScript,
+  csvScript,
+} from "bip388";
+
+// <pubkey> OP_CHECKSIG
+pkScript(pubkey);
+
+// OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG
+pkhScript(pubkey);
+
+// OP_2 <key1> <key2> <key3> OP_3 OP_CHECKMULTISIG
+multiScript(2, [key1, key2, key3]);
+
+// <time> OP_CHECKLOCKTIMEVERIFY OP_DROP <pubkey> OP_CHECKSIG
+cltvScript(pubkey, locktime);
+
+// <blocks> OP_CHECKSEQUENCEVERIFY OP_DROP <pubkey> OP_CHECKSIG
+csvScript(pubkey, blocks);
+```
+
+## API Reference
+
+### Pattern Builders
+
+| Function                  | Description                                |
+| ------------------------- | ------------------------------------------ |
+| `taprootHtlc(params)`     | Taproot HTLC with secret and timeout paths |
+| `segwitHtlc(params)`      | SegWit P2WSH HTLC                          |
+| `taprootMultisig(params)` | Taproot k-of-n multisig                    |
+| `segwitMultisig(params)`  | SegWit P2WSH k-of-n multisig               |
+
+### BIP-388 Builders
+
+| Function               | Description                            |
+| ---------------------- | -------------------------------------- |
+| `buildTaprootPolicy()` | Build a `tr()` wallet policy           |
+| `buildSegwitPolicy()`  | Build a `wsh()` wallet policy          |
+| `keyPlaceholder(n)`    | Create `@n/**` key placeholder         |
+| `formatKeyInfo()`      | Format key as `[fingerprint/path]xpub` |
+
+### Miniscript Fragments
+
+| Function                 | Description               |
+| ------------------------ | ------------------------- |
+| `pk(key)`                | Public key check          |
+| `sha256(hash)`           | SHA256 preimage check     |
+| `and_v(left, right)`     | Verify AND                |
+| `or_i(left, right)`      | IF/ELSE OR                |
+| `older(blocks)`          | Relative timelock (CSV)   |
+| `after(time)`            | Absolute timelock (CLTV)  |
+| `multi(k, keys)`         | k-of-n multisig (SegWit)  |
+| `multi_a(k, keys)`       | k-of-n multisig (Taproot) |
+| `sortedmulti(k, keys)`   | Sorted k-of-n (SegWit)    |
+| `sortedmulti_a(k, keys)` | Sorted k-of-n (Taproot)   |
+
+## License
+
+MIT