Skip to content

Commit 4344847

Browse files
G8XSUG8XSU
authoredMar 17, 2025··
Add VSS Blogpost. (#298)
* Add VSS Blogpost
1 parent 04f54de commit 4344847

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed
 

‎docs/_blog/announcing-vss.md

+180
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: "Announcing Versioned Storage Service (VSS)"
3+
description: "The Versioned Storage Service (VSS) provides a server-side storage solution for non-custodial mobile, web and hosted wallets."
4+
date: "2025-03-17"
5+
authors:
6+
- Gursharan Singh
7+
tags:
8+
- VSS
9+
- Mobile
10+
- Storage
11+
- Self-custody
12+
---
13+
14+
The Versioned Storage Service (VSS) provides a server-side storage solution for non-custodial mobile, web and hosted
15+
wallets. VSS significantly simplifies the wallet development process by offering a reliable, secure, and robust
16+
framework that stores and manages the various forms of state data required for the Lightning Network (LN) and Bitcoin
17+
applications.
18+
19+
# What Is VSS?
20+
21+
VSS is a client-server storage framework for Lightning Network (LN) and Bitcoin wallet data. VSS primarily serves two
22+
core functionalities:
23+
24+
- Recovery: VSS enables the restoration of states and wallet access, helping users regain their funds and control even
25+
in scenarios of device or data loss.
26+
- Multi-device Access: While this isn’t available now, future phases will allow the same wallet app across multiple
27+
devices to securely share and access the LN state, leading to consistent access to funds.
28+
29+
Clients can also leverage VSS for general application metadata storage including payment history, user metadata, and
30+
more.
31+
32+
# Why VSS?
33+
34+
VSS aims to lower the barriers to high-quality LN wallet development. Wallet builders can host the VSS service in-house
35+
for straightforward interaction with the service or use reliable third-party VSS providers, if available.
36+
37+
VSS was designed with privacy in mind, offering features such as client-side encryption, key-obfuscation, and robust
38+
authorization. It also ensures data and version number verifiability, and will support multi-device access in the
39+
future. The software ensures modularity for seamless integration with different storage backend technologies.
40+
Additionally, VSS can work with various applications with different key-level versioning and data-integrity mechanisms
41+
and even allows disabling versioning for single-device wallet usage.
42+
43+
### Why do we need VSS as primary storage for lightning wallets?
44+
45+
Keeping VSS in sync with the latest Lightning state isn’t optional; if the server’s version lags and the user loses the
46+
device, there is a risk for funds loss. That’s why VSS-powered wallets must be designed to hold off advancing the
47+
lightning state until everything’s securely updated on the server.
48+
49+
The on-device state of a Lightning wallet changes every time a user sends or receives payments. While some backup
50+
options offer frequency-based backups, these can lead to data being out of sync and do not ensure full funds or channel
51+
recovery if the device is lost. Protocols that sync asynchronously based on intervals inherently have insufficient data
52+
for complete recovery by design.
53+
54+
Using VSS as the primary storage ensures that every state change is securely stored in real-time, enabling full recovery
55+
of funds and channels regardless of device loss.
56+
57+
<div style="text-align: center;">
58+
<img style="display: block; margin: auto;" src="../assets/vss-data-flow-simplified.png" alt="VSS High Level Data Flow (Simplified)">
59+
<p style="margin-top: 10px;">VSS High Level Data Flow (Simplified)</p>
60+
</div>
61+
62+
# Customization
63+
64+
While VSS can be readily used, it is intended to be customized based on specific requirements. For example, clients
65+
might need to implement custom authorization, encryption, or backend database integration with different cloud
66+
providers. With the accurate facilitation of the API contract, wallets can easily switch between different instances of
67+
VSS. For example, a wallet can easily switch from VSS-Provider-A to VSS-Provider-B by just downloading the whole state
68+
and uploading it to the new provider.
69+
70+
By default, VSS incorporates a PostgreSQL implementation and can be hosted on preferred infrastructure/cloud providers
71+
such as AWS, GCP, and others. Its backend storage can be interchanged with other implementations for KeyValueStore if
72+
necessary.
73+
74+
# Usage
75+
76+
### Using with LDK Node:
77+
78+
[LDK Node](https://github.com/lightningdevkit/ldk-node) can be easily configured to run with VSS as primary storage. It
79+
is integrated in LDK Node (written in Rust) using [VSS-rust-client](https://github.com/lightningdevkit/vss-rust-client),
80+
and there is also support for other languages such as Swift, Kotlin and Python
81+
through [UniFFI](https://mozilla.github.io/uniffi-rs/) bindings.
82+
83+
```rust
84+
use ldk_node::Builder;
85+
86+
fn main() {
87+
let mut node_builder = Builder::new();
88+
...
89+
// Note: store_id can be freely set by the user and is useful for creating separate namespaces within storage.
90+
// However, it must remain fixed for the entire life of the node as it is used for database storage.
91+
let node = node_builder
92+
.build_with_vss_store_and_fixed_headers(
93+
vss_endpoint,
94+
store_id,
95+
HashMap::new(),
96+
)
97+
.unwrap();
98+
99+
node.start().unwrap();
100+
...
101+
...
102+
}
103+
```
104+
105+
### Using with Other Applications
106+
107+
VSS is designed to store application-related metadata. Clients can use
108+
the [VSS-rust-client](https://github.com/lightningdevkit/vss-rust-client) directly for this purpose. This can help
109+
provide a complete user data recovery solution for applications, as well as enable turn-key multi-device support in the
110+
future.
111+
112+
### Hosting
113+
114+
VSS can either be self-hosted or deployed in the cloud. If a service provider is hosting VSS for multiple users, it must
115+
be configured with **HTTPS**, **Authentication/Authorization**, and **rate-limiting**.
116+
117+
Application/wallet vendors can choose to either self-host VSS instances or use one of the existing hosted VSS providers.
118+
119+
### Authentication & Authorization
120+
121+
Currently, the VSS-server supports [JWT](https://datatracker.ietf.org/doc/html/rfc7519)\-based authentication and
122+
authorization, and can run without authentication for local testing or in trusted setups. The VSS-rust-client supports
123+
LNURL-auth & JWT based authentication and authorization. Switching to simple HTTP header authentication is
124+
straightforward by adding another implementation. Note that the security of authentication heavily relies on using HTTPS
125+
for all requests.
126+
127+
### Scaling
128+
129+
VSS itself is stateless and can be horizontally scaled easily. VSS can be configured to point to a PostgreSQL cluster,
130+
and further scaling considerations need to be addressed in the PostgreSQL cluster.
131+
132+
# Project Status
133+
134+
VSS execution is split into two phases: Phase I prioritizes recovery and single-device use, whereas Phase II covers
135+
multi-device use. Phase I is ready to use and integrated within [LDK Node](https://github.com/lightningdevkit/ldk-node).
136+
Phase II will be subject to monitoring for demand from wallets and may slip to a later date. Refer
137+
to [LDK-Roadmap](https://lightningdevkit.org/blog/ldk-roadmap/#vss) for more details.
138+
139+
# Implementation
140+
141+
Currently, the VSS server has Java and Rust based implementations and is ready to use.
142+
[VSS-rust-client](https://github.com/lightningdevkit/vss-rust-client) is a Rust-based client with support
143+
for client-side encryption, key obfuscation, retry mechanisms, and LNURL-auth. VSS is also integrated starting
144+
with [LDK Node](https://github.com/lightningdevkit/ldk-node) v0.4.x as alpha support.
145+
146+
# Future
147+
148+
In the future, LDK and VSS will introduce multi-device support. This will enable users to seamlessly access the same
149+
Lightning node across multiple devices.
150+
151+
With synchronized updates and real-time access, users can manage their Lightning wallet from any preferred device,
152+
enhancing convenience and accessibility while maintaining consistency across platforms.
153+
154+
# Conclusion
155+
156+
In summary, VSS provides an open-source, server-side cloud storage solution optimized specifically for non-custodial
157+
Lightning/Bitcoin wallets as well as auxiliary application storage needs. Its key features include multi-device access,
158+
recovery capabilities, user privacy protection, and data verifiability. With VSS, wallet developers can focus on
159+
creating innovative Lightning wallets without the extra burden of crafting
160+
complex [live backup storage](https://lightningdevkit.org/blog/the-challenges-of-developing-non-custodial-lightning-on-mobile/#live-backups)
161+
solutions from scratch.
162+
163+
# Resources
164+
165+
1. [vss-server](https://github.com/lightningdevkit/vss-server) : A java and rust implementation of VSS server with
166+
PostgreSQL as default storage backend.
167+
168+
2. [vss-rust-client](https://crates.io/crates/vss-client) : A rust client for VSS, with in-built support for retries,
169+
client-side encryption and custom auth mechanism.
170+
171+
3. [LDK Node](https://github.com/lightningdevkit/ldk-node/blob/f1fdee50d5a8b628040fb2d584a7c4b831090de4/src/builder.rs#L441-L557) :
172+
VSS is integrated with LDK Node and currently has alpha/experimental support.
173+
174+
4. Bindings: On the client side, VSS is also usable with existing LDK Node bindings in Kotlin/swift/python.
175+
176+
# Support
177+
178+
If you encounter any issues or have questions, feel free to open an issue on
179+
the [GitHub repository](https://github.com/lightningdevkit/vss-server/issues). For further assistance or to discuss the
180+
development of VSS, you can reach out to us in the [LDK Discord](https://discord.gg/5AcknnMfBw) in the `#vss` channel.

‎docs/assets/vss-data-flow-simplified.png

36.5 KB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.