Skip to content

Commit 1e94710

Browse files
G8XSUG8XSU
committed
Add VSS Blogpost.
1 parent 04f54de commit 1e94710

File tree

2 files changed

+174
-0
lines changed

2 files changed

+174
-0
lines changed

‎docs/_blog/announcing-vss.md

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