Go to file
oscar-pepper c7dddecfe9 Update darksidewalletd.md 2023-11-28 13:52:06 -07:00
.github add Sapling and Orchard tree commitment sizes to GetBlock result 2023-06-04 22:26:17 -06:00
cmd add --sync-from-height command-line option 2022-05-24 15:17:38 -05:00
common darksidewallet: GetLightdInfo with no blocks shouldn't crash 2023-09-04 15:06:00 -06:00
docker revert unintended docker/zcash.conf change 2020-04-09 10:27:08 -06:00
docs Update darksidewalletd.md 2023-11-28 13:52:06 -07:00
frontend fail during startup if rpcpassword not specified 2023-10-26 14:47:24 -06:00
kubernetes/tekton Added serviceaccount for tekton 2020-08-31 09:55:32 -04:00
parser darkside: Store, track, and expose commitment tree sizes 2023-08-16 10:34:38 -06:00
tekton Added tekton for Docker image build 2020-03-23 15:01:04 -04:00
testclient add a gRPC test client for performance measurement and stress testing 2020-03-19 21:10:47 -06:00
testdata test: follow-on to PR 440 - update test vectors 2023-07-04 11:36:13 -06:00
testtools eliminate genblocks compile warning 2021-04-07 10:45:46 -06:00
utils fix pullblocks.sh for macOS 2020-11-04 08:25:14 -07:00
walletrpc add comments that GetTaddressTxids() returns transactions 2023-10-19 16:37:22 -06:00
.codecov.yml Update .codecov.yml 2019-10-29 16:21:39 -07:00
.env.template Moved HTTP endpoint startup to a fucntion 2020-04-09 10:27:08 -06:00
.gitignore remove vendor, clean up module files and Makefile 2022-06-10 14:47:01 -06:00
.gitlab-ci.yml Updated Makefile for new build options 2020-03-18 08:56:29 -06:00
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 2019-09-19 19:26:16 -07:00
CONTRIBUTING.md Fix typos 2020-12-21 13:03:41 -07:00
COPYING add COPYING and copyright lines 2020-03-12 12:02:55 -06:00
Dockerfile Update Dockerfile 2023-07-07 07:53:35 -06:00
LICENSE Create LICENSE 2019-09-19 19:21:48 -07:00
Makefile Fix typos 2023-01-02 13:11:15 -07:00
README.md Fix README's suggested zcashd configuration 2023-09-03 15:34:07 -06:00
buildenv.sh Added per-instance password by moving to an environment build script. 2019-12-20 14:15:45 -08:00
docgen.sh add documentation for lightwalletd APIs and data types 2020-03-02 17:21:41 -07:00
docker-compose.yml Revert "Update compose for new LWD config params" 2020-06-08 13:27:16 -04:00
go.mod Bump google.golang.org/grpc from 1.53.0 to 1.56.3 2023-11-28 13:13:56 -07:00
go.sum Bump google.golang.org/grpc from 1.53.0 to 1.56.3 2023-11-28 13:13:56 -07:00
lightwalletd-example.yml Example usage of cobra and viper for configuration 2020-03-18 08:56:29 -06:00
main.go rebase PR 175 - Use cobra and viper for configuration 2020-03-18 12:13:30 -06:00


pipeline status codecov

Security Disclaimer

lightwalletd is under active development, some features are more stable than others. The code has not been subjected to a thorough review by an external auditor, and recent code changes have not yet received security review from Electric Coin Company's security team.

Developers should familiarize themselves with the wallet app threat model, since it contains important information about the security and privacy limitations of light wallets that use lightwalletd.


lightwalletd is a backend service that provides a bandwidth-efficient interface to the Zcash blockchain. Currently, lightwalletd supports the Sapling protocol version and beyond as its primary concern. The intended purpose of lightwalletd is to support the development and operation of mobile-friendly shielded light wallets.

lightwalletd is a backend service that provides a bandwidth-efficient interface to the Zcash blockchain for mobile and other wallets, such as Zecwallet.

To view status of CI pipeline

To view detailed Codecov report

Documentation for lightwalletd clients (the gRPC interface) is in docs/rtd/index.html. The current version of this file corresponds to the two .proto files; if you change these files, please regenerate the documentation by running make doc, which requires docker to be installed.

Local/Developer docker-compose Usage


Local/Developer Usage


You must start a local instance of zcashd, and its .zcash/zcash.conf file must include the following entries (set the user and password strings accordingly):


The zcashd can be configured to run mainnet or testnet (or regtest). If you stop zcashd and restart it on a different network (switch from testnet to mainnet, for example), you must also stop and restart lightwalletd.

It's necessary to run zcashd --reindex one time for these options to take effect. This typically takes several hours, and requires more space in the .zcash data directory.

Lightwalletd uses the following zcashd RPCs:

  • getinfo
  • getblockchaininfo
  • getbestblockhash
  • z_gettreestate
  • getblock
  • getrawtransaction
  • sendrawtransaction
  • getrawmempool
  • getaddresstxids
  • getaddressbalance
  • getaddressutxos


First, install Go version 1.17 or later. You can see your current version by running go version.

Clone the current repository into a local directory that is not within any component of your $GOPATH ($HOME/go by default), then build the lightwalletd server binary by running make.


Assuming you used make to build the server, here's a typical developer invocation:

./lightwalletd --no-tls-very-insecure --zcash-conf-path ~/.zcash/zcash.conf --data-dir . --log-file /dev/stdout

Type ./lightwalletd help to see the full list of options and arguments.

Production Usage

Run a local instance of zcashd (see above), except do not specify --no-tls-very-insecure. Ensure Go version 1.17 or later is installed.

x509 Certificates You will need to supply an x509 certificate that connecting clients will have good reason to trust (hint: do not use a self-signed one, our SDK will reject those unless you distribute them to the client out-of-band). We suggest that you be sure to buy a reputable one from a supplier that uses a modern hashing algorithm (NOT md5 or sha1) and that uses Certificate Transparency (OID will be present in the certificate).

To check a given certificate's (cert.pem) hashing algorithm:

openssl x509 -text -in certificate.crt | grep "Signature Algorithm"

To check if a given certificate (cert.pem) contains a Certificate Transparency OID:

echo " certTransparency Certificate Transparency" > oid.txt
openssl asn1parse -in cert.pem -oid ./oid.txt | grep 'Certificate Transparency'

To use Let's Encrypt to generate a free certificate for your frontend, one method is to:

  1. Install certbot
  2. Open port 80 to your host
  3. Point some forward dns to that host (some.forward.dns.com)
  4. Run
certbot certonly --standalone --preferred-challenges http -d some.forward.dns.com
  1. Pass the resulting certificate and key to frontend using the -tls-cert and -tls-key options.

To run production SERVER

Example using server binary built from Makefile:

./lightwalletd --tls-cert cert.pem --tls-key key.pem --zcash-conf-path /home/zcash/.zcash/zcash.conf --log-file /logs/server.log

Block cache

lightwalletd caches all blocks from Sapling activation up to the most recent block, which takes about an hour the first time you run lightwalletd. During this syncing, lightwalletd is fully available, but block fetches are slower until the download completes.

After syncing, lightwalletd will start almost immediately, because the blocks are cached in local files (by default, within /var/lib/lightwalletd/db; you can specify a different location using the --data-dir command-line option).

lightwalletd checks the consistency of these files at startup and during operation as these files may be damaged by, for example, an unclean shutdown. If the server detects corruption, it will automatically re-downloading blocks from zcashd from that height, requiring up to an hour again (no manual intervention is required). But this should occur rarely.

If lightwalletd detects corruption in these cache files, it will log a message containing the string CORRUPTION and also indicate the nature of the corruption.

Darksidewalletd & Testing

lightwalletd now supports a mode that enables integration testing of itself and wallets that connect to it. See the darksidewalletd docs for more information.

Pull Requests

We welcome pull requests! We like to keep our Go code neatly formatted in a standard way, which the standard tool gofmt can do. Please consider adding the following to the file .git/hooks/pre-commit in your clone:


modified_go_files=$(git diff --cached --name-only -- '*.go')
if test "$modified_go_files"
    need_formatting=$(gofmt -l $modified_go_files)
    if test "$need_formatting"
        echo files need formatting (then don't forget to git add):
        echo gofmt -w $need_formatting
        exit 1

You'll also need to make this file executable:

$ chmod +x .git/hooks/pre-commit

Doing this will prevent commits that break the standard formatting. Simply run the gofmt command as indicated and rerun the git add and git commit commands.