diff --git a/zips/zip-0400.rst b/zips/zip-0400.rst index b692cd679..26389709e 100644 --- a/zips/zip-0400.rst +++ b/zips/zip-0400.rst @@ -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 ======== @@ -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 vchCryptedSecret``" - "ckey*", "Encrypted transparent pubkey and private key.", "1. ``vector vchPubKey``", "1. ``vector 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 vchCryptedSecret``" + "3..6", "ckey*", "Encrypted transparent pubkey and private key.", "1. ``vector vchPubKey``", "1. ``vector vchPrivKey``" + "3..6", "csapzkey*", "Encrypted Sapling pubkey and private key.", "1. ``libzcash::SaplingIncomingViewingKey ivk``", "1. ``libzcash::SaplingExtendedFullViewingKey extfvk`` 2. ``vector 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 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 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 @@ -133,7 +138,7 @@ 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]_ @@ -141,8 +146,8 @@ For a deeper understanding of the current encryption mechanism please refer to [ 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" `_ .. [#BDB] `Oracle Berkeley Database `_ -.. [#ZIP400Issue] `ZIP 400 issue `_ +.. [#zips-issue350] `zcash/zips issue #350: [ZIP 400] Format of Zcash wallet.dat files `_ .. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#CrypterCode] `Database key encryption implementation `_ +.. [#protocol-orchardencodings] `Zcash Protocol Specification, Version 2024.5.1. Section 5.6.4: Unified and Orchard Encodings `_