@hypawave/sdk 0.3.0 → 0.4.1

package/AGENTS.md

@@ -91,12 +91,12 @@ For Paths 3a / 3b, there is no SDK — use raw HTTP with pubkey signatures per t
 
 ## Non-negotiables
 
-1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this.
+1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this. The wallet also needs **funded outbound liquidity ≥ amount + fees** — a fresh/empty node or "fee-credit" balance can't pay even when total balance ≥ price. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — only funding is needed.
 2. **Confirm before unlocking.** Always submit preimage to the confirm endpoint before requesting file keys or download URLs.
 3. **Funds flow buyer→seller directly.** Never route principal through any Hypawave endpoint. Only activation fees (small, Hypawave-issued bolt11s) go to Hypawave.
 4. **Honor `terms_hash`** on Path 3b offers. If the server returns `409 terms_changed`, re-read the offer before paying.
 5. **Do not invent endpoints.** If a field or path is not in openapi.json, it does not exist.
-6. **Encrypt client-side** for file attachments. AES-256-GCM. Hypawave never sees plaintext.
+6. **Encrypt client-side** for file attachments. AES-256-GCM. Hypawave never sees plaintext. `storeFile` requires `ciphertext_sha256` (SHA-256 hex of the bytes you upload) — Hypawave verifies + seals it so buyers can verify what they download.
 
 ## When you hit something the manual doesn't cover
 

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to `@hypawave/sdk` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1]
+
+### Changed
+- Docs only — no API changes. Clarified payer-wallet requirements in `README.md`,
+  `AGENTS.md`, and the bundled `skills/hypawave/SKILL.md`: the wallet needs
+  **funded outbound liquidity ≥ amount + fees** (a fresh/empty node or Phoenix
+  "fee-credit" balance can't pay even when total balance ≥ price), and for small
+  or test payments a **custodial wallet over NWC (e.g. Coinos)** avoids channel
+  setup entirely — only funding is needed. Mirrors the buyer-wallet guidance in
+  `llms.txt`.
+
+## [0.4.0]
+
+### Added
+- `StoreFileParams.ciphertext_sha256` (**required**) — the lowercase-hex SHA-256
+  of the exact ciphertext you upload. Hypawave verifies it against the stored
+  bytes and seals them at the first bolt11 mint, and returns it at key retrieval
+  so buyers can verify downloaded bytes before decrypting (content integrity /
+  anti-bait-and-switch).
+
+### Changed
+- `storeFile()` now requires `ciphertext_sha256`. Compute `sha256` over the same
+  bytes you PUT to the presigned upload URL and pass it through. Calls without it
+  are rejected by the API with `400 validation_error`.
+
 ## [0.3.0]
 
 ### Added

package/README.md

@@ -44,6 +44,8 @@ This SDK requires **programmable Lightning infrastructure** that exposes the pre
 
 - LND, CLN, Alby API, LNbits, NWC, or equivalent
 
+The wallet also needs **funded outbound liquidity ≥ amount + routing fees** — a fresh/empty node or a "fee-credit" balance (e.g. Phoenix below the channel-open threshold) cannot pay even when total balance ≥ price; only spendable channel liquidity counts. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — no liquidity minimum, only funding is needed.
+
 **Consumer wallets (Wallet of Satoshi, Phoenix, etc.) do not reliably expose the preimage and are not suitable for agent integrations.** Files and data will not unlock without a preimage.
 
 ## Install
@@ -384,7 +386,7 @@ Additional methods available — see types for full signatures, or [openapi.json
 - `listInvoices(params?)` — list invoices with filters and pagination
 - `getPayerReceipt(invoiceId, preimage)` — payer receipt fetch using the Lightning preimage as proof of payment (no API key needed)
 - `getUploadUrl(params)` — signed URL for encrypted file upload (creator side)
-- `storeFile(params)` — register an uploaded file against an invoice
+- `storeFile(params)` — register an uploaded file against an invoice (requires `ciphertext_sha256`: the SHA-256 hex of the bytes you uploaded; Hypawave verifies + seals it so buyers can verify what they download)
 - `storeFileKey(params)` — register a file's encryption key against an invoice
 
 ## Error Handling

package/dist/index.d.mts

@@ -108,6 +108,13 @@ interface StoreFileParams {
     file_name: string;
     encrypted_file_url: string;
     iv_hex: string;
+    /**
+     * Lowercase-hex SHA-256 of the exact ciphertext uploaded to storage. Required.
+     * Hypawave verifies it against the stored bytes and seals them at the first
+     * bolt11 mint, and returns it at key retrieval so buyers can verify what they
+     * download. Compute over the same bytes you PUT to the presigned upload URL.
+     */
+    ciphertext_sha256: string;
     key_hash?: string;
     size?: number;
 }

package/dist/index.d.ts

@@ -108,6 +108,13 @@ interface StoreFileParams {
     file_name: string;
     encrypted_file_url: string;
     iv_hex: string;
+    /**
+     * Lowercase-hex SHA-256 of the exact ciphertext uploaded to storage. Required.
+     * Hypawave verifies it against the stored bytes and seals them at the first
+     * bolt11 mint, and returns it at key retrieval so buyers can verify what they
+     * download. Compute over the same bytes you PUT to the presigned upload URL.
+     */
+    ciphertext_sha256: string;
     key_hash?: string;
     size?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypawave/sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/skills/hypawave/SKILL.md

@@ -86,12 +86,12 @@ For Paths 3a / 3b, there is no SDK — use raw HTTP with pubkey signatures per t
 
 ## Non-negotiables
 
-1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this.
+1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this. The wallet also needs **funded outbound liquidity ≥ amount + fees** — a fresh/empty node or "fee-credit" balance can't pay even when total balance ≥ price. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — only funding is needed.
 2. **Confirm before unlocking.** Always submit preimage to the confirm endpoint before requesting file keys or download URLs.
 3. **Funds flow buyer→seller directly.** Never route principal through any Hypawave endpoint. Only activation fees (small, Hypawave-issued bolt11s) go to Hypawave.
 4. **Honor `terms_hash`** on Path 3b offers. If the server returns `409 terms_changed`, re-read the offer before paying.
 5. **Do not invent endpoints.** If a field or path is not in openapi.json, it does not exist.
-6. **Encrypt client-side** for file attachments. AES-256-GCM. Hypawave never sees plaintext.
+6. **Encrypt client-side** for file attachments. AES-256-GCM. Hypawave never sees plaintext. `storeFile` requires `ciphertext_sha256` (SHA-256 hex of the bytes you upload) — Hypawave verifies + seals it so buyers can verify what they download.
 
 ## When you hit something the manual doesn't cover