A Lightweight Wallet for Sia

Recently I made a thing called narwal. In essence, it’s a “lite wallet” for Sia, enabling you to check your balance, send and receive siacoins, and even form and renew file contracts – all without downloading the Sia blockchain.

That’s a reasonably-good explanation, but it’s missing a lot of important details. To tell the truth, I’ve found it surprisingly difficult to condense what narwal is into a single sentence, or even a single paragraph. So here’s a more long-winded description that will hopefully do it justice. We’ll proceed in top-down fashion, with each section (hopefully) answering questions that arise after reading the previous section. Starting with…

What is narwal, really?

It’s a service that provides hosted walrus instances.

Okay, what is walrus?

It’s a Sia full node that functions as a watch-only wallet server. You tell walrus which addresses you care about, and it watches the Sia blockchain for those addresses. Then you can query walrus for transactions involving your addresses, outputs sent to your addresses, etc.

How is that a wallet?

It’s not, really; it’s more like an Electrum server. A walrus server by itself isn’t useful for much, but you can couple it with a client application to create a fully-featured wallet.

Here’s one way to think of it. A wallet requires two things: the blockchain, and a set of private keys. You need the blockchain in order to know which outputs you can spend, and you need private keys in order to sign transactions that spend those outputs. walrus handles the blockchain, and the client application handles your private keys.

I need something more concrete.

Okay. Let’s pretend that we have a single private key. We use that private key to generate an address, and we tell walrus to watch the blockchain for it. Later, someone sends 10 SC to our address. This creates an output worth 10 SC that we can spend using our private key. walrus sees this transaction and records the output; if we ask it for our current balance, it will say “10 SC.” Next, we want to create a transaction that sends 5 SC to a friend, and returns the remaining 5 SC to our address. We query walrus for the set of spendable outputs we control, and it replies with the 10 SC output. We can then construct a transaction that spends this output, and sign it using our private key. Once we broadcast this transaction, walrus will notice that the output has been spent, and remove it from our set of spendable outputs. If we ask it for our balance again, it will say “5 SC.”

That sounds like a lot of work!

Well, that’s why there are client applications to handle all those details for you. When you use a client application, you won’t see raw private keys or outputs; instead, you’ll see a nice graphical interface, much like Electrum or Sia-UI. Currently there is only one client for walrus (a CLI app called walrus-cli), but a mobile app is also under development.

What’s the point of splitting a wallet into client and server?

The split is advantageous for two reasons.

First, one server can service multiple clients. Processing the blockchain takes lots of disk space, bandwidth, and CPU time, so it’s more efficient to only do it once. You might run a walrus server on your desktop computer, for example, and run client applications on your laptop and phone. Or you might connect to a narwal server that services hundreds or thousands of clients.

Second, it means that your private keys are only stored on the client. This reduces attack surface: if someone hacks a narwal server, they won’t be able to steal everyone’s wallets. It also allows for flexibility in how the keys are generated and stored. You can derive your keys from a seed phrase on a Ledger Nano S, or generate them in your phone’s secure enclave, or read them from tea leaves; the server doesn’t care.

What’s the difference between walrus and narwal again?

narwal runs a walrus server for you in The Cloud™. It’s walrus-as-a-service! Alternatively, I suppose you could say that narwal is “hosted,” while walrus is “on-prem.” Here, maybe these diagrams will clear things up:

walrus is a full node, typically operated and used by a single person. It stores the Sia blockchain and a set of addresses. The client stores the private key for each address (or a seed capable of deriving such keys). Multiple clients can communicate with a single server, so you could (for example) check your balance using either your laptop or your phone.

narwal is also a full node, typically operated by an organization and used by many people. It uses a single copy of the blockchain to instantiate multiple "virtual" walrus servers. To a client, these virtual servers are indistinguishable from the real thing: each server can track a different set of addresses, and can service multiple clients (not shown here).


So I can run walrus myself?

Sure, and I strongly recommend doing so! When you run a walrus server, you’re running a full node that improves the health of the Sia network. Plus, since you’re running the server yourself, you don’t need to worry about it lying to you.

The server can lie??

Well, you should always assume that third-party services may be lying to you, especially when cryptocurrency is involved. A malicious narwal server can lie about lots of things: your balance, your transaction history, which outputs you control, etc. The server doesn’t possess your private keys, so it can’t directly steal your siacoins, but it can try to trick you into misusing those keys by lying. For example, imagine you agreed to sell someone a pizza in exchange for some SC; the server could lie and claim that you had been paid, when in reality no such transaction had occurred.

Can’t you use SPV like Electrum does?

No, because Sia doesn’t support SPV. And even if it did, I wouldn’t use it. The reality is that, if you’re not running a full node yourself, you’re trusting someone who is. Better to make that trust explicit, put big warnings around it, and provide mechanisms for attestation/repudiation.

Why would I ever use narwal, then?

Because it’s more convenient than running your own walrus server, without sacrificing too much security. walrus requires significant time, bandwidth, and disk space, and if you want to access your wallet remotely (e.g. from your phone), you’re responsible for securing that connection and keeping the server running 24/7. narwal handles all that for you: you just type in the server URL, and boom, you’re done. You can set up a working wallet in just a few minutes!

Furthermore, using narwal is still vastly more secure than storing your siacoins on an exchange. Even though a malicious narwal server can lie to you, at the end of the day, you control the private keys. Compare this to an exchange, which can be hacked, can exit-scam you, and can lock you out of your account at any moment. So if you’re currently storing siacoins on an exchange, and you’re looking for a more secure option (perhaps involving a hardware wallet), narwal is an excellent choice.

Is this compatible with siad?

That depends on what you mean. If you want to use an existing siad wallet seed with walrus or narwal, that’s certainly possible in theory, but there isn’t a client application that supports it yet. Instead, I recommend creating a new seed with walrus-cli and sending some coins to it.

How do I start?

Go to https://narwal.lukechampine.com to receive a personal walrus server URL. Then install walrus-cli and follow the instructions in the repo. Remember to pass your server URL to the -a flag in every command.

If you’re interested in developing a new client application, or you just want a better understanding of how walrus works, check out the server API docs or the source code.

Lastly, in case it wasn’t clear, you can run your own narwal server too! Currently, there’s only one public server (mine), so you would be providing the community with an alternative. If you’re interested in doing this, get in touch!