Do you maintain a Bitcoin wallet? Then help the growing Bitcoin community to find it among all the others occupying this crowded space by self-managing it on WalletMatrix.
WalletMatrix wants vendors to manage their own data. After all, they know most about their own products. All that's needed is a simple JSON file added to your existing OSS GIthub repository (Vendors without a suitable repository, can self-manage on our own Github repository). All that's needed is to push an update when you add new wallet features and WalletMatrix will do the rest.
By keeping wallet information updated, the Bitcoin community benefits by having a reliable source of wallet information to refer to that won't become stale.
Because WalletMatrix enjoys referrals from some popular Bitcoin resources; vendors and maintainers enjoy greater exposure to their projects. The same can be said of our REST API when developers connect their apps and render wallet data outside of WalletMatrix itself.
Vendors also benefit by shaping future WalletMatrix JSON schema iterations. Have your say about the features and options that should become searchable by the Bitcoin community.
- Email: email@example.com
- Twitter: @walletmatrix
- About the WalletMatrix schema
- The WalletMatrix REST API
I'm keen, where do I sign up!?
If we haven't contacted you already, then all that's needed is for you to send an email to firstname.lastname@example.org with the following information:
- Your company or organisation name (Used to create your own, private data repository on GitHub)
- Your wallet name
- An email address and username
- The address and username should be associated with an existing Github repo (preferably an official wallet repo owned by your organisation). We'll send an invite to this address for granting access to your new private, DCentrica owned GiHub data repository.
- The address should also be associated with a public PGP key if you want users to be able to self-verify your data (recommended)
Once we hear from you, we'll setup your repository and respond with the repo URL and information about next steps.
Who are DCentrica?
DCentrica is the parent company of WalletMatrix, a small, bespoke software development shop based in New Zealand looking to specialise in software development using decentralised systems such as Bitcoin and IPFS.
How does it work?
If you're able to host a matrix.json file on a repository under your control, let us know and we'll issue a pull request against it. It's as simple as that. Otherwise, we can grant you access to a private Dcentrica repository on Github. In this case, we're assuming your developers already have a GitHub account so we just need you to supply us with a GitHub username and email address and we'll add that user to a dedicated, private GitHub repository.
Developers maintain a JSON file and commit changes each time new features should be added. WalletMatrix periodically consumes the GitHub data, validates and renders it on the website within the matrix itself and also via our REST API.
If you’re keen to take part, we’d love to hear from you: email@example.com.
What does the JSON file look like?
The file is named matrix.json and should validate against our version 3 JSON schema. Vendor data is automatically validated against the schema each time our automated import process runs. Validation failures are automatically detected and we're automatically notified.
We have two GitHub repos for our iOS and Android app, do these count as two separate wallets?
No. We don't support multiple data repos for the same wallet. Instead a single matrix.json file can contain all required data for multiple wallets. We assume an iOS and Android app for example comprise the same (or very similar) features of the same "wallet" and therefore only a single instance of matrix.json should exist. In this case the matrix.json data file can also be configured to contain Github references to both projects' repos too.
- You have developers!
- No admin login required, which is a reduced attack vector, and less hassle for vendors
Can we generate a UUID for a new wallet?
Sure! Use our web-service to generate a compatible v4 UUID: https://walletmatrix.app/api/v1/uuid.
Note: UUIDs are of course unique so multiple wallets shouldn't share a common UUID.
How do we validate our matrix.json against the schema?
How does self-validation for users work?
Wallet vendors can optionally digitally sign their matrix.json file using PGP by exporting a detached signature file and naming it matrix.asc. Once pushed to GitHub, and when WalletMatrix discovers this file, an extra validation process occurs during the periodic import process.
If the signature is valid for the associated matrix.json file, then a “shield” icon will be highlighted when your wallet appears in search results. Users can then select this in order to download the files and manually validate them using free and open source software tools.
We updated matrix.json but forgot to update matrix.asc, what happens now?
Not much! But while this remains the case, the automated validation process will fail which will result in users seeing the corresponding “shield” icon displaying as "faded" (aka un-verified) for your wallet, when displayed in search results. This means that users will not be able to download your files in order to self-verify.
You should create a new matrix.asc file and push that to your GitHub repo as soon as possible, so it can be processed in the next import run.
We changed our company name and updated matrix.json, but self-verification breaks. What happened?
The automated PGP validation system relies on there being a match between the "organisation.name" JSON field, and the DCentrica github repo slug. Future iterations will likely rely on a UUID which of course is not subject to change.
In the interim, if you need to change your organisation name, just let us know with as much notice as you can, and we’ll sort that for you.
What does it cost?
We welcome contributions from vendors who have the means to contribute and who may have benefited from their services being available on WalletMatrix. Email us to find out how: firstname.lastname@example.org.
While Web API requests are initially free, we do plan on introducing a tiered access model, priced and paid in Satoshi, using The Lightning Network.
How do you avoid Wallet Scams?
In order to ensure a minimum level of quality and to avoid scam projects, there's a handful of criteria that wallets should meet. See our Listing Policy to find out more.
How are wallets in the Matrix sorted?
In order to avoid gamification of search results by sorting by last-updated date, search results are instead ordered alphabetically by wallet name.
How often is new Wallet data automatically updated?
We pushed some changes, but they haven't appeared for over an hour. What's up?
Assuming you can rule-out browser or proxy caches that are showing you stale data, then it's likely your matrix.json hasn't validated correctly against our schema. Double check that then commit your changes and push again. We plan on introducing a dashboard feature so vendors can see at-a-glance the status of their wallet imports.
Note: There is currently no automated alert for you when this happens (It's in our backlog though).
Can we help with anything?
You sure can!
How can the current version 3 schema be improved? What does the WalletMatrix JSON Schema v4 look like? The schema is used to validate incoming data from GitHub. Our ideas right now are centred around fine-grained data points for Lightning Network features such as the following, but your suggestions are welcome. Flick us an email: email@example.com.
- Trampoline payments (Y|N)
- Auto channel funding (Y|N)
- Testnet (Y|N)
- Custodial (Y|N)
- Fees [0-9]%
- AMP (Y|N)
- In-app Bitcoin purchase (Y|N)
- Turbo channel aware (Y|N)
- Loop-in / Loop-out (Y|N)