Skip to content

ZIP 400: Update wallet schema #968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dorianvp wants to merge 19 commits into
base: main
Choose a base branch
from
Open

ZIP 400: Update wallet schema #968

Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
60dbe00
ZIP 400: add fields from v4, v5 and v6
dorianvp Dec 19, 2024
b9e5a0d
Add recipientmapping & fix versions
dorianvp Dec 31, 2024
1713bb3
fix: typo
dorianvp Dec 31, 2024
9a4b654
ZIP 400: Add descriptions for new keys and the `Version` column, and …
dorianvp Jan 7, 2025
837c2bb
ZIP 400: Clarify `Version` column meaning
dorianvp Jan 8, 2025
22b3147
ZIP 400: Indicate disabled properties, add replacement information fo…
dorianvp Jan 15, 2025
b8ba40e
ZIP 400: Fix amount of times `cscript` can appear
dorianvp Jan 21, 2025
2d5f06d
Remove space
dorianvp Feb 23, 2025
81f3dd5
Update `UFVKEncoding` to `protocol-orchardencodings`
dorianvp Feb 23, 2025
463de57
Update reference to `protocol-orchardencodings` and render latest cha…
dorianvp Feb 23, 2025
4400dcf
Update zips/zip-0400.rst
dorianvp Feb 23, 2025
268fc0c
`zips-issue350` citation
dorianvp Feb 23, 2025
31cb49f
Update reference to `zips-issue350`
dorianvp Feb 23, 2025
dec428b
Add type for `sapextfvk` key
dorianvp Feb 23, 2025
21d7339
Add type for `minversion` key
dorianvp Feb 23, 2025
4dbd4b6
Merge branch 'main' into zip400-update
dorianvp May 18, 2025
61a71ef
fix(zip400): remove unused `wkey`
dorianvp May 18, 2025
4b3864f
fix(zip400): remove `acc` and `acentry` fields
dorianvp May 18, 2025
fc1e0e9
fix(zip400): remove `Terminology` section & reference to BCP14
dorianvp May 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 49 additions & 44 deletions zips/zip-0400.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,6 @@
License: MIT


Terminology
===========

The key words "MUST" and "MAY" in this document are to be interpreted as described in
BCP 14 [#BCP14]_ when, and only when, they appear in all capitals.

Abstract
========

Expand Down Expand Up @@ -43,46 +37,57 @@ Here ``zkey`` is the property name located at the first position of the database
Schema
------

According to Zcash v3.0.0-rc1 the following key-values can be found: the property names in **bold** mean only one instance of this type can exist in the entire database, while the others, suffixed by '\*' can have multiple instances. Keys and Values columns of the table contain the types that the stored data is representing. Included also there are the variable names hoping it will add some clarity to what the stored data is representing.
The following key-values can be found: the property names in **bold** mean only one instance of this type can
exist in the entire database, while the others, suffixed by '\*' can have multiple instances. Keys and Values columns of the table
contain the types that the stored data is representing. The Version column indicates the zcashd version(s) that create databases containing this key.
Included also there are the variable names hoping it will add some clarity to what the stored data is representing.

.. csv-table::
:header: "Name", "Description", "Keys", "Values"

"acc*", "Account data", "1. ``string strAccount``", "1. ``CAccount account``"
"acentry*", "Track internal transfers between accounts in the same wallet", "1. ``string strAccount``
2. ``uint64_t nNumber``", "1. ``CAccountingEntry acentry``"
"**bestblock**", "The current best block of the blockchain.", "", "1. ``CBlockLocator locator``"
"**chdseed**", "Encrypted HD seed", "1. ``uint256 seedFp``", "1. ``vector<unsigned char> vchCryptedSecret``"
"ckey*", "Encrypted transparent pubkey and private key.", "1. ``vector<unsigned char> vchPubKey``", "1. ``vector<unsigned char> vchPrivKey``"
"csapzkey*", "Encrypted Sapling pubkey and private key.", "1. ``libzcash::SaplingIncomingViewingKey ivk``", "1. ``libzcash::SaplingExtendedFullViewingKey extfvk``
:header: "Version", "Name", "Description", "Keys", "Values"
:align: left

"3..6", "**bestblock**", "The current best block of the blockchain.", "", "1. ``CBlockLocator locator``"
"3..4", "**chdseed**", "Encrypted HD seed. Replaced by ``cmnemonicphrase`` in later versions.", "1. ``uint256 seedFp``", "1. ``vector<unsigned char> vchCryptedSecret``"
"3..6", "ckey*", "Encrypted transparent pubkey and private key.", "1. ``vector<unsigned char> vchPubKey``", "1. ``vector<unsigned char> vchPrivKey``"
"3..6", "csapzkey*", "Encrypted Sapling pubkey and private key.", "1. ``libzcash::SaplingIncomingViewingKey ivk``", "1. ``libzcash::SaplingExtendedFullViewingKey extfvk``
2. ``vector<unsigned char> vchCryptedSecret``"
"**cscript**", "Serialized script, used inside transaction inputs and outputs", "1. ``uint160 hash``", "1. ``CScript script``"
"czkey*", "Encrypted Sprout pubkey and private key.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``uint256 rkValue``
"3..6", "cscript\*", "Serialized redeem script, used inside transaction inputs and outputs", "1. ``uint160 hash``", "1. ``CScript script``"
"3..6", "czkey*", "Encrypted Sprout pubkey and private key.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``uint256 rkValue``
2. ``vector<unsigned char> vchCryptedSecret``"
"**defaultkey**", "Default Transparent key.", "", "1. ``CPubKey CWallet::vchDefaultKey``"
"destdata*", "Adds a destination data tuple to the store.", "1. ``std::string strAddress``
"3..6", "**defaultkey**", "Default Transparent key.", "", "1. ``CPubKey CWallet::vchDefaultKey``"
"3..6", "destdata*", "Adds a destination data tuple to the store.", "1. ``std::string strAddress``
2. ``std::string strKey``", "1. ``std::string strValue``"
"**hdchain**", "Hierarchical Deterministic chain code, derived from seed.", "", "1. ``CHDChain chain``"
"hdseed*", "Hierarchical Deterministic seed. [#zip-0032]_", "1. ``uint256 seedFp``", "1. ``RawHDSeed rawSeed``"
"key*", "Transparent pubkey and privkey.", "1. ``CPubKey vchPubKey``", "1. ``CPrivKey pkey``"
"keymeta*", "Transparent key metadata.", "1. ``CPubKey vchPubKey``", "1. ``CKeyMetadata keyMeta``"
"**minversion**", "Wallet required minimal version.", "", ""
"**mkey**", "Master key, used to encrypt public and private keys of the database.", "1. ``unsigned int nID``", "1. ``CMasterKey kMasterKey``"
"name*", "Name of an address to insert in the address book.", "1. ``string strAddress``", "1. ``string strAddress``"
"**orderposnext**", "Index of next tx.", "", "1. ``int64_t nOrderPosNext``"
"pool*", "", "1. ``int64_t nIndex``", "1. ``CKeyPool keypool``"
"purpose*", "Short description or identifier of an address.", "1. ``string strAddress``", "1. ``string strPurpose``"
"sapzaddr*", "Sapling z-addr Incoming Viewing key and address.", "1. ``libzcash::SaplingPaymentAddress addr``", "1. ``libzcash::SaplingIncomingViewingKey ivk``"
"sapextfvk*", "Sapling Extended Full Viewing Key", "", ""
"sapzkey*", "Sapling Incoming Viewing Key and Extended Spending Key", "1. ``libzcash::SaplingIncomingViewingKey ivk``", "1. ``libzcash::SaplingExtendedSpendingKey key``"
"tx*", "Store all transactions that are related to wallet.", "1. ``uint256 hash``", "1. ``CWalletTx wtx``"
"**version**", "The ``CLIENT_VERSION`` from ``clientversion.h``.", "", "1. ``int nFileVersion``"
"vkey*", "Sprout Viewing Keys.", "1. ``libzcash::SproutViewingKey vk``", "1. ``char fYes``"
"watchs*", "Watch-only t-addresses.", "1. ``CScript script``", "1. ``char fYes``"
"**witnesscachesize**", "Shielded Note Witness cache size.", "", "1. ``int64_t nWitnessCacheSize``"
"wkey*", "Wallet key.", "", ""
"zkey*", "Sprout Payment Address and Spending Key.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``libzcash::SproutSpendingKey key``"
"zkeymeta*", "Sprout Payment Address and key metadata.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``CKeyMetadata keyMeta``"
"3..6", "**hdchain**", "Hierarchical Deterministic chain code, derived from seed.", "", "1. ``CHDChain chain``"
"3..4", "hdseed*", "Hierarchical Deterministic seed. [#zip-0032]_ Replaced by ``mnemonicphrase`` in later versions.", "1. ``uint256 seedFp``", "1. ``RawHDSeed rawSeed``"
"3..6", "key*", "Transparent pubkey and privkey.", "1. ``CPubKey vchPubKey``", "1. ``CPrivKey pkey``"
"3..6", "keymeta*", "Transparent key metadata.", "1. ``CPubKey vchPubKey``", "1. ``CKeyMetadata keyMeta``"
"3..6", "**minversion**", "Wallet required minimal version.", "", "1. ``int nVersion``"
"3..6", "**mkey**", "Master key, used to encrypt public and private keys of the database.", "1. ``unsigned int nID``", "1. ``CMasterKey kMasterKey``"
"3..6", "name*", "Name of an address to insert in the address book.", "1. ``string strAddress``", "1. ``string strAddress``"
"3..6", "**orderposnext**", "Index of next tx.", "", "1. ``int64_t nOrderPosNext``"
"3..6", "pool*", "", "1. ``int64_t nIndex``", "1. ``CKeyPool keypool``"
"3..6", "purpose*", "Short description or identifier of an address.", "1. ``string strAddress``", "1. ``string strPurpose``"
"3..6", "sapzaddr*", "Sapling z-addr Incoming Viewing key and address.", "1. ``libzcash::SaplingPaymentAddress addr``", "1. ``libzcash::SaplingIncomingViewingKey ivk``"
"3..6", "sapextfvk*", "Sapling Extended Full Viewing Key", "1. ``libzcash::SaplingExtendedFullViewingKey extfvk``", "1. ``char fYes``"
"3..6", "sapzkey*", "Sapling Incoming Viewing Key and Extended Spending Key", "1. ``libzcash::SaplingIncomingViewingKey ivk``", "1. ``libzcash::SaplingExtendedSpendingKey key``"
"3..6", "tx*", "All transactions that are related to the wallet.", "1. ``uint256 hash``", "1. ``CWalletTx wtx``"
"3..6", "**version**", "The ``CLIENT_VERSION`` from ``clientversion.h``.", "", "1. ``int nFileVersion``"
"3..6", "vkey*", "Sprout Viewing Keys.", "1. ``libzcash::SproutViewingKey vk``", "1. ``char fYes``"
"3..6", "watchs*", "Watch-only t-addresses.", "1. ``CScript script``", "1. ``char fYes``"
"3..6", "**witnesscachesize**", "Shielded Note Witness cache size.", "", "1. ``int64_t nWitnessCacheSize``"
"3..6", "zkey*", "Sprout Payment Address and Spending Key.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``libzcash::SproutSpendingKey key``"
"3..6", "zkeymeta*", "Sprout Payment Address and key metadata.", "1. ``libzcash::SproutPaymentAddress addr``", "1. ``CKeyMetadata keyMeta``"
"5..6", "**networkinfo**", "Network information.", "", "1. ``string strNetworkInfo``"
"5..6", "**orchard_note_commitment_tree**", "Orchard note commitment tree.", "", "1. ``OrchardWalletNoteCommitmentTreeWriter noteCommitmentTree``"
"5..6", "unifiedaccount*", "Unified Account metadata.", "1. ``ZcashdUnifiedAccountMetadata keyMeta``", "1. ``0x00``"
"5..6", "unifiedfvk*", "Unified Full Viewing Key. [#protocol-orchardencodings]_", "1. ``libzcash::UFVKId ufvkId``", "1. ``string ufvkString``"
"5..6", "unifiedaddrmeta*", "Unified Address metadata, useful for future re-derivation.", "1. ``ZcashdUnifiedAddressMetadata addrmeta``", "1. ``0x00``"
"5..6", "**mnemonicphrase**", "Mnemonic seed phrase.", "1. ``uint256 seedFp``", "1. ``MnemonicSeed seed``"
"5..6", "**cmnemonicphrase**", "Encrypted mnemonic seed phrase.", "1. ``uint256 seedFp``", "1. ``vector<unsigned char> vchCryptedSecret``"
"5..6", "**mnemonichdchain**", "HD chain metadata.", "", "1. ``CHDChain chain``"
"5..6", "recipientmapping*", "Maps transaction to UA.", "1. ``uint256 txid``
3. ``CSerializeRecipientAddress recipientAddr``", "1. ``std::string uaString``"
"6", "**bestblock_nomerkle**", "Replaces ``bestblock``. However, ``bestblock`` is kept empty so that previous versions automatically rescan.", "", "1. ``CBlockLocator locator``"


Functionality
Expand Down Expand Up @@ -133,16 +138,16 @@ Zcash forum or Community Discord.
Wallet Encryption
^^^^^^^^^^^^^^^^^

Encryption will not be discussed in this document in detail as it is expected for the algorithm to change in the future according to the Wallet format ZIP issue: [#ZIP400Issue]_.
Encryption will not be discussed in this document in detail as it is expected for the algorithm to change in the future according to the Wallet format ZIP issue: [#zips-issue350]_.


For a deeper understanding of the current encryption mechanism please refer to [#CrypterCode]_

References
==========

.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" <https://www.rfc-editor.org/info/bcp14>`_
.. [#BDB] `Oracle Berkeley Database <https://www.oracle.com/database/berkeley-db/db.html>`_
.. [#ZIP400Issue] `ZIP 400 issue <https://github.com/zcash/zips/issues/350>`_
.. [#zips-issue350] `zcash/zips issue #350: [ZIP 400] Format of Zcash wallet.dat files <https://github.com/zcash/zips/issues/350>`_
.. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets <zip-0032.rst>`_
.. [#CrypterCode] `Database key encryption implementation <https://github.com/zcash/zcash/blob/master/src/wallet/crypter.h>`_
.. [#protocol-orchardencodings] `Zcash Protocol Specification, Version 2024.5.1. Section 5.6.4: Unified and Orchard Encodings <https://zips.z.cash/protocol/protocol.pdf#orchardencodings>`_