Architecture and Development of a Lightning Wallet
We develop Lightning wallets—applications for the Bitcoin Lightning Network that enable instant payments. A Lightning Network transaction completes in about 1 second on average. An on-chain Bitcoin transaction takes 10 to 60 minutes. The fee per payment is less than 0.001% of the amount—thousands of times cheaper than the main chain. Savings on transaction fees reach up to 95% compared to on-chain transfers. For a business processing 1,000 microtransactions daily, this translates to annual savings of over $5,000 in fees. A single channel can handle up to 4,000 payments per second, making Lightning ideal for micropayments and frequent transfers. Errors in state management can lead to loss of funds—that's why we pay special attention to architecture and security. Our team brings 5+ years of certified blockchain expertise and guarantees a secure implementation. We have delivered 22 projects with Lightning integration. We work with the full stack: from embedded solutions on LDK to custodial ones on LND/CLN. Non-custodial wallets require careful implementation of LDK, Breez SDK, channel management, submarine swaps, watchtowers, and support for BOLT 12 and LNURL—all of which we handle. Get a free project estimate within 2 days.
A Lightning wallet fundamentally falls into two classes: custodial and non-custodial. The choice determines the entire architecture. In the custodial model, the user does not hold channel keys. The server manages channels, and the client only sends requests via API. Examples include Strike, CashApp, and Wallet of Satoshi. Non-custodial models come in two types: embedded node (LDK, Breez SDK) and hosted node (Greenlight). In the former, the node runs directly in the app; in the latter, the keys remain with the user while the node executes in Blockstream's cloud. Breez SDK allows launching a non-custodial wallet 4x faster than a full implementation on LDK.
How Does the Channel State Machine Work?
Understanding the channel state machine is critical for any serious implementation. Here's the essence in a simplified model.
Commitment transaction—a transaction signed by both parties that either party can publish on-chain at any time to close the channel. At any given moment, only one valid commitment transaction exists for each party (each party has its own version with an asymmetric timelock).
The asymmetry is crucial because if Alice publishes her commitment transaction, she cannot immediately spend her output. It has an OP_CHECKSEQUENCEVERIFY (CSV) delay (e.g., 144 blocks). Bob can spend his output immediately. This gives Bob time to react if Alice published an outdated (revoked) commitment. He can take the entire channel balance via a penalty transaction.
The key secret is the commitment revocation key. At each state update, the parties exchange the per_commitment_secret of the previous state. With this secret, the counterparty can, if needed, construct a penalty transaction to punish the cheater.
State 0: Alice 1 BTC, Bob 0 BTC -> Alice reveals secret_0 to Bob
State 1: Alice 0.5 BTC, Bob 0.5 -> Bob reveals secret_1 to Alice
State 2: Alice 0.3 BTC, Bob 0.7 -> Alice reveals secret_2 to Bob
If Alice tries to publish State 0 (which favors her), Bob already has secret_0 and can apply the penalty, taking all of Alice's balance. This is the economic incentive not to cheat.
HTLC Routing Details
For payments through intermediate nodes, HTLC (Hash Time-Locked Contract) is used. A payment from Alice to Carol via Bob:
- Carol generates a random preimage R, gives Alice hash(R) in an invoice
- Alice adds an HTLC in her channel with Bob: "Give Bob X satoshi if he shows preimage for hash(R) by block N"
- Bob adds an analogous HTLC in his channel with Carol (slightly fewer satoshi—his fee, slightly shorter timeout)
- Carol reveals the preimage to Bob and claims the payment
- Bob reveals the preimage to Alice and claims the payment
If something goes wrong—the HTLC expires and funds return. Bob learns the preimage only when Carol reveals it; he couldn't cheat earlier.
In code implementation (LDK), this appears as a series of event callbacks:
fn handle_event(&self, event: Event) {
match event {
Event::PaymentClaimable { payment_hash, amount_msat, .. } => {
// We receive an incoming payment, need preimage
if let Some(preimage) = self.pending_payments.get(&payment_hash) {
self.channel_manager.claim_funds(*preimage);
}
}
Event::PaymentClaimed { payment_hash, amount_msat, .. } => {
// Payment successfully received
}
Event::PaymentFailed { payment_hash, .. } => {
// Payment failed, need to update UI
}
_ => {}
}
}
Why Are Watchtowers Critical for Non-Custodial Wallets?
Non-custodial Lightning has a fundamental problem: if the user is offline and a counterparty publishes an old commitment transaction, the user can lose funds (during the CSV timelock window). The solution is a watchtower.
A watchtower is a service to which the wallet delegates blockchain monitoring. The algorithm:
- At each channel state update, the wallet sends the watchtower an encrypted blob (penalty transaction + decryption key, encrypted with the txid of the revoked commitment)
- The watchtower monitors the blockchain
- If it sees a fraudulent commitment, it decrypts the blob and publishes the penalty transaction
- The watchtower takes a share of the penalty (usually 1%) as a reward
In LDK: channel_manager.get_relevant_txids() returns the txids to watch. Data for the watchtower is generated by channel_monitor.get_latest_holder_commitment_txn().
Open protocols: BOLT 13 (draft). Real implementations: The Eye of Satoshi (TEOS), Lightning Rod (Zeus). You can integrate a ready-made watchtower or run your own.
What's Included in Lightning Wallet Development
Our full-cycle development includes:
- Detailed technical documentation and architecture specification
- Implementation of channel management, HTLC processing, and routing
- Watchtower and submarine swap integration
- Support for LNURL, BOLT 11/12, and LSPS standards
- Access to development and staging environments (testnet/signet)
- Training for your team on maintenance and operations
- Post-launch support for 3 months, including bug fixes and updates
- Security audit report with code review and formal verification findings
Custodial vs Non-Custodial Comparison
| Parameter | Custodial | Non-custodial (embedded) |
|---|---|---|
| Key control | Server | User |
| Risk of fund loss due to error | Low (server manages) | High (requires correct implementation) |
| Time to launch | 6-8 weeks | 4-6 months |
| Implementation complexity | Medium (API wrapper) | High (state machine, watchtower) |
| User UX | Simpler (no channel management) | Harder (needs channel management) |
Stack and Technologies
| Component | Technology | Application |
|---|---|---|
| Lightning core | LDK (Rust/bindings) | Non-custodial mobile |
| Hosted node | Greenlight + Breez SDK | Managed non-custodial |
| Lightning node | LND (Go) / CLN (C) | Custodial / server |
| On-chain data | Electrum protocol / Esplora | Synchronization |
| Watchtower | TEOS / custom | Offline protection |
| Submarine swaps | Boltz API | On/off-ramp |
| Mobile | React Native + LDK bindings | iOS + Android |
Process of Work
- Analytics—define requirements, channels, liquidity, target audience
- Design—architecture, protocol selection, security
- Implementation—write modules for channel management, HTLC, routing
- Testing—unit, integration, fuzzing (Echidna, Slither)
- Deployment—spin up nodes, configure watchtower, monitoring
Estimated Timelines and Cost
- Custodial Lightning wallet (mobile app + backend on LND/CLN): 6-8 weeks, starting from $25,000
- Non-custodial with Breez SDK (simplified non-custodial): 8-10 weeks, starting from $35,000
- Full non-custodial implementation on LDK with watchtower, LSP integration, BOLT 12, submarine swaps: 4-6 months, starting from $80,000
Cost is determined individually. Our team is certified in LDK and LND, guaranteeing a thorough security audit. Contact us for a consultation and preliminary estimate. Our engineers have over 5 years of blockchain experience and have delivered more than 20 projects with Lightning integration.
Typical Development Mistakes
- Loss of channel monitor state—critical, can lead to fund loss. LDK requires a reliable Persist trait implementation—every state update must be persisted before confirming to the counterparty.
- Incorrect fee management—HTLC routing fees and on-chain fees for opening/closing channels must be transparent to the user.
- Ignoring invoice expiry—BOLT 11 invoices have an expiry (default 3600 seconds). The UI should show the remaining time and be able to generate a new invoice.
A Lightning wallet on LDK provides 3x higher payment throughput compared to an LND-based backend solution. Savings on transaction fees are up to 95% compared to on-chain Bitcoin payments. Order turnkey development and get a reliable solution for instant micropayments.