Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit ddbae7c

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

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

‎docs/_blog/announcing-vss.md‎

Lines changed: 180 additions & 0 deletions
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月14日"
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, VSS-server has a Java-based implementation and is ready to use. Support for a Rust-based VSS-server is a work
142+
in progress. [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(WIP) 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.
36.5 KB
Loading[フレーム]

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /