{"id":35122078,"url":"https://github.com/synonymdev/vss-server","last_synced_at":"2026-04-28T02:32:57.065Z","repository":{"id":328352952,"uuid":"1108434913","full_name":"synonymdev/vss-server","owner":"synonymdev","description":"Versioned Storage Service configured with the JWT auth contract expected by ldk-node and vss-rust-client.","archived":false,"fork":false,"pushed_at":"2025-12-12T17:26:23.000Z","size":314,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T06:27:32.630Z","etag":null,"topics":["backups","bitcoin","storage"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synonymdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-02T12:53:10.000Z","updated_at":"2025-12-12T17:15:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/synonymdev/vss-server","commit_stats":null,"previous_names":["synonymdev/vss-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/synonymdev/vss-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synonymdev%2Fvss-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synonymdev%2Fvss-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synonymdev%2Fvss-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synonymdev%2Fvss-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synonymdev","download_url":"https://codeload.github.com/synonymdev/vss-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synonymdev%2Fvss-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32363629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backups","bitcoin","storage"],"created_at":"2025-12-28T00:37:11.971Z","updated_at":"2026-04-28T02:32:57.060Z","avatar_url":"https://github.com/synonymdev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Versioned Storage Service\n\n### Introduction to VSS (Versioned Storage Service)\n\nVSS, which stands for Versioned Storage Service, is an open-source project designed to offer a server-side cloud storage\nsolution specifically tailored for non-custodial Lightning supporting mobile wallets. Its primary objective is to\nsimplify the development process for Lightning wallets by providing a secure means to store and manage the essential\nstate required for Lightning Network (LN) operations.\n\nIn a non-custodial Lightning wallet, it is crucial to securely store and manage various types of state data. This\nincludes maintaining a list of open channels with other nodes in the network and updating the channel state for every\npayment made or received. Relying solely on user devices to store this information is not reliable, as data loss could\nlead to the loss of funds or even the entire wallet.\n\nTo address this challenge, the VSS project introduces a framework and a readily available service that can be hosted by\nanyone as a Versioned Storage Service. It offers two core functionalities:\n\n* **Recovery**: In the event of a user losing their phone or access to their app's data, VSS allows for the restoration\n  of the wallet state. This ensures that users can regain access to their funds, even in cases of device or data loss.\n* **Multi-device Access**: VSS enables multiple devices with the same wallet app to securely access and share LN state.\n  This seamless switching between devices ensures consistent access to funds for users.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"http://www.plantuml.com/plantuml/png/VP2nJWCn44HxVyMKK4JqAQ8W8aGHA33GBxuXP-7p7lRUeVmzAz60X6YcsQTvezrtasRBL89bAyHBZBZBfn57hYmuY0bkYtw6SA-lkV30DITkTd1mY-l5HbRBIInhnIC_5dOBVjliVl9RT9ru8Ou_wJlhPGX5TSQRDhYddJ7BUV8cT8-hniIySlZJ-JmFOiJn0JUZrCg2Q6BybaRJ9YVwCjCff_zWUE7lZN59YRq7rY7iFVmhNm00\" /\u003e\n\u003c/p\u003e\n\nClients can also use VSS for general metadata storage such as payment history, user metadata, etc.\n\n### Motivation\n\nBy providing a reusable component, VSS aims to lower the barriers for building high-quality LN wallets. Wallet\ndevelopers have the flexibility to either host the VSS service in-house, enabling easy interaction with the component,\nor utilize reliable third-party VSS providers if available.\n\nVSS is designed to work with various applications that implement different levels of key-level versioning and\ndata-integrity mechanisms. It even allows for the disabling of versioning altogether for single-device wallet usage,\nmaking it simple to get started.\n\nThe project's design decisions prioritize features such as multi-device access, user privacy through client-side\nencryption (e.g. using key derived from bitcoin wallet), authorization mechanisms, data and version number verifiability,\nand modularity for seamless integration with different backend technologies.\n\n### Modularity\n\nVSS can work out-of-the-box with minor configuration but is intended to be forked and customized based on the specific needs\nof wallet developers. This customization may include implementing custom authorization, encryption, or backend database\nintegration with different cloud providers. As long as the API contract is implemented correctly, wallets can\neffortlessly switch between different instances of VSS.\n\nVSS ships with a PostgreSQL implementation by default and can be hosted in your favorite infrastructure/cloud provider\n(AWS/GCP) and its backend storage can be switched with some other implementation for KeyValueStore if needed.\n\n### Project Status\n\nVSS execution is split into two phases: Phase I prioritizes recovery and single-device use, whereas Phase II covers\nmulti-device use. Phase I is ready to use and integrated within [LDK-node]. Phase II will be subject to monitoring for\ndemand from wallets and may slip to a later date. Refer to [LDK-Roadmap] for more details.\n\n### API\n\nSee the [VSS API contract] for details.\n\n### Implementation\n\nCurrently, VSS-server has a Rust-based implementation and is ready to use.\n[VSS-rust-client] is a Rust-based client with support for client-side encryption, key obfuscation, retry mechanisms, and\nLNURL-auth.\nVSS is also integrated with [LDK-node] v0.4.x as alpha support.\n\n### Development\n\n* **Build \u0026 Deploy**: Refer to language-specific folder for instructions related to building and deploying VSS.\n* **Hosting**: VSS can either be self-hosted or deployed in the cloud. If a service provider is hosting VSS for multiple\n  users, it must be configured with **HTTPS**, **Authentication/Authorization**, and **rate-limiting**.\n* **Authentication and Authorization**: Currently, the VSS-server\n  supports [JWT](https://datatracker.ietf.org/doc/html/rfc7519)-based authentication and authorization, and can run\n  without authentication for local testing or in trusted setups. The VSS-rust-client supports LNURL-auth \u0026 JWT based\n  authentication and authorization. Switching to simple HTTP header authentication is straightforward by adding another\n  implementation. Note that the security of authentication heavily relies on using HTTPS for all requests.\n* **Scaling**: VSS itself is stateless and can be horizontally scaled easily. VSS can be configured to point to a\n  PostgreSQL cluster, and further scaling considerations need to be addressed in the PostgreSQL cluster.\n* **Using with LDK-node**: [LDK-node] can be easily configured to run with VSS as primary storage. It is integrated in\n  LDK-node (written in Rust) using [VSS-rust-client], and there is also support for other languages such as Swift,\n  Kotlin and Python through [UniFFI] bindings.\n    ```rust\n    use ldk_node::Builder;\n    fn main() {\n        let mut node_builder = Builder::new();\n        ...\n        let node = node_builder.build_with_vss_store_and_fixed_headers(vss_endpoint, store_id, HashMap::new()).unwrap();\n        node.start().unwrap();\n        ...\n    }\n    ```\n* **Using with Other Applications**: VSS is designed to store application-related metadata. Clients can use\n  the [VSS-rust-client] directly for this purpose. This can help provide a complete user data recovery solution for\n  applications, as well as enable turn-key multi-device support in the future.\n\n### Summary\n\nIn summary, VSS is an open-source project that offers a server-side cloud storage solution for non-custodial Lightning\nwallets. It provides multi-device access, recovery capabilities, and various features to ensure user privacy and data\nverifiability. By leveraging VSS, wallet developers can focus on building innovative Lightning wallets without the\nburden of implementing complex storage solutions from scratch.\n\n### Support\n\nIf you encounter any issues or have questions, feel free to open an issue on\nthe [GitHub repository](https://github.com/lightningdevkit/vss-server/issues). For further assistance or to discuss the\ndevelopment of VSS, you can reach out to us in the [LDK Discord] in the `#vss` channel.\n\n[VSS API contract]: https://github.com/lightningdevkit/vss-server/blob/main/proto/vss.proto\n\n[VSS-rust-client]: https://github.com/lightningdevkit/vss-rust-client\n\n[LDK-node]: https://github.com/lightningdevkit/ldk-node\n\n[LDK-Roadmap]: https://lightningdevkit.org/blog/ldk-roadmap/#vss\n\n[LDK Discord]: https://discord.gg/5AcknnMfBw\n\n[UniFFI]: https://mozilla.github.io/uniffi-rs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynonymdev%2Fvss-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynonymdev%2Fvss-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynonymdev%2Fvss-server/lists"}