feat: Complete Lightning Wallet — Auto-verification, Budget Control, Styled Receipts #38
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,79 +1,74 @@ | ||
| # Alby Bitcoin Lightning Wallet Skill — Community Edition | ||
|
|
||
| A complete Bitcoin Lightning wallet powered by Alby's Nostr Wallet Connect. The agent handles everything — you just talk naturally. | ||
|
|
||
| Every payment gets **cryptographically proven** with SHA-256 preimage verification. No transaction is ever lost. No payment can be disputed. | ||
|
|
||
| ## What It Does | ||
|
|
||
| | Say This | Get This | | ||
| |----------|----------| | ||
| | "balance" | Multi-currency balance + styled card | | ||
| | "create invoice 100 sats" | BOLT-11 + QR code + styled receipt | | ||
| | "send 500 to alice@getalby.com" | Confirmed payment with preimage proof | | ||
| | "wallet summary" | Complete one-command overview | | ||
| | "verify this payment" | SHA-256 cryptographic proof | | ||
|
|
||
| ## Features | ||
|
|
||
| - **Auto-Ledger** — Background process that verifies and saves every settled payment with SHA-256 preimage proofs | ||
| - **Budget Guardian** — Weekly spending caps with 90% alerts (commitment device) | ||
| - **Multi-Wallet** — Add, switch, and manage multiple N wallets | ||
| - **Activity Milestones** — Gamified streak tracking | ||
| - **Styled Receipt Cards** — Beautiful PIL/Pillow cards for messaging platforms | ||
| - **6-Point Health Diagnostics** — Instant wallet status check | ||
| - **CSV Export** — Tax-ready, audit-proof transaction records | ||
| - **Safety Confirmations** — Mandatory confirmation before any outgoing payment | ||
| - **NWC Lie Detection** — Verifies every payment appears in transaction history after send | ||
|
|
||
| ## Install | ||
|
|
||
| ### For Hermes Agent Users | ||
|
|
||
| ```bash | ||
| # Drop into your skills directory | ||
| git clone https://github.com/getAlby/alby-agent-skill.git ~/.hermes/skills/alby-bitcoin-payments | ||
| cd ~/.hermes/skills/alby-bitcoin-payments | ||
| npm install @getalby/sdk @getalby/lightning-tools light-bolt11-decoder qrcode | ||
| ``` | ||
|
|
||
| ### Configure | ||
|
|
||
| Save your NWC URL in `~/.hermes/config_local.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "wallet": { | ||
| "nwc_url": "nostr+walletconnect://..." | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Requirements | ||
|
|
||
| - Node.js 22+ | ||
| - Python 3 with Pillow (for styled cards) | ||
| - Alby NWC wallet connection | ||
|
|
||
| ## Test Wallet | ||
|
|
||
| Get instant test wallet with 10,000 sats: | ||
|
|
||
| ```bash | ||
| curl -X POST https://faucet.nwc.dev?balance=10000 | ||
| ``` | ||
|
|
||
| ## What Makes This Special | ||
|
|
||
| Every payment is a **trustless cryptographic event**. The preimage proves it happened — mathematics, not promises. | ||
|
|
||
| A wallet without verified preimages is just a claim. This skill turns claims into proof. | ||
|
|
||
| --- | ||
|
|
||
| Built on: [Alby JS SDK](https://github.com/getAlby/js-sdk) · [Alby Lightning Tools](https://github.com/getAlby/js-lightning-tools) · [NIP-47 NWC Protocol](https://github.com/nostr-protocol/nips/blob/master/47.md) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,166 @@ | ||
| --- | ||
| name: alby-bitcoin-payments | ||
| description: Bitcoin Lightning wallet via NWC. Say anything natural, get confirmed transactions. Every payment cryptographically proven with SHA-256 preimage verification. | ||
| version: "7.0.0" | ||
| --- | ||
|
|
||
| ## What This Is | ||
|
|
||
| A complete Bitcoin Lightning wallet powered by Alby's Nostr Wallet Connect. The agent handles everything — the user just talks naturally. | ||
|
|
||
| ## How It Works | ||
|
|
||
| User → says anything natural → agent does everything → confirmation. | ||
|
|
||
| ``` | ||
|
There was a problem hiding this comment. Add language identifiers to fenced code blocks (MD040). These fences are missing language tags and trigger markdownlint warnings. Suggested cleanup- ```
+ ```text
...
- ```
+ ```text
...
- ```
+ ```text
...
- ```
+ ```text
...
- ```
+ ```bashAlso applies to: 54-54, 61-61, 67-67, 103-103 🧰 Tools🪛 markdownlint-cli2 (0.22.0)[warning] 15-15: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🤖 Prompt for AI Agents |
||
| User: "send 500 to alice@getalby.com" | ||
| User: "balance" | ||
| User: "create invoice for 1000 sats" | ||
| User: "my wallet" ← one command, everything | ||
| User: "verify this payment" | ||
| ``` | ||
|
|
||
| ## Core Agent Rules | ||
|
|
||
| **On session start:** | ||
| 1. Read `wallet.nwc_url` from `~/.hermes/config_local.json` | ||
| 2. If auto-ledger not running, start it in background | ||
| 3. Show balance | ||
|
|
||
| **SECURITY: NWC URL MUST NEVER be displayed, echoed, or shared in any output, logs, or chat.** | ||
|
|
||
| **On every wallet operation:** | ||
| - `cd /root/.hermes/skills/alby-bitcoin-payments` first | ||
| - NWC returns millisats → always divide by 1000 | ||
| - Always include fiat equivalent (USD default) | ||
| - NWC URL → never echo, never log, never display in any form | ||
| - Read URL only from `~/.hermes/config_local.json` (chmod 600) — never ask user for it again | ||
|
There was a problem hiding this comment. Clarify expired-URL flow vs “never ask again” rule. These lines conflict operationally. Define one explicit policy for renewal (e.g., secure re-provisioning flow) so agents don’t behave inconsistently. Also applies to: 163-163 🤖 Prompt for AI Agents |
||
|
|
||
| **Before sending:** | ||
| 1. Decode destination → show amount, fiat, recipient | ||
| 2. Confirm: `"Send X sats ($Y) to Z? Reply YES to confirm."` | ||
| 3. After paying → verify in `listTransactions()` (NWC can report false success) | ||
|
|
||
| **On invoice creation:** | ||
| - BOLT-11 in code block (one-tap copy) | ||
| - Include sats + fiat | ||
|
|
||
| **On BOLT-11 or lightning address in any message:** | ||
| - Auto-decode → show details → offer next action | ||
|
|
||
| ## Response Style | ||
|
|
||
| ### Balance Card | ||
| ``` | ||
| Wallet: alias | mainnet | ||
| Balance: 1,234 sats | ||
| $ 1.23 USD · € 1.07 EUR · KSh 159.20 KES | ||
| ``` | ||
|
|
||
| ### Transaction Row | ||
| ``` | ||
| → +100 sats ($0.07) ✅ | description | bal: 1,234 | ||
| ← -50 sats ($0.03) ✅ | to alice | bal: 1,184 | ||
| ``` | ||
|
|
||
| ### Payment Proof | ||
| ``` | ||
| Payment Hash: a863be4753fe982d... | ||
| SHA-256(preimage): a863be4753fe982d... | ||
| ✅ MATCH — Preimage: 9137715c...59b1 | ||
| ``` | ||
|
|
||
| ## Behind the Scenes | ||
|
|
||
| | Feature | Script | What It Does | | ||
| |---|---|---| | ||
| | Summary | `summary.js` | One-command wallet overview | | ||
| | Balance | `balance.js` | Multi-currency balance (USD/EUR/KES) | | ||
| | Invoice | `qr_invoice.js` | BOLT-11 invoice + QR code | | ||
| | Decode | `decode.js` | Parse invoices or lightning addresses | | ||
| | Analytics | `analytics.js` | Period reports with top transactions | | ||
| | Auto-Ledger | `auto_ledger.js` | Background: real-time payments + crypto proofs | | ||
| | Validate | `validate.js` | Standalone preimage verification | | ||
| | Budget | `budget_guardian.js` | Weekly spending caps with alerts | | ||
| | Streaks | `streaks.js` | Activity milestones & gamification | | ||
| | Multi-Wallet | `wallets.js` | Add/switch/remove wallets | | ||
| | Health | `health_check.js` | 6-point diagnostics | | ||
| | Export | `export_ledger.js` | CSV export for tax/audit | | ||
|
|
||
| ## Auto-Ledger (The Trustless Core) | ||
|
|
||
| Every settled payment gets automatically: | ||
| 1. **Verified** — SHA-256(preimage) == payment_hash | ||
| 2. **Saved** — Persistent ledger at `~/.hermes/ledgers/transactions_ledger.json` | ||
| 3. **Proved** — Individual proof files in `~/.hermes/ledgers/proofs/` | ||
|
|
||
| No transaction is ever lost. No payment can be disputed. Mathematics, not promises. | ||
|
|
||
| ## Budget Guardian | ||
|
|
||
| Set a weekly spending cap. The system tracks and alerts at 90%. Pre-commitment removes the temptation of impulse spending. | ||
|
|
||
| ``` | ||
| node budget_guardian.js setup 5000 # 5000 sats/week | ||
| node budget_guardian.js status # Current usage | ||
| node budget_guardian.js reset # Reset for new week | ||
| ``` | ||
|
|
||
| ## Initial Setup | ||
|
|
||
| 1. `cd ~/.hermes/skills/alby-bitcoin-payments` | ||
| 2. Run `npm install` (uses `package.json` in skill root) | ||
|
There was a problem hiding this comment. Setup instructions conflict on Line 112 says Also applies to: 148-149 🤖 Prompt for AI Agents |
||
| 3. Set NWC URL in `~/.hermes/config_local.json` under `wallet.nwc_url` | ||
| ```json | ||
| {"wallet": {"nwc_url": "nostr+walletconnect://..."}} | ||
| ``` | ||
| 4. Set file permissions: `chmod 600 ~/.hermes/config_local.json` | ||
| 5. Start auto-ledger: `export NWC_URL=$(python3 -c "import json; print(json.load(open('~/.hermes/config_local.json'))['wallet']['nwc_url'])") && node scripts/auto_ledger.js &` | ||
|
|
||
| ### Running Scripts | ||
|
|
||
| Always export NWC URL first (scripts read from env, not config file): | ||
| ```bash | ||
| cd ~/.hermes/skills/alby-bitcoin-payments | ||
| export NWC_URL=$(python3 -c "import json; print(json.load(open('~/.hermes/config_local.json'))['wallet']['nwc_url'])") | ||
| node scripts/balance.js | ||
|
Comment on lines
+118
to
+126
There was a problem hiding this comment. 🧩 Analysis chain🌐 Web query:
💡 Result: No. 🏁 Script executed: # Check if SKILL.md exists and view the relevant lines
if [ -f "SKILL.md" ]; then
echo "=== Lines 115-130 of SKILL.md ==="
sed -n '115,130p' SKILL.md
echo ""
echo "=== Full context around line 118 and 125 ==="
sed -n '110,135p' SKILL.md
else
echo "SKILL.md not found, searching for it..."
find . -name "SKILL.md" -type f
fiRepository: getAlby/builder-skill Length of output: 1790 🏁 Script executed: # Search for any wrapper scripts or references to these commands
echo "=== Search for references to 'open' with config_local.json ==="
rg "config_local\.json" -A 2 -B 2
echo ""
echo "=== Search for shell scripts or Python files that might wrap these commands ==="
fd -e "sh" -e "py" -e "js" | head -20 | xargs -I {} rg -l "NWC_URL|nwc_url" {}
echo ""
echo "=== Check if there are any shell startup scripts or bashrc ==="
find . -name ".bashrc" -o -name ".bash_profile" -o -name "*.sh" -type f | head -10Repository: getAlby/builder-skill Length of output: 3506 Fix The Python Suggested fix- export NWC_URL=$(python3 -c "import json; print(json.load(open('~/.hermes/config_local.json'))['wallet']['nwc_url'])") && node scripts/auto_ledger.js &
+ export NWC_URL=$(python3 -c "import json, os; p=os.path.expanduser('~/.hermes/config_local.json'); print(json.load(open(p))['wallet']['nwc_url'])") && node scripts/auto_ledger.js &
- export NWC_URL=$(python3 -c "import json; print(json.load(open('~/.hermes/config_local.json'))['wallet']['nwc_url'])")
+ export NWC_URL=$(python3 -c "import json, os; p=os.path.expanduser('~/.hermes/config_local.json'); print(json.load(open(p))['wallet']['nwc_url'])")🤖 Prompt for AI Agents |
||
| ``` | ||
|
|
||
| ## Environment | ||
|
|
||
| | Path | Purpose | | ||
| |------|---------| | ||
| | `/root/.hermes/skills/alby-bitcoin-payments/` | Skill root — always `cd` here first | | ||
| | `~/.hermes/ledgers/` | Auto-ledger + proof files | | ||
| | `~/.hermes/config_local.json` | NWC URL + user config | | ||
|
|
||
| **Script Execution:** Always export the NWC URL before running scripts: | ||
| ```bash | ||
| export NWC_URL=$(python3 -c "import json; print(json.load(open('/root/.hermes/config_local.json'))['wallet']['nwc_url'])") | ||
| ``` | ||
|
|
||
| **Important Script Argument Orders:** | ||
| - `pay.js` — takes `<amount_sats>` then `<recipient>`: `pay.js 100 user@domain.com` (amount first!) | ||
| - `qr_invoice.js` — takes `<amount_sats>` then `<description>`: `qr_invoice.js 100 "my invoice"` | ||
|
|
||
| **Key Operational Notes:** | ||
| - The `@getalby/sdk` NWCClient must be imported from `@getalby/sdk/nwc` (not the main module) | ||
| - The `package.json` may not be present in the installed skill directory — it's in the clone root, needed for `npm install` | ||
| - The auto-ledger (`auto_ledger.js`) does NOT start automatically — run it manually in background after wallet setup: | ||
| ```bash | ||
| mkdir -p ~/.hermes/ledgers/proofs && node scripts/auto_ledger.js & | ||
| ``` | ||
| - Payment verification via NWC `listTransactions()` is the authoritative source — NWC `payInvoice()` can report false success | ||
| - SHA-256 preimage verification: `crypto.createHash('sha256').update(Buffer.from(preimage, 'hex')).digest('hex')` should match `payment_hash` | ||
|
|
||
| **PIL cards:** Disabled. Do not generate styled PIL receipt cards. Just use text confirmations and ASCII panels. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| | Problem | Fix | | ||
| |---|---| | ||
| | `Cannot find module` | Run from skill directory — deps are in local `node_modules/` | | ||
| | Connection refused | NWC URL expired — ask for a new one | | ||
| | Amount looks 1000x wrong | NWC = millisats. Divide by 1000. | | ||
| | `payInvoice` reported success but no transaction | NWC can lie. Always check `listTransactions()` after paying | | ||
| | PIL import fails | Use `/usr/bin/python3` — the agent's venv python doesn't have Pillow | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| { | ||
| "dependencies": { | ||
| "@getalby/lightning-tools": "^7.0.2", | ||
| "@getalby/sdk": "^7.0.0", | ||
| "bolt12-decoder": "^1.0.0", | ||
| "light-bolt11-decoder": "^3.2.0", | ||
| "qrcode": "^1.5.4" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # Payment Validation (Preimage Verification) | ||
|
|
||
| Verify that a Lightning Network payment was actually completed by cryptographically checking the preimage against the invoice's payment hash. | ||
|
|
||
| ## How It Works | ||
|
|
||
| 1. Every BOLT-11 invoice contains a `payment_hash` (SHA-256 of the preimage) | ||
| 2. When payment completes, the payer's node reveals the `preimage` | ||
| 3. Verifying: `SHA-256(preimage) == payment_hash` proves the payment went through | ||
| 4. Only the recipient can know the preimage — so proving they had it proves they received payment | ||
|
|
||
| Reference implementation: https://github.com/kingonly/validate-payment | ||
| Live web validator: https://validate-payment.com/ | ||
|
|
||
| ## CLI Script (Bundled) | ||
|
|
||
| ```bash | ||
| node scripts/validate.js [invoice] [preimage_hex] | ||
| ``` | ||
|
|
||
| Supports BOLT11 (`lnbc`/`lntb`) and BOLT12 (`lni`) invoice formats. | ||
| Shows decoded invoice details (amount, description, timestamp, expiry) plus the hash comparison. | ||
|
|
||
| ## Node.js API | ||
|
|
||
| ```typescript | ||
| import { decode as decodeBolt11 } from 'light-bolt11-decoder'; | ||
| import crypto from 'crypto'; | ||
|
|
||
| function validatePayment(invoice: string, preimage: string): boolean { | ||
| const decoded = decodeBolt11(invoice); | ||
| const paymentHash = decoded.sections.find(s => s.name === 'payment_hash').value; | ||
| const preimageBytes = Uint8Array.from(preimage.match(/.{1,2}/g).map(h => parseInt(h, 16))); | ||
| const computed = crypto.createHash('sha256').update(preimageBytes).digest('hex'); | ||
| return computed === paymentHash; | ||
| } | ||
| ``` | ||
|
|
||
| ## When to Use | ||
|
|
||
| - **Pay-to-unlock content**: User pays, you deliver content, they can verify the preimage matches | ||
| - **Third-party payment proof**: Someone claims they paid — verify with preimage | ||
| - **Escrow/settlement verification**: Confirm funds actually moved before releasing goods | ||
| - **HOLD invoice confirmation**: After settling, the preimage proves the HTLC completed | ||
| - **Payment receipt verification**: Generate a verifiable receipt by providing preimage + invoice |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Clone URL may not match repository name.
The PR is on
getAlby/builder-skillbut the clone command referencesalby-agent-skill. Also, thenpm installcommand is missing some dependencies listed in package.json (e.g.,bolt12-decoder,qrcode-terminal,bolt11).Verify and fix installation commands
📝 Committable suggestion
🤖 Prompt for AI Agents