Skip to content

Public Alpha Guide

Jump to bottom Edit New page
bitcartel edited this page Aug 6, 2016 · 47 revisions

Zcash Technology Preview

Zcash currently only works on Linux. It is also recommended that your hardware has at least 4GB of memory and a few GB of free storage space. (We plan to improve the space-efficiency of our construction in the following months.)

In addition, the RPC interface is very "low-level" and a user interface has not been developed yet. The zcraw* commands will be replaced and deprecated prior to release.

Getting Help

If you run into snags, please let us know. There's plenty of work needed to make this usable and your input will help us prioritize the worst sharpest edges earlier. For user help, we recommend using our forum:

https://forum.z.cash/

Get Started

First install the dependencies. On Debian/Ubuntu-based systems:

sudo apt-get install \
    build-essential pkg-config libgtest-dev libc6-dev m4 \
    g++-multilib autoconf libtool ncurses-dev unzip git python \
    zlib1g-dev wget bsdmainutils

On Fedora-based systems:

sudo dnf install \
    git pkgconfig automake autoconf ncurses-devel python wget \
    gtest-devel gcc gcc-c++ libtool patch

Fetch our repository with git and run fetch-params.sh like so:

git clone https://github.com/zcash/zcash.git
cd zcash/
git checkout zc.v0.11.2.z7
./zcutil/fetch-params.sh

This will fetch our public alpha proving and verifying keys and place them into ~/.zcash-params/. These keys are, together, nearly 1.5GB in size, so it may take some time to download them.

Upgrading?

If you're upgrading from an older alpha release, try these commands instead:

git fetch origin
git checkout zc.v0.11.2.z7
./zcutil/fetch-params.sh

Compiling

Ensure you have successfully installed all system package dependencies as described above. Then run the build:

./zcutil/build.sh -j4

This should compile our dependencies and build zcashd.

Testing

The tests take a while to run. If you would rather get started right away, you can skip to the next section. If you want to run the tests to make sure Zcash is working, run:

./qa/zcash/full-test-suite.sh

You can also run the RPC tests, which take much longer:

./qa/pull-tester/rpc-tests.sh

The tests need at least 8 GB of memory, possibly more, to run successfully. An out-of-memory error will usually cause a FAIL or ERROR outcome with "std::bad_alloc" somewhere in the output.

Running

Place a configuration file at ~/.zcash/zcash.conf (you may need to mkdir ~/.zcash) with the following contents (you don't need to modify anything):

testnet=1
addnode=alphatestnet.z.cash
rpcuser=username
rpcpassword=password

Now, run the daemon!

./src/zcashd -daemon

You should be able to use the RPC after it finishes loading. Here's a quick way to test:

./src/zcash-cli getinfo

NOTE: If you are familiar with bitcoind's RPC interface, you can use many of those calls to send Zcash testcoins between "transparent" (Bitcoin-style) addresses, but we do not support and do not recommend you use the 'Accounts' feature which has been deprecated in bitcoind.

Getting Zcash Testcoins

You need test zcash! You can mine it, but you'd probably be better off just asking us for some, since we've mined a lot ourselves. Zcash on the testnet doesn't have any value. Be prepared for the testnet to be reset which will cause you to lose your Zcash testcoins.

Generate a new "transparent" (Bitcoin-style) address like so:

./src/zcash-cli getnewaddress
mojH91FkurYJzQyYEVFRBYxTNbsUpPkJEQ

Then come visit us on irc.oftc.net in channel #zcash and we'll gladly give you some! Then come back here for the remaining instructions.

(If you want to help us set up a faucet, let us know!)

Protecting your testcoins

Your testcoins are currently "transparent," so let's protect them by sending them to a Zcash address.

First, generate an address.

./src/zcash-cli zcrawkeygen
{
    "zcaddress" : "920205e7e7a83c117929b0f39ff36e60a6d06773c6cc17f7e19caa36e85676503530d43a343642c0752aeefc2ca1621a3d47085ca9294d06cd1d68e7619cccc458",
    "zcsecretkey" : "c092c80760738eabff003dd92b236d50dbbf1ae736d3c52a2c5a706deea7cbf3",
    "zcviewingkey" : "600d49455c31bb723f5e06374c5aa957049501001111fff03e53ffffaaf07646"
}

zcaddress is the public address you can give to others to receive protected Zcash. zcsecretkey is the private address used to spend value which is sent to the zcaddress. These addresses are pretty large right now, and are not encoded or compressed, so it's easy to make mistakes with them. Let's put them in environment variables to avoid mistakes:

ZCADDRESS=920205e7e7a83c117929b0f39ff36e60a6d06773c6cc17f7e19caa36e85676503530d43a343642c0752aeefc2ca1621a3d47085ca9294d06cd1d68e7619cccc458
ZCSECRETKEY=c092c80760738eabff003dd92b236d50dbbf1ae736d3c52a2c5a706deea7cbf3

In order to send your "transparent" testcoins to your Zcash address, a process we sometimes call "protecting", let's begin by making a raw transaction.

Run this command to see your unspent testcoins:

./src/zcash-cli listunspent

You should see something like:

[
    {
        "txid" : "e3eb7d61e9f98162ac5301c94573d9ce9d50131fe4d108a56fdd7d73418478fb",
        "vout" : 0,
        "address" : "mx46njzjTWhZnFXMkCLnMkBWf6yRW2VGxV",
        "scriptPubKey" : "210301bd1b356f310430c4054dae2ad542b5f3954784d9dfec48a79ab4f42e87a127ac",
        "amount" : 50.00000000,
        "confirmations" : 1520,
        "spendable" : true
    }
]

Notice that this particular "UTXO" has a value of 50 test-ZEC -- yours may be different. Using one of your unspent outputs, create the raw transaction by copying and pasting the txid and vout fields you got from listunspent like so:

RAWTX=$(./src/zcash-cli createrawtransaction '[{"txid":"e3eb7d61e9f98162ac5301c94573d9ce9d50131fe4d108a56fdd7d73418478fb","vout":0}]' '{}')

This will place the raw transaction in the environment variable RAWTX. It sends the entire value (in my case, 50 test-ZEC) as a fee, but we're going to use another operation to send it to our private zcash address:

./src/zcash-cli zcrawjoinsplit "$RAWTX" '{}' "{\"$ZCADDRESS\":49.9}" 49.9 0

(The name of this RPC call changed from zcrawpour to zcrawjoinsplit in the z7 release, and some other calls and field names have also changed.)

In this case, I'm taking 50 testcoins from my UTXO, sending 49.9 of them to my zcaddress, and producing 0.1 as a fee for the transaction. The balance of your transaction must work out or you will get errors!

This operation (called a JoinSplit) might take a minute or two depending on your hardware. It is producing a zero-knowledge proof. (This operation's performance will be improved in the coming months.)

When it's done, it'll produce an output like this:

{
    "encryptednote1" : "0012fab373559c00d1396dd9f6b1392908ad4b91654bcb674241dedfae6b5bb40b1ab3a0ab1b0dc20495e7a668e70f43be26172df6a480b45544077b533256ee23a4ea9d4976fb4635ed9424a0b63a429486e7c073b24f00cdeb141282ffccfba60c25239d4fabcd2f1dc5db3f1a1406b15a2e0bc302e7b2a9d69b142d2549e930172ec6c3a2ba1806cd2d502bba1c8faa623201489890b95333ab29d7af5998fa3111e02081e55a6d807520270c95529d602b9b80505a68a2066fdf793177e9e30d1efd5573874a2f0e5cb2a3fab5d1ce6c8b99e69e3a307847af31f7dbdb89c3e29d0203f621965308c2b49e797196af95f130084c336bb780de74fcdc962d5b3428ba7f381d4d7078e0cf78a4801a0614205b36e7038f6b9c",
    "encryptednote2" : "0112fab373559c00d1396dd9f6b1392908ad4b91654bcb674241dedfae6b5bb40b53e0ae1e69896dc62f080c3a621c72e4deffdb814f15636cede36af37706cd0560d639b706b735d251a6cfe4b1c7b9f6e9d2ba1eebcc50289feac93ed28d36c96288f994e14cfb669f258d09602bd408c5b356ce89458edb60ae8d3343e290f1ff19d8f4ca25216279e46367a4a3978f23f8ac70a6b0b12c2cc6e982c0bf064400a7bc8489bbc740b25f2e87c81d64855774fef5878bd095d5cca0b03121c113731ca0341c5e6635d69f5041952fa275d7ef97417ebebbb12809efa4da028acdfb850e2c5a97114fb6b931b169c08d6b952e701680650b3ea1de74fcdc962d5b3428ba7f381d4d7078e0cf78a4801a0614205b36e7038f6b9c",
    "rawtxn" : "0200000001ffc72812eeb7873498b17410b99ff22ed12ea82a3f72e80aa874d8a097aa17dd0000000000ffffffff00000000000100a3e11100000000000000000000000000000000000000000000000000000000000000000000000000000000000000001327e74dd5b63a968c280e56969d67f46312b4b320616aebff607ae469ebb6699524f014d7f3245b36eb21dc1475c5f65901eaaae910e2d8dccf46ba145ff1388e1a8d5f6c462f1c30d4cff2c12864e761136cc514ba25be53817f4ba595e99cf6bbfe4c555545340ce76587d95caf48d671e985c581d5ec766487b44ca4529e1ab3a0ab1b0dc20495e7a668e70f43be26172df6a480b45544077b533256ee23a4ea9d4976fb4635ed9424a0b63a429486e7c073b24f00cdeb141282ffccfba60c25239d4fabcd2f1dc5db3f1a1406b15a2e0bc302e7b2a9d69b142d2549e930172ec6c3a2ba1806cd2d502bba1c8faa623201489890b95333ab29d7af5998fa3111e02081e55a6d807520270c95529d602b9b80505a68a2066fdf793177e9e30d1efd5573874a2f0e5cb2a3fab5d1ce6c8b99e69e3a307847af31f7dbdb89c3e29d0203f621965308c2b49e797196af95f130084c336bb78053e0ae1e69896dc62f080c3a621c72e4deffdb814f15636cede36af37706cd0560d639b706b735d251a6cfe4b1c7b9f6e9d2ba1eebcc50289feac93ed28d36c96288f994e14cfb669f258d09602bd408c5b356ce89458edb60ae8d3343e290f1ff19d8f4ca25216279e46367a4a3978f23f8ac70a6b0b12c2cc6e982c0bf064400a7bc8489bbc740b25f2e87c81d64855774fef5878bd095d5cca0b03121c113731ca0341c5e6635d69f5041952fa275d7ef97417ebebbb12809efa4da028acdfb850e2c5a97114fb6b931b169c08d6b952e701680650b3ea112fab373559c00d1396dd9f6b1392908ad4b91654bcb674241dedfae6b5bb40bbf76a6fc17d0531941c36ee5ff0ad85f4aac2829357282649f69de61f277afaf9ac9cf8f8d61e9e657fc99bd99dcf4120c0559179db459b6d55a0e735df84d8a9a8ec63a6bbe7c61e65a2745afbcf0f3f00dd95acfd0ab34d5e99e3e4c033696fd840530203137383633313135383038313133303830353433303039313836353638393036383638303330323936383131303130393035363930313232353831303731313334303234343938383336313439203134303138323934313335343130303734323636303837313839313232323236393438313834303030373831373635313730383230383630393232363631323437323635353931303534313839203020313638383731353332363338363934323631383038353231383634373530373238333031393438303631313732343239343234393937323739353030373332313030343834393936353935313520323531323436313635313837313331373836303437393336343439323331343936323835393336363839383834303637353037343435343733313435343632323237333033383738303131360a30203132373931363834363338333733363236303738373435313938383633333935363537313536373838343632383035363237363039373533343635383730393538313537343731343639333335203230313836323238353431343832373330313130323437343439343135303034373533363837323738323232333333363231373033323036333437333532393130303535333339373437333220323932353437333731363433383935303937323637313330323030383334373739323430323132343835393539373533353538343135363733383637303434323132363538313739303538302031373039303231323239323735313435343039383633383431333233383730363636353939353330363032363136303237323135343836363638303235353037353038303736383437393731382030203231323834333934383937313336393539313732383937343633393135313732333339393737313231363931333539383136383035343436383230333835323230323632323436383634363733203234363733343738313336323039373036343134323137383938313938383330373035343230323836353536333732333635333139373734333230363036393338303630353538373631310a3020313039303734323533333832383934393139303337333234333036333432373136373436333836323235333732323439393930363230303937353236393732303232333536373735363837343420353334303539303036343732343034383139363235383138323338323937383237313334313732353732323731323032333534363231353932333932343430383938343130343031333738362030203739353735353232333835393637333234383834373439333937343936323533363033303237363432353333393437383536303935363638313338313333373539353631353031383834363220383333303333333139363132353234303730333536393038343039363831323135303833333636383033393333303534313433303436303835363631333034393232353234383936333336300a302031353534323737343439373030383332313234303736363738363932373932383634383231333138383331323437383636323130383030323238313430343939373130363134353935313030332031313538353830313133353633323433383036303631343739343931383239303530333830363239323132333330333635323034323731393739333731363333373239313734313932303833350a302032303434393934343638313332363431373833353135303132353433303132363132323735333337333039333933383537393134303037323531333733383831363537363739373330393930362031323333353537343636343434393832343936363833343932373230363635353037363332343735313630363731343235333532323336333831323830353735333135373234323534333931330a"
}

encryptednote1 is an encrypted "note" which you must send to your recipient. In this case, that's you! encryptednote2 is another encrypted note, but in our transaction we only have one output, so this note is of zero value; don't worry about it. rawtxn is the raw transaction with the joinsplit added.

Now, sign the raw transaction, by copying and pasting the rawtxn field from the output you got from zcrawjoinsplit:

./src/zcash-cli signrawtransaction "$RAWTXN_FROM_ZCRAWJOINSPLIT"

You should be able to now send the result of that operation (the hex field) over the network as a complete transaction.

./src/zcash-cli sendrawtransaction "$RAWTXN_FROM_SIGNRAWTRANSACTION"

If it returns a transaction ID, congrats! It needs to enter a block before it can be spent -- this helps make it indistinguishable and simplifies consensus rules. Let's use the zcrawreceive RPC now.

./src/zcash-cli zcrawreceive $ZCSECRETKEY $ENCRYPTEDNOTE1

This will decrypt encryptednote1 -- it should show the correct value, and return a note which you need for spending later. This is a sample output:

{
    "amount" : 49.90000000,
    "note" : "805b6d290100000020876b2852235d7415e4e9b8b00ed28e953cf715849c0655fad8d04cb60f0a99313030e65eba908d007b92d3fb4e8ccb9d8279698c23cc89a0cc1c4628f0266f6f6d9eab499eff588e44d8db583b23da676a",
    "exists" : true
}

The note is like a UTXO that only you and the sender know about, and only you can spend. The exists field specifies whether this is a valid note (i.e. it is in the blockchain).

Sending Zcash

Once you've "protected" your test-Zcash -- you have a note from zcrawreceive, and you have zcsecretkey/zcaddress -- you can send value to others pretty painlessly.

Let's create a standard transaction with no inputs and outputs to serve as the base.

./src/zcash-cli createrawtransaction '[]' '{}'

This should produce:

01000000000000000000

Let's say our friend's zcaddress is 926511379d00e6a128e9f254aa2133d360e954c6cd54e7c938f96a4affebea8ccd9cc5998868141f055a4242b884f2e8eb9a0237dedbb9e2f04a378816f8e2e15c.

Let's send 10 test-ZEC to this person for a pizza.

./src/zcash-cli zcrawjoinsplit 01000000000000000000 "{\"805b6d290100000020876b2852235d7415e4e9b8b00ed28e953cf715849c0655fad8d04cb60f0a99313030e65eba908d007b92d3fb4e8ccb9d8279698c23cc89a0cc1c4628f0266f6f6d9eab499eff588e44d8db583b23da676a\":\"$ZCSECRETKEY\"}" '{"926511379d00e6a128e9f254aa2133d360e954c6cd54e7c938f96a4affebea8ccd9cc5998868141f055a4242b884f2e8eb9a0237dedbb9e2f04a378816f8e2e15c":10,"920205e7e7a83c117929b0f39ff36e60a6d06773c6cc17f7e19caa36e85676503530d43a343642c0752aeefc2ca1621a3d47085ca9294d06cd1d68e7619cccc458":39.8}' 0 0.1

As you can see, we sent 39.8 test-ZEC back to our zcaddress as change, and sent 0.1 as a fee.

To make the outputs spendable, we need to sign and send the transaction (like we did earlier when protecting the coins):

./src/zcash-cli signrawtransaction "$RAWTXN_FROM_ZCRAWJOINSPLIT"
./src/zcash-cli sendrawtransaction "$RAWTXN_FROM_SIGNRAWTRANSACTION"

Send the first encrypted note to your friend. They should be able to zcrawreceive it with their zcsecretkey like you did earlier. The second encrypted note is the "change output" which you should keep so that you can spend it!

Uprotecting Zcash

Instead of paying for a pizza, let's say you wanted to send your protected test-Zcash to a friend who is using a "transparent" address (Bitcoin-style). Whatever amount of test-Zcash being sent to your friend will be unprotected.

Your friends "transparent" address is mrHHYArYuCg86Mfy8GJpHK1dmvZWW7nEg6. We create a standard transaction with no inputs and use your friend's address as an output.

 ./src/zcash-cli createrawtransaction '[]' '{"mrHHYArYuCg86Mfy8GJpHK1dmvZWW7nEg6":10.0}'

This should produce:

01000000000100ca9a3b000000001976a91476139faccf9b7449a8d0db0eb051705dbe83f6dd88ac00000000

Now, let's finish building the transaction.

./src/zcash-cli zcrawjoinsplit 01000000000100ca9a3b000000001976a91476139faccf9b7449a8d0db0eb051705dbe83f6dd88ac00000000 "{\"805b6d290100000020876b2852235d7415e4e9b8b00ed28e953cf715849c0655fad8d04cb60f0a99313030e65eba908d007b92d3fb4e8ccb9d8279698c23cc89a0cc1c4628f0266f6f6d9eab499eff588e44d8db583b23da676a\":\"$ZCSECRETKEY\"}" '{"920205e7e7a83c117929b0f39ff36e60a6d06773c6cc17f7e19caa36e85676503530d43a343642c0752aeefc2ca1621a3d47085ca9294d06cd1d68e7619cccc458":39.8}' 0 10.1

As you can see, we are sending 39.8 test-ZEC back to our zcaddress, and sending 0.1 as a fee. The total amount of test-ZEC which will become unprotected as a result of this transaction is 10.1.

To make the outputs spendable, we need to sign and send the transaction, like we did earlier:

./src/zcash-cli signrawtransaction "$RAWTXN_FROM_ZCRAWJOINSPLIT"
./src/zcash-cli sendrawtransaction "$RAWTXN_FROM_SIGNRAWTRANSACTION"

Your friend can verify the transaction manually:

./src/zcash-cli getrawtransaction $TXID 1
Add a custom footer
Add a custom sidebar
Clone this wiki locally