Skip to content

API surface analysis

Jump to bottom
MeerKatDev edited this page Nov 30, 2023 · 1 revision

This wiki page is reserved for sharing all our knowledge about the most relevant parts of the Zcash librustzcash library. Usually some analysis work is needed in order to proceed with later implementations.

Keys derivation

In the following document we will analyze the object graph of the key derivation API. See also the protocol specification for each key type and possible derivations (Section 3.1):

image

Names in the following diagrams could change the original name of the current objects in code in a slightly way. This is done for clearness in the analysis. But they can be easily identified in both, our FFI and librustzcash APIs. Here are some shortcuts taken:

  • SK - Spending Key
  • OVK - Outgoing Viewing Key
  • IVK - Incoming Viewing Key
  • Names which are prefixed with Zcash correspond to the nomenclature chosen in our FFI code. See our code conventions page for more information on this.

We are currently making use of ZcashUnifiedSpendingKey and ZcashUnifiedFullViewingKey unified objects, which can be used to obtain derivations for all the key types (Transparent, Sapling, Orchard), thats where the *Unified* name comes from. That means that:

From a ZcashUnifiedSpendingKey, we could generate any SpendingKey , for any key type (Transparent, Sapling, Orchard).

graph LR;
style UnifiedSK fill:#66b2ff
UnifiedSK-->TransparentAccountPrivKey
UnifiedSK-->SaplingExtSK
UnifiedSK-->OrchardSK
Loading

Note: As we can see, Transparent key type follows the unshielded Bitcoin implementation, so derives in AccountPrivKey.

From a ZcashUnifiedFullViewingKey we could generate any FullViewingKey , for any key type (Transparent, Sapling, Orchard).

graph LR;
style UnifiedFVK fill:#66b2ff
UnifiedFVK-->TransparentAccountPubKey
UnifiedFVK-->SaplingDiversifiableFVK
UnifiedFVK-->OrchardFVK
Loading

Again, Transparent key type follows the unshielded Bitcoin implementation, so derives AccountPubKey.

Finally, from an ZcashUnifiedSpendingKey, we can derive a ZcashUnifiedFullViewingKey (unified spending to unified full, view keys).

If we merge all what we have seen till this point, we obtain the following derivation graph:

graph LR;
style UnifiedFVK fill:#66b2ff
style UnifiedSK fill:#66b2ff
UnifiedSK-->TransparentAccountPrivKey
UnifiedSK-->SaplingExtendedSK
UnifiedSK-->OrchardSK
UnifiedFVK-->TransparentAccountPubKey
UnifiedFVK-->SaplingDiversifiableFVK
UnifiedFVK-->OrchardFVK
UnifiedSK-->UnifiedFVK
Loading

As we can observe in the above graph, we presented the derivation path going through the unified objects to their first level child elements. Lets now put all available paths in a complete diagram:

graph LR;
style UnifiedFVK fill:#66b2ff
style UnifiedSK fill:#66b2ff
UnifiedSK-->TransparentAccountPrivKey
TransparentAccountPrivKey-->TransparentAccountPubKey
UnifiedSK-->SaplingExtendedSK
SaplingExtendedSK-->SaplingExtendedFVK
SaplingExtendedFVK-->SaplingDiversifiableFVK
SaplingDiversifiableFVK-->SaplingIVK
SaplingIVK-->PaymentAddress
SaplingDiversifiableFVK-->SaplingOVK
SaplingExtendedSK-->SaplingDiversifiableFVK
UnifiedSK-->OrchardSK
OrchardSK-->OrchardFVK
OrchardFVK-->OrchardIVK
OrchardIVK--->OrchardAddress
OrchardFVK-->OrchardOVK
UnifiedFVK-->TransparentAccountPubKey
UnifiedFVK-->SaplingDiversifiableFVK
UnifiedFVK-->OrchardFVK
UnifiedSK-->UnifiedFVK
Loading

As we can see, multiple the derivations paths are available to API users. One could go through the Unified objects and derive from there as saw in diagrams, or maybe start the derivation path on any spending key for each key type (Transparent, Sapling, Orchard).

Clone this wiki locally