AZTEC Protocol 1.0.0
Technical specification of the AZTEC Protocol
Table of contents
Architecture
The AZTEC Cryptography Engine
AZTEC notes and ABI encoding
The Note Registry
ACE, the AZTEC Cryptography Engine
Validating AZTEC proofs - defining the proof's identifier
Enacting confidential transfer instructions - defining the ABI encoding of proofOutputs
ABI encoding for
bytes proofOutputsABI encoding for
bytes proofOutput = proofOutputs[i]Cataloguing valid proofs inside ACE
ACE owner
The key responsibilities of
ACESeparating proof validation and note registry interactions
Contract Interactions
Zero-knowledge dApp contract interaction, an example flow with bilateral swaps
The rationale behind multilateral confidential transactions
Validating an AZTEC proof
Note registry implementation
Creating a note registry
Note Registry Variables
Smart contract implementation
Upgradeability functionality
Processing a transfer instruction
A note on ERC20 token transfers
Minting AZTEC notes
Minting and tokens
Burning AZTEC notes
Interacting with ACE: zkAsset
Creating a confidential asset
Issuing a confidential transaction: confidentialTransfer
Issuing delegated confidential transactions: confidentialTransferFrom
Permissioning
Proof verification contracts
JoinSplit.sol
Swap.sol
Dividend.sol
PublicRange.sol
PrivateRange.sol
JoinSplitFluid.sol
Specification of Utility libraries
Appendix
A: Preventing collisions and front-running
B - Interest streaming via AZTEC notes
Glossary
Architecture
The AZTEC protocol enables efficient confidential transactions through the construction of AZTEC-compatible zero-knowledge proofs. Specifically, the protocol focuses on optimizing confidential settlement and other forms of value-transfer.
The protocol is architected to optimize for the following factors:
customizability - AZTEC assets must have confidential transaction semantics that can be modified to suit the ends of the user
interoperability - different AZTEC assets must conform to a standard interface that dApps can use to settle confidential transactions
efficiency - no redundant computation should be performed when verifying confidential transactions
qualified upgradability - as improvements are made to the underlying cryptographic protocols, and additional proof systems are added into AZTEC, existing confidential assets should be able to enjoy the benefits of these improvements. At the same time, users of AZTEC must be able to have confidence that they can opt out of these upgrades - that the verification algorithms used to validate existing zero-knowledge proofs are immutable. In addition, as upgrades are made to the logic of note registries, user must have the option to benefit from these upgrades whilst also being able to opt out.
The AZTEC Cryptography Engine
The focus of our protocol is this cryptography engine (ACE.sol). ACE is the ultimate arbiter of the correctness of an AZTEC zero-knowledge proof. AZTEC assets subscribe to ACE and call on it to validate proofs.
ACE converts zero-knowledge proof data into instructions - directions on the following:
AZTEC notes to be created
AZTEC notes to be destroyed
Public tokens that need to be transferred
Internally, ACE will create a unique representation of each proof instruction and store it.
ABI encoding and AZTEC data 'types'
The nature of zero-knowledge cryptography means that a significant volume of data is processed on-chain in the form of zero-knowlege proof inputs and zero-knowledge proof outputs.
Because using structs in external functions is still an experimental feature, the AZTEC protocol defines its own ABI encoding for struct-like data types. These objects are represented by the bytes type, where the contents of the bytes array contains data that is formatted according to the AZTEC protocol's ABI specification.
AZTEC note ABI
One key feature of ACE is the ability to support multiple note 'types'. Different note types enable the engine to support zero-knowledge proofs that use different techniques to represent encrypted value.
For example, the currently implemented basic AZTEC note is the most efficient way to represent encrypted value, however it's UTXO-like form may be unsuitable for some applications. On the other hand, once implemented, ElGamal 'treasury' notes could be used to emulate a more traditional account-balance model, where the balance is encrypted.
All notes use the same basic structure, but with different publicKey values. Every AZTEC zero-knowlege proof explicitly defines the type of note that it utilizes. Under no circumstances should it be possible to use a note of the wrong 'type' in a zero-knowledge proof.
The ABI encoding of a note is as follows:
Type 1: UTXO notes
This is the default note type and currently used by the protocol. The ABI formatting of this note's publicKey is as follows:
Type 2: El-Gamal treasury notes
Treasury notes would enable a single 'account' to have their balance represented by a single treasury note (instead of a multitude of AZTEC UTXO-type notes). They are slightly more gas-expensive to use than AZTEC notes and are only used in a small subset of AZTEC zero-kowledge proofs.
metaData
UPDATE WITH THE NOTE ACCESS PACKAGE FUNCTIONALITY
metaData is a general purpose data field for notes. It is not used by the logic of AZTEC zero-knowlege proof validators, but instead contains implementation and application specific information and is broadcast by events involving a note.
The metaData schema has a default component and then an additional customData component that can be set if the associated functionality is required. By default, it is populated with the ephemeral key which can be used to recover a note viewing key (see below). Additional custom data can be appended by calling note.setMetaData(), resulting in a schema as below:
Therefore, included in the metaData is: the note ephemeral key, addresses to be approved, a series of IES encrypted viewing keys for use in granting note access to third parties and data for application specific use cases. These are used to enable various functionality as defined below.
Use 1: Recovering viewing key using the ephemeral key
Every note viewing key should be distinct, however users should not have to manage a multitude of unique viewing keys. In addition, if user A wishes to send user B a note, they should be able to derive a viewing key that A can recover. This process should be non-interactive.
The solution is to use a shared secret protocol, between an 'ephemeral' public/private key pair and the public key of the note owner. An extension of this protocol can be used to derive 'stealth' addresses, if the recipient has a stealth wallet. Currently, our V1 APIs use the basic shared secret protocol for ease of use (traditional Ethereum wallets can own these kinds of AZTEC notes). At the smart contract level, the protocol is forward-compatible with stealth addresses.
Therefore, the first use of the metaData field is to store the data that a user requires to recover their note viewing key - the 'ephemeral' public key.
Use 2: Granting view key access
Note viewing key access can be directly granted to third parties by encoding an IES encrypted viewing key and the associated approved address into the metaData. This allows a method whereby viewing key access can be efficiently computed, without having to derive using the ephemeral key.
Granting of viewing keys is supported by the zkAsset.updateNoteMetaData(bytes32 noteHash, bytes calldata metaData) function. This allows the metaData of an already existing note to be updated, and so grant viewing key access to additional parties.
Use 3: Application specific data
Lastly, application specific data can be attached to the metaData of a note. This gives digital asset builders the option to attach custom data to an AZTEC note for an application specific utility.
The Note Registry
The AZTEC note registry contract is a subset of the AZTEC Cryptography Engine, but we describe it explicitly given its importance to the protocol.
The note registry contains the storage variables that define the set of valid AZTEC notes for a given address. It is expected this address maps to a smart contract, but this is not enforced.
The note registry enacts the instructions generated by valid AZTEC proofs - creating and destroying the required notes, as well as transferring any required tokens.
The note registry's owner is the only entity that can issue instructions to update the registry. NoteRegistry will only enact instructions that have been generated by a valid AZTEC proofs as it is of critical importance that notes are not created/destroyed unless a balancing relationship has been satisfied.
Because every confidential asset that uses an ACE note registry can have 100% confidence in the integrity of the state of every other ACE note registry, it makes it possible to express AZTEC notes from one registry as a percentage of notes in a second registry, which in turn is useful for dividend-paying confidential assets and confidential assets that utilize income streaming.
ACE, the AZTEC Cryptography Engine
The ACE.sol contract is responsible for validating the set of AZTEC zero-knowledge proofs and performing any transfer instructions involving AZTEC notes. ACE is the controller of all AZTEC note registries and acts as the custodian of both AZTEC notes and any tokens that have been converted into AZTEC notes.
While it is possible to define note registries that are external to ACE, the state of these contract's note registries cannot be guranteed and only a subset of proofs will be usable (i.e. if an asset uses an ACE note registry, transfer instructions from AZTEC proofs that involve multiple note registries are only enacted if every note registry is controlled by ACE).
The ACE has the following interface:
Validating AZTEC proofs - defining the proof's identifier
ACE supports multiple types of zero-knowlege proof and this family of proofs will grow over time. It is important to categorise these proofs in a systematic manner.
The ACE proof identification and versioning sytem has the following characteristics:
Extendibility. AZTEC's modular proof system enables composable confidential transaction semantics - adding more proofs enables these semantics to be more expressive. Additionally, it allows the AZTEC protocol to support fundamentally new types of zero-knowledge proving technology as Ethereum scales (e.g. bulletproofs, zk-snarks)
Opt-out functionality. If an asset controller only wants to listen to a subset of proofs (e.g. whether to listen to newly added proofs is on their terms. This is important for assets that have an internal review process for zero-knowledge proofs)
Qualified immutability. The validator code for a given proof id should never change. AZTEC must be able to de-activate a proof if it is later found to contain a bug, but any upgrades or improvement to a proof are expressed by instantiating a new validator contract, with a new proof id.
A proof is uniquely defined by an identifieruint24 _proof. ACE stores a mapping that maps each _proof to the address of a smart contract that validates the zero-knowledge proof in question.
Instead of having a 'universal' validation smart contract, it was chosen to make these contracts discrete for maximum flexibility. Validator contracts should not be upgradable, to gurantee that users of AZTEC proofs can have confidence that the proofs they are using are not subject to change. Upgrades and changes are implemented by adding new validator contracts and new proofs.
The uint24 _proof variable contains the concatenation of three uint8 variables (the rationale for this compression is to both reduce calldata size and to simplify the interface. Our javascript APIs automatically compose proofs with the correct _proof, minimizing the amount of variables that a builder on AZTEC has to keep track of.
The formatting as follows (from most significant byte to least significant byte)
A semantic-style version system was not used because proof epoch defines functionality as well as a form of version control. Proofs with the same uint8 id but with different uint8 epoch do not neccesarily perform the same function and proofs from a later epoch are not strictly 'better' than proofs from an earlier epoch.
For example, if the basic family of AZTEC proofs was adapted for confidential transactions that do not use a trusted setup, these proofs would be categorized by a new epoch. However these would not be a strict upgrade over the earlier epoch because the gas costs to verify these proofs would be almost an order of magnitude greater.
Similarly, when confidential voting mechanics are implemented into ACE, these will be defined by a separate epoch to emphasise their different functionality vs confidential transactions.
The uint8 category variable represents an enum with the four following values:
The ACE contract has separate logic to handle BALANCED, MINT and BURN proofs, as the latter two expressly violate the balancing relationship used to prevent double spending. The MINT and BURN proofs are designed for fully private AZTEC assets, ones with no ERC20 token equivalent, where AZTEC notes are the primary expression of value. Additional restrictions are placed on their use because of this.
For more information regarding minting and burning, see the mint and burn section.
The UTILITY proofs are designed for assets that require additional validation logic before a transaction can be performed. For example, an asset might require a trader to prove that they own less than 10% of the total supply of the asset before a trade is processed. This is supported by our dividend utility proof.
This specification contains descriptions for every currently supported proof id. Formal descriptions of the zero-knowledge proofs utilized by the verifiers can be found in the AZTEC protocol paper.
When combined together, uint8 epoch, uint8 category, uint8 id create 65025 unique proof identifies for each category. Given the complexity of zero-knowledge cryptographic protocols and the validation that must be performed before integration into ACE, it is infeasible for there to ever be demand for more than 65025 types of zero-knowledge proof inside ACE.
Enacting confidential transfer instructions - defining the ABI encoding of proofOutputs
There is substantial variation between the zero-knowledge proofs that AZTEC utilizes. Because of this, and the desire to create a simple interface to validate proofs, the interface for proof inputs is generic. An AZTEC proof accepts three parameters: bytes data, address sender, uint256[6] commonReferenceString. The commonReferenceString is provided by ACE. The data variable contains the zero-knowledge proof data in question, the address sender field is utilized to eliminate front-running. The ABI-encoding of bytes data is specific to a given validator smart contract.
The output of a zero-knowledge proof is a list of instructions to be performed. It is important that these proofOutput variables conform to a common standard so that existing confidential assets can benefit from the addition of future proofs.
An instruction must contain the following:
A list of the notes to be destroyed, the 'input notes'
A list of the notes to be created, the 'output notes'
If public tokens are being transferred, how many tokens are involved, who is the beneficiary and what is the direction of the transfer? (into ACE or out of ACE?)
In addition to this, ACE must support one zero-knowledge proof producing multiple instructions (e.g. the Swap proof provides transfer instructions for two distinct assets).
Proofs in the UTILITY category also conform to this specification, although in this context 'input' and 'output' notes are not created or destroyed.
To summarise, the output of any AZTEC validator smart contract is a bytes proofOutputs variable, that encodes a dynamic array of bytes proofOutput objects. The ABI encoding is as follows:
ABI encoding for bytes proofOutputs
bytes proofOutputsABI encoding for bytes proofOutput = proofOutputs[i]
bytes proofOutput = proofOutputs[i]Both bytes inputNotes and bytes outputNotes are dynamic arrays of AZTEC notes, encoded according to the AZTEC note ABI spec.
The int256 publicValue variable is a signed integer, because negative values are interpreted as tokens being transferred from address publicOwner and into ACE. Similarly, positive values are interpreted as tokens being transferred to address publicOwner.
It should be noted that int256 publicValue does not represent an absolute number of tokens. Each registry inside NoteRegistry has an associated uint256 scalingFactor, that defines how many ERC20 tokens are represented by 1 unit of AZTEC note 'value'. This mapping is neccessary because AZTEC note values are approximately 30-bit integers (CAVEAT HERE) and a scaling factor is required to map 256-bit ERC20 token volumes to 30-bit AZTEC values.
The uint256 challenge variable is used to ensure that each bytes proofOutput produces a unique hash. The challenge variable is required for every AZTEC zero-knowledge proof, and is itself a unique pseudorandom identifier for the proof (two satisfying zero-knowledge proofs cannot produce matching challenge variables without a hash collision). For a proof that produces multiple bytes proofOutput entries inside bytes proofOutputs, it is the responsibility of the verifier smart contract to ensure each challenge variable is unique (i.e. each bytes proofOutput contains a challenge variable that is a hash of the challenge variable for the previous entry).
Consequently, a hash of bytes proofOutput creates a unique identifier for a proof instruction because of the uniqueness of the challenge variable.
Cataloguing valid proofs inside ACE
Once a BALANCED, MINT or BURN proof has been validated, ACE records this fact so that future transactions can query the proof in question. This is done by creating a keccak256 hash of the following variables (encoded in an unpacked form)
This creates a unique key, that is mapped to true if the proof is valid (invalid proofs are not stored).
Contracts can query ACE with a bytes proofOutput, combined with a uint24 _proof and the address of the entity that issued the instruction. ACE can validate whether this instruction came from a valid proof.
This mechanism enables smart contracts to issue transfer instructions on behalf of both users and other smart contracts, enabling zero-knowledge confidential dApps.
ACE owner
It should be noted that upon deployment, the owner of the ACE will be a multi-signature wallet. The multi-sig wallet used is defined here: https://github.com/AztecProtocol/AZTEC/blob/develop/packages/protocol/contracts/MultiSig/MultiSigWalletWithTimeLock.sol
The key responsibilities of ACE
ACEThe ACE engine has two critical responsibilities:
Determine the correctness of valid AZTEC zero-knowledge proofs and permanently record the existence of validated
BALANCEDproofsUpdate the state of its note registries when presented with valid transfer instructions
When processing a transfer instruction, the following criteria must be met:
Did the transfer instruction originate from the note registry's owner?
Is the transfer instruction sourced from a mathematically legitimate AZTEC proof?
Because of these dual responsibilities, valid AZTEC proofs are not catalogued against specific note registries. The outputs of any valid proof can, theoretically, be issued to any note ,registry. After all, the existence of a valid proof indicates the resulting transfer instructions are balanced. This is the critical property that ACE must ensure, that all of its note registries are balanced and that there is no double spending.
Restricting note registry updates to the creator of a given note registry provides a natural separation of concerns - ACE determines whether a transfer instruction can happen and the note registry owner determines whether the instruction should happen.
Separating proof validation and note registry interactions
Because of these dual responsibilities, it might seem intuitive to roll proof validation and note registry updates into a single function. However, this would undermine one of the key strengths of the AZTEC protocol - that third party dApps can validate zero-knowledge proofs and send the resulting transfer instructions to AZTEC-compatible confidential assets. [Zero-knowledge dApp contract interaction, an example flow with bilateral swaps] (#zero-knowledge-dapp-contract-interaction-an-example-flow-with-Swaps) demonstrates this type of interaction and, consequently, the importance of separating proof validation from note registry updates.
Contract Interactions
Transaction #1
ACE.validateProof(uint24 _proof, address sender, bytes data)Validator.validate(bytes data, address sender, uint[6] commonReferenceString)(revert on failure, returnbytes proofOutputs)return
address publicOwner, uint256 transferValue, int256 publicValueto ACE, ifint256 publicValueis non-zero,ACE.transferPublicTokens(address _publicOwner, uint256 _transferValue, int256 _publicValue, bytes32 _proofHash)(revert on failure)a. (if
proofOutput.publicValue > 0)ERC20.transfer(proofOutput.publicOwner, uint256(proofOutput.publicValue))(revert on failure)b. (if
proofOutput.publicValue < 0)ERC20.transferFrom(proofOutput.publicOwner, this, uint256(-proofOutput.publicValue))(revert on failure)return
bytes proofOutputsto caller, log valid proof if category !=UTILITY, revert on failure
Transaction #1
ACE.updateNoteRegistry(uint24 _proof, bytes proofOutput, address sender)NoteRegistry.validateProofByHash(uint24 _proof, bytes proofOutput, address sender)(revert on failure)3a. (if
proofOutput.publicValue > 0)ERC20.transfer(proofOutput.publicOwner, uint256(proofOutput.publicValue))(revert on failure)3b. (if
proofOutput.publicValue < 0)ERC20.transferFrom(proofOutput.publicOwner, this, uint256(-proofOutput.publicValue))(revert on failure)NoteRegistry: (revert on failure)
ACE: (revert on failure)
Zero-knowledge dApp contract interaction, an example flow with bilateral swaps
The following image depicts the flow of a zero-knowledge dApp that utilizes the Swap proof to issue transfer instructions to two zkAsset confidential digital assets. This example aims to illustrate the kind of confidential cross-asset interactions that are possible with AZTEC. Later iterations of the protocol will include proofs that enable similar multilateral flows.
The dApp-to-zkAsset interactions are identical for both zkAsset A and zkAsset B. To simplify the description we only describe the interactions for one of these two assets.
(1-5) : Validating the proof
zk dAppreceives aSwapzero-knowledge proof fromcaller(with a defineduint24 _proofandbytes data.The
zk-dAppcontract queriesACEto validate the received proof, viaACE.validateProof(_proof, msg.sender, data). If_proofis not supported byzk-dAppthe transaction willrevert.On receipt of a valid proof,
ACEwill identify thevalidatorsmart contract associated with_proof(in this case,Swap.sol).ACEwill then callvalidator.validateProof(data, sender, commonReferenceString). If the_proofprovided does not map to a validvalidatorsmart contract, the transaction willrevert.If the proof is valid, the
validatorcontract will return abytes proofOutputsobject toACE. If the proof is invalid, the transaction willrevert.On receipt of a valid
bytes proofOutputs,ACEwill examine_proofto determine if the proof is of theBALANCEDcategory. If this is the case,ACEwill iterate over eachbytes proofOutputinbytes proofOutputs. For eachproofOutput, thebytes32 proofHashis computed. A unique proof identifier,bytes32 _proofIdentifier = keccak256(abi.encode(_proof, msg.sender, proofHash)), is then computed. This is used as a key to log the existence of a valid proof -validProofs[_proofIdentifier] = true.
Once this has been completed, ACE will return bytes proofOutputs to zk-dApp.
(6-8): Issuing a transfer instruction to zkAsset A
zkAsset AAt this stage, zk-dApp is in posession of transfer instructions that result from a valid Swap proof, in the form of a bytes proofOutputs object received from ACE.
For the Swap proof, there will be 2 entries inside proofOutputs, with each entry mapping to one of the two confidential assets - zkAsset A and zkAsset B.
The
zk-dAppcontract issues a transfer instruction tozkAsset AviazkAsset.confidentialTransferFrom(_proof, proofOutput).On receipt of
uint24 _proof, bytes proofOutput. ThezkAsset Acontract validates that_proofis on the contract's proof whitlelist. If this is not the case, the transaction willrevert.
zkAsset A computes bytes32 proofHash and query ACE as to the legitimacy of the received instructions, via ACE.validateProofByHash(_proof, proofHash, msg.sender).
ACEqueries itsvalidProofsmapping to determine if a proof that producedbytes proofOutputwas previously validated and return a boolean indicating whether this is the case.
If no matching proof was previously validated by ACE, zkAsset A will revert the transaction.
(9-16): Processing the transfer instruction
Having been provided with a valid proofOutput that satisfies a balancing relationship, zkAsset A will validate the following:
For every input
note, isapproved[note.noteHash][msg.sender] == true?
If this is not the case, the transaction will revert.
If all input notes have been
approved,zkAsset Awill instructACEto update its note registry according to the instructions inproofOutput, viaACE.updateNoteRegistry(_proof, proofOutput, msg.sender).On receipt of
bytes proofOutput,ACEwill also validate that theproofOutputinstruction came from a valid zero-knowledge proof (andrevertif this is not the case). Having been satisfied of the proof's correctness,ACEwill instruct the note registry owned bymsg.sender(zkAsset A) to process the transfer instruction.NoteRegistry Awill validate the following is correct:For every input
note, isnote.noteHashpresent inside theregistry?For every output
note, isnote.noteHashnot present inside theregistry?
If proofOutput.publicValue > 0, the registry will call erc20.transfer(proofOutput.publicOwner, uint256(proofOutput.publicValue)).
If proofOutput.publicValue < 0, the registry will call erc20.transferFrom(proofOutput.publicOwner, this, uint256(-proofOutput.publicValue)).
If the resulting transfer instruction fails, the transaction is
reverted, otherwise control is returned toNote Registry A
13-15. If the transaction is successful, control is returned to ACE, followed by zkAsset A and zk-dApp.
Following the successful completion of the confidential transfer (from both
zkAsset AandzkAsset B), control is returned tocaller. It is assumed thatzk-dAppwill emit relevant transfer events, according to the ERC-1724 confidential token standard.
The rationale behind multilateral confidential transactions
The above instruction demonstrates a practical confidential cross-asset settlement mechanism. Without ACE, a confidential digital asset could only process a transfer instruction after validating the instruction conforms to its own internal confidential transaction semantics, a process that would require validating a zero-knowledge proof.
This would result in 3 distinct zero-knowledge proofs being validated (one each by zk-dApp, zkAsset A, zkAsset B). Because zero-knowledge proof validation is the overwhelming contributor to the cost of confidential transactions, this creates a severe obstacle to practical cross-asset confidential interactions.
However, by subscribing to ACE as the arbiter of valid proofs, these three smart contracts can work in concert to process a multilateral confidential transfer having validated only a single zero-knowledge proof (this is because the Swap proof produces transfer instructions that lead to two balancing relationships. Whilst zkAsset A and zkAsset B do not know this (the proof in question could have been added to ACE after the creation of these contracts), ACE does, and can act as the ultimate arbiter of whether a transfer instruction is valid or not.
Whilst it may apear that this situation requires AZTEC-compatible assets to 'trust' that ACE will correctly validate proofs, it should be emphasized that ACE is a completely deterministic smart-contract whose code is fully available to be examined. No real-world trust (e.g. oracles or staking mechanisms) is required. The source of the guarantees around the correctness of AZTEC's confidential transactions come from its zero-knowledge proofs, all of which have the properties of completeness, soundness and honest-verifier zero-knowledge.
Validating an AZTEC proof
AZTEC zero-knowledge proofs can be validated via ACE.validateProof(uint24 _proof, address sender, bytes calldata data) external returns (bytes memory proofOutputs).
The bytes data uses a custom ABI encoding that is unique to each proof that AZTEC supports. It is intended that, if a contract requires data from a proof, that data is extracted from bytes proofOutputs and not the input data.
If the uint8 category inside _proof is of type BALANCED, ACE will record the validity of the proof as a state variable inside mapping(bytes32 => bool) validatedProofs.
If the proof is not valid, an error will be thrown. If the proof is valid, a bytes proofOutputs variable will be returned, describing the instructions to be performed to enact the proof. For BALANCED proofs, each individual bytes proofOutput variable inside bytes proofOutputs will satisfy a balancing relationship.
Note registry implementation
Creating a note registry
An instance of a note registry is created inside ACE, via createNoteRegistry(address _linkedTokenAddress, uint256 _scalingFactor, bool _canAdjustSupply, bool _canConvert).
The _canAdjustSupply flag defines whether the note registry owner an directly modify the note registry state by minting and burning AZTEC notes. The _canConvert flags defines whether ERC20 tokens from _linkedTokenAddress can be converted into AZTEC notes. If _canConvert is false, then _linkedTokenAddress = address(0) and the asset is a fully private asset.
For a given note registry, only the owner can call ACE.updateNoteRegistry, ACE.mint or ACE.burn. Traditionally this is imagined to be a zkAsset smart contract. This allows the zkAsset contract to have absolute control over what types of proof can be used to update the note registry, as well as the conditions under which updates can occur (if extra validation logic is required, for example).
Note Registry Variables
bytes32 confidentialTotalMinted
bytes32 confidentialTotalMintedThis variable is the keccak256 hash of an AZTEC UTXO note that defines the total amount of value that a note registry has directly minted.
When a note registry is created, this note is set to be an AZTEC UTXO note that has a value of 0 and a viewing key of 1.
bytes32 confidentialTotalBurned
bytes32 confidentialTotalBurnedThis variable is the kecckak256 hash of an AZTEC UTXO note that defines the total amount of value that a note registry has directly burned.
When a note registry is created, this note is set to be an AZTEC UTXO note that has a value of 0 and a viewing key of 1.
uint256 scalingFactor
uint256 scalingFactorIf this registry permits conversions from AZTEC notes into tokens, scalingFactor defines the number of tokens that an AZTEC note value of 1 maps to.
This is required because the maximum value of an AZTEC note is approximately 2^26 (it is dependent on ACE's common reference string) - there is an associated loss of precision when converting a 256 bit variable into a 26 bit variable.
uint256 totalSupply
uint256 totalSupplyThis variable represents the total amount of tokens that currently reside within ACE as a result of tokens being converted into AZTEC notes, for a given note registry.
ERC20 linkedToken
ERC20 linkedTokenThis is the address of the registry's linked ERC20 token. Only one token can be linked to an address.
canAdjustSupply
canAdjustSupplyFlag determining whether the note registry has minting and burning priviledges.
canConvert
canConvertFlag determining whether the note registry has public to private, and vice versa, conversion priviledges
totalSupplemented
totalSupplementedTotal number of tokens supplemented to the ACE, as a result of tokens being transferred when conversion of minted notes to public value was attempted and there were not sufficient tokens held by ACE.
Implementation and upgradeability functionality
In order to guarantee the correct implementation of any operation affecting the state of note registries within the AZTEC ecosystem, all of the data and behaviour relating to note registries is encapsulated in the AZTEC Cryptography Engine.
However, it is likely that the behaviour of note registries will need to be modified in the future in order to accomodate potential functionality improvements such as added support for new types of linked public tokens, mixers etc. To allow this to happen without requiring a hard fork, note registries have been made upgradeable and broken out from the immutable ACE contract into their own upgradeable modules.
Various considerations were taken into account when designing this architecture.
Firstly, the data stored in these registries is obviously very sensitive, and valuable. Upgrades should be rare, backwards compatible, and no upgrade should result in funds becoming inaccessible, partly or wholly un-spendable, or otherwise compromised.
In addition, despite being encapsulated inside of ACE, note registries are owned by ZkAssets. These asset owners should have complete agency over their implementation and so the only entities which should be allowed to upgrade the note registry associated to a particular ZkAsset is its owner.
The implementation of all behaviour which affects the state of all note registries should also be controlled and vetted by the owner of ACE, and ZkAsset owners should not be able to upgrade to arbitrary implementations. This is to protect the integrity of the registries.
The upgrade pattern, or any individual upgrade itself, should also not compromise the hard link between a ZkAsset and its note registry (i.e. no non-authorised contract or account should be able to affect the state of the note registry through an upgrade or because note registries are upgradeable).
Of the various upgradeability patterns available, the unstructured storage proxy pattern developed by Open Zeppelin is used. The foundation of this pattern is to seperate the storage of the note registry, which defines the set of valid notes, from the logic, behaviour and methods of the note registry. There are four base contracts involved in this implementation: Behaviour.sol, AdminUpgradeabilityProxy.sol , Factory.sol and NoteRegistryManager.sol .
Behaviour contract - Behaviour.sol
The behaviour contract defines the methods and contains the logic of the note registry. It is this contract that is the mutable, upgradeable contract and the method whereby the implementation of note registry methods is upgraded. All behaviour contracts must abide by a set minimum API in order to maintain compatibility with ACE:
Storage/proxy contract - AdminUpgradeabilityProxy.sol
The storage contract is referred to as the Proxy and it has four main responsibilities:
Store the storage variables which define the set of unspent notes
Implement the delegation of calls to behaviour contracts via
delegatecall(). In this way, note registry functionality on the behaviour contract is executed in the context of the calling proxy storage contract - allowing behaviour methods access to notesPoint the proxy to an upgraded behaviour implementation. This functionality is protected by an authorisation mechanism
Faciliate a possible change of admin
The interface is defined as:
In order to facilitate the process of upgrading the behaviour contract to a new instance, there are two further classes of contracts: factory contracts and the note registry manager.
Factory contracts - Factory.sol
Factory contracts are used to deploy and link an upgraded behaviour instance to ACE. They are owned by the ACE and there is a factory contract for each type of behaviour instance that can be deployed: adjustable and mixed.
It is important to detail the versioning system used to keep track of the various factory versions - each factory is associated with a unique ID. The purpose of this ID is to identify the following properties of the factory and the resulting deployed behaviour contract:
Epoch - the version number
Cryptosystem - the crypto system that the note registry is interfacing with
Asset type - the type of asset that the note registry belongs to i.e. is it convertable, adjustable, various combinations of these
Each of these variables is represented by a uint8 , which are then packed together into a uint24 to give the unique factory ID. Epoch number can only ever increase and all newly deployed behaviours must be backwards compatible.
Note registry manager - NoteRegistryManager.sol
The note registry manager is inherited by ACE. Its responsibilities include:
Define the methods uses to deploy and upgrade registries
Define the methods uses to enact state changes sent by the owner of a registry
Manage the list of factories that are available
An overview of this architecture is provided below:
How an upgrade works
The above system of smart contracts can be used to deploy both non-upgradeable and upgradable zkAssets . Only ownable ZkAssets are able to be upgraded through this upgrade pattern and in the case where there is no owner, the latest note registry behaviour is deployed.
Deploying a new non-upgradeable ZkAsset
A user deploys a ZkAsset contract, feeding in constructor arguments
aceAddress, erc20Address, ERC20_SCALING_FACTOR, canAdjustSupply.The ZkAsset calls ACE, telling it to instantiate a note registry
ACE, through the NoteRegistryManager, finds the latest Factory, and tells it to deploy a new Proxy contract, and then to deploy a new Behaviour contract, passing the address of the Proxy contract in its constructor.
Once deployed, the Factory transfers ownership of the Behaviour to ACE
The Factory returns the address of the new Behaviour contract, and ACE adds to a mapping from address of ZkAsset to NoteRegistry.
Deploying a new NoteRegistry version
A new Factory.sol is deployed, which has the ability to deploy new NoteRegistryBehaviour contracts, and can manage transferring ownership from itself to an address it received
The Owner of ACE sends a Tx associating a unique identifier with the address of the new Factory
Upgrading a ZkAsset's NoteRegistry
The Owner of a ZkAsset makes a call to upgrade its NoteRegistry, giving a specific unique id of a particular factory.
The ZkAsset calls ACE, telling it to upgrade its NoteRegistry, and passing it a specific version to use.
ACE finds the NoteRegistry, fetches its associated Proxy address, and finds the relevant factory to call
ACE tells the factory to deploy a new Behaviour, passing in the Proxy address it received.
The factory deploys the new Behaviour contract
Once deployed, the factory transfers ownership to ACE
The address of the deployed Behaviour is sent back to ACE,
ACE tells the old Factory to abdicate control over the Proxy contract in favour of the new Factory
Controlled release
In order to build liquidity in particular assets when AZTEC launches, a slow release period feature has been added in which some assets will be available whilst others will be availale after this fixed slow release period ends. The relevant note registry epochs are 2 and 3, implemented in behaviour contracts Behaviour201911.sol and behaviour201912.sol
Assets that have a note registry version of epoch 2 (Behaviour201911) will be unavailable during the slow release period:
The slow release period length is defined by the variable slowReleaseEnd , after which the asset will automatically become available. The restricting of availability up to this point is defined through the use of the function modifier onlyIfAvailable() which modifiers the behaviour of the key updateNoteRegistry() function.
It is also possible for the ZkAsset owner to make the asset available earlier than the end of the burn-in period, by calling the makeAvailable() method.
Assets that have a note registry version of epoch 3 (Behaviour201912) will be available during the slow release period. They have no concept of the onlyIfAvailable() modifier:
Current notre registry versions
There are currently three versions/epochs of the note registry behaviour contract. Each inherits from the previous contract epoch and adds additional functionality. This is summarised below:
Processing a transfer instruction
Once a proof instruction has been received (either through ACE or via a third party that validated a proof through ACE, for example a confidential decentralized exchange dApp), it can be processed by calling ACE.updateNoteRegistry(uint24 _proof, bytes proofOutput, address sender).
If
msg.senderhas not registered a note registry insideACE, the transaction will throwIf the the proof instruction was not sourced from a proof that
ACEvalidated, the transaction will throwIf
validatedProofs[keccak256(abi.encode(_proof, sender, keccak256(proofOutput)))] == false, the transaction will throw
If the above criteria are satisfied, the instruction is passed to NoteRegistry, where the following checks are validated against:
If any note in
proofOutput.inputNotesdoes not hash to a key that does not exist insidenoteRegistry, the transaction will throwIf any note in
proofOutput.outputNoteshashes to a key that already exists insidenoteRegistry, the transaction will throwIf
proofOutput.publicValue != 0and the asset is notmixed, the transaction will throw
Once these conditions have been satisfied, every note in proofOutput.inputNotes is destroyed, and every note in proofOutput.outputNotes is created.
Additionally, if proofOutput.publicValue < 0, linkedToken.transferFrom(proofOutput.publicOwner, this, uint256(-proofOutput.publicValue)) is called. If this call fails, the transaction will throw. If proofOutput.publicValue > 0, linkedToken.transfer(proofOutput.publicOwner, uint256(proofOutput.publicValue)) will be called. If this call fails, the transaction will throw.
A note on ERC20 token transfers
For mixed assets, if tokens are withdrawn from AZTEC then, from the balancing relationships checked by AZTEC's zero-knowledge proofs, ACE will always have a sufficient balance, as the only way to create AZTEC notes is by depositing tokens in the first place.
For mintable assets that are also mixed, there are additional steps that a digital asset builder must implement. If an AZTEC note is directly minted, and then converted into tokens, ACE will not have a sufficient token balance to initiate the transfer.
Minting AZTEC notes
Under certain circumstances, a digital asset owner may wish to directly mint AZTEC notes. One example is a confidential digital loan, where the loan originators create the initial loan register directly in the form of AZTEC notes.
At the creation of a note registry, the registry owner can choose whether their registry is 'mintable' by setting bool _canAdjustSupply to true in ACE.createNoteRegistry(address _linkedTokenAddress, uint256 _scalingFactor, bool _canAdjustSupply, bool _canConvert).
A 'mintable' note registry has access to the ACE.mint(uint24 __proof, bytes _proofData, address _proofSender) function. This function will validate the proof defined by __proof, _data, _proofSender (and assert that this is a MINTABLE proof) and then immediately enact the produced bytes proofOutput at the note registry controlled by msg.sender.
A MINTABLE proof follows a defined standard. The note registry contains a bytes32 totalMinted variable that is the hash of an AZTEC UTXO note that contains the total value of AZTEC notes that been minted by the registry owner.
A MINTABLE proof will produce a proofOutputs object with two entries.
The first entry contains the old
confidentialTotalMintednote and the newconfidentialTotalMintedvalueThe second entry contains a list of notes that are to be minted
If the confidentialTotalMinted value does not match the old confidentialTotalMinted value in proofOutputs, the transaction will revert.
If all checks pass, the relevant AZTEC notes will be added to the note registry.
Minting and tokens
Care should be taken if AZTEC notes are directly minted into an asset that can be converted into ERC20 tokens. It is possible that a conversion is attempted on a note and the token balance of the note registry in question is insufficient. Under these circumstances the transaction will revert. It is the responsibility of the note registry owner to provide ACE with sufficient tokens to enable such a transfer, as it falls far outside the remit of the Cryptography Engine to request minting priviledges for any given ERC20 token.
This can be performed via ACE.supplementTokens(uint256 _value), which will cause ACE to call transferFrom on the relevant ERC20 token, using msg.sender both as the transferee and the note registry owner. It is assumed that the private digital asset in question has ERC20 minting priviledges, if the note registry is also mintable.
Burning AZTEC notes
Burning is enacted in an identical fashion to note minting. The total amount of burned AZTEC notes is tracked by a bytes32 confidentialTotalBurned variable.
Burn proofs follow a similar pattern - updating the totalBurned variable and destroying the specified AZTEC notes.
It should be stressed that only a note registry owner, who has set the relevant permissions on their note registry, can call ACE.mint and ACE.burn.
If ERC20 tokens have been converted into AZTEC notes, which are subsequently burned, the resulting tokens will be permanently locked inside ACE and will be unretrievable. Care should be taken by a note registry owner that this behaviour is desired when they burn notes.
Interacting with ACE: zkAsset
The zkAsset.sol contract is an implementation of a confidential token, that follows the EIP-1724 standard. It is designed as a template that confidential digital asset builders can follow, to create an AZTEC-compatible asset. All zkAssets must follow the following minimum interface:
Creating a confidential asset
A zkAsset contract must instantiate a note registry inside ACE via ACE.createNoteRegistry. If the asset is a mixed, the contract address of the linked ERC20 token must be supplied.
Issuing a confidential transaction: confidentialTransfer()
The primary method of unilateral value transfer occurs via zkAsset.confidentialTransfer(bytes _proofData, bytes _signatures). In this method, the joinSplit AZTEC proof is used to enact a value transfer. The beneficiaries of the transaction are defined entirely by the contents of bytes _proofData.
Both ACE.validateProof(data) and9 ACE.updateNoteRegistry(proofOutput) must be called, with proofOutput being extracted from ACE.validateProof's return data.
Note that in order to call confidentialTransfer() the following API is used:
This is necessary because of the way in which Truffle interacts with overloaded functions which are defined to have a different number of parameters.
Issuing delegated confidential transactions: confidentialTransferFrom()
The confidentialTransferFrom(uint24 __proof, bytes _proofOutput) method is used to perform a delegated transfer. As opposed to confidentialTransfer, confidentialTransferFrom can use any proof supported by ACE (assuming the zkAsset contract accepts this type of proof).
Permissioning
It is the responsibility of the zkAsset to perform the required permissioning checks when value transfer occurs. The permissioning mechanism used in a confidentialTransfer() call is different to that used for a confidentialTransferFrom() call.
The confidentialTransfer method takes a set of EIP712 ECDSA signatures over each inputNote that is involved in the transfer. These are then validated in the method confidentialTransferInternal().
However, this method is not suitable for a delegated transfer calling confidentialTransferFrom(). In this case, the note 'owners' may be smart contracts and so unable to create digitial signatures. Therefore, for confidentialTransferFrom() to be used, a permission granting function must be called on every input note that is consumed.
There are two flavours of this permissioning granting function: confidentialApprove() and batchConfidentialApprove() . The first allows permission to be granted for an individual note, the second allows permission to be granted to multiple notes in a single function call.
confidentialApprove()
The confidentialApprove(bytes32 _noteHash, address _spender, bool _spenderApproval, bytes memory _signature) method gives the _spender address permission to use an AZTEC note, whose hash is defined by _noteHash, to be used in a zero-knowledge proof.
The _spenderApproval boolean defines whether permission is being given or revoked.
The _signature variable defines an ECDSA signature over an EIP712 message. This signature is signed by the address owner of the AZTEC note being approved.
If _signature = bytes(0x00), then msg.sender is expected to be the address owner of the AZTEC note being approved.
This interface is designed to facilitate stealth addresses. For a stealth address, it is unlikely that the address will have any Ethereum funds to pay for gas costs, and a meta-transaction style transaction is required. In this situation, msg.sender will not map to the owner of the note and so an ECDSA signatue is used.
For other uses, such as a smart contract or a non-stealth address, a direct transaction sent by the correct msg.sender is possible by sending a null signature.
batchConfidentialApprove()
This allows spending permission to be granted to multiple notes in a single atomic function call. This is useful for delegating note control over n notes in a single transaction, rather than having to make n confidentialApprove() calls.
It has the following interface
_noteHashes are the hashes of the notes for which permission is being granted or revoked.
_spender is the address being granted spending control of the notes.
_spenderApprovals defines an array of booleans, which control whether spending permission is being revoked or granted.
_batchSignature is an EIP712 signature created over all the notes, authoring the delegation.
Granting note view key access
AZTEC notes contain a metaData field, with a specification as outlined in the note ABI discussion. One of the principal uses of this data field, is to store encrypted viewing keys - to allow note view access to be granted to third parties. The metaData of a note is not stored in storage, rather it is emitted as an event along with the successful creation of a note:
It may be desirable to grant note view key access to parties, beyond those for which an encrypted viewing key was initially provided when the note was created. To facilitate this, the ZkAssetBase.sol has an updateNoteMetaData() method:
The purpose of this method is to ultimately emit a new event UpdateNoteMetaData(noteOwner, noteHash, metaDatawith updated metaData.The metaData is the updated metaData which contains the IES encrypted viewing keys for all parties that are to be granted note view access.
Note that Ethereum addresses are extracted from the metaData field of a CreateNote() or UpdateNoteMetaData() event, then it will not be checksummed and instead will be lowercase. This is because metaData is defined to be a bytes data type, rather than address , given that it can represent arbitrary data.
Permissioning
The permissioning of this function is of critical importance - as being able to call this function allows note view access to be given to an arbitrary address. To this end, there is a require() statement which enforces that one of the two valid groups of users are calling this function. It will revert if not.
The first category of permissioned caller is the noteOwner . A note owner should have complete agency over to whom they grant view key access to their note.
The second category of permissioned callers are those Ethereum addresses that are being granted view key access in the metaData. These addresses are explicitly stated in the approvedAddresses section of metaData.
To enact this check, an addressID is first calculated - the keccak256 hash of msg.sender and the hash of the note in question. We then make use of the noteAccess mapping declared in the ZkAsset:
This is a mapping of addressIDs to a uint256 , where the uint256 is the block.timestamp of the block in which the particular address was originally granted approval via approveAddresses().
We then compare noteAccess[addressID] to the value stored in metaDataTimeLog[noteHash]. metaDataTimeLog is a second mapping of the form:
It is a mapping of noteHash to the block.timestamp when the method setMetaDataTimeLog() was last called. This mapping is used to keep track of when the metaData for a particular note was last updated.
By checking that noteAccess[addressID] >= metaDataTimeLog[noteHash] we satisfy two conditions. Firstly, that msg.sender is an address which has been previously approved view access in the metaData of a note. Secondly, that msg.sender still has view access to a note and has not since been revoked (by metaData being updated and not including this Ethereum address as an approved address).
setProofs()
It should be noted that ZkAssets which are ownable and inherit from the ZkAssetOwnable.sol contract have a concept of `supporting proofs'. The owner is able to choose which proofs the ZkAsset supports and can interact with.
This is achieved through the setProofs() function, restricted to onlyOwner:
In order for a ZkAsset to be able to listen to and interact with a particular proof, it must be first registered with this function.
By default, all ZkAssetOwnable contracts have the basic unilateral transfer joinSplit proof enabled in their constructor.
Types of ZkAssets
There are various types of zkAssets, which are differentiated based on the flags canAdjustSupply ,canConvert and whether or not the asset is ownable.
canAdjustSupply determines whether the asset is able to mint or burn whilst canConvert determines whether public ERC20 tokens can be converted into AZTEC notes and vice versa. These flags are not exposed to the user instantiating the asset and are instead hardcoded into the constructor of the asset or derived from existing properties. canAdjustSupply is hardcoded into the constructor of the relevant asset, whilst canConvert is derived from whether a linkedTokenAddress was set in the asset's constructor.
These flags give rise to the contracts whose properties are summarised in the below table:
where Y is yes, N no and P is possible (it is at the discretion of the instantiator). ZkAssetMintable is only able to mint, ZkAssetBurnable is only able to burn, whilst ZkAssetAdjustable is able to both mint and burn.
Proof verification contracts
JoinSplit.sol
The JoinSplit contract validates the AZTEC join-split proof. It takes a series of inputNotes , to be removed from a note registry, and a series of outputNotes to be added to the note registry. In addition, an integer publicValue can be supplied - this specifies the number of ERC20 tokens to be converted into AZTEC note form or from AZTEC note form.
The ABI of bytes data is the following:
uint[6][] notes contains the zero-knowledge proof data required for the set of input and output UTXO notes used inside JoinSplit. The ABI encoding is as follows:
The amount of public 'value' being used in the join-split proof, publicValue, is defined as the kBar value of the last entry in the uint[6][] notes array. This value is traditionally empty (the last note does not have a kBar parameter) and the space is re-used to house publicValue.
Swap.sol
The Swap contract validates a zero-knowledge proof that defines an exchange of notes between two counter-parties, an order maker and an order taker.
The proof involves 4 AZTEC UTXO notes, and proves the following:
note[0].value = note[2].valuenote[1].value = note[3].value
In this context, the notes are interpreted as the following:
note[0]: order maker bid notenote[1]: order maker ask notenote[2]: order taker ask notenote[3]: order taker bid note
This proof does not perform any authorization logic - it is the responsibility of the asset smart contracts involved in a trade to perform required permissioning checks.
The ABI of bytes data is identical to the ABI-encoding of the JoinSplit.sol verification smart contract. The Swap contract will throw if n != 4 or m != 2.
Once a proof has been successfully validated, bytes proofOutputs will contain two entries, with the following note assignments:
proofOutputs[0].inputNotes = [note[0]]proofOutputs[0].outputNotes = [note[2]]proofOutputs[1].inputNotes = [note[3]]proofOutputs[1].outputNotes = [note[1]]
i.e. Both the order maker and order taker are destroying their bid notes in exchange for creating their ask notes.
Each entry inside proofOutputs defines a balancing relationship. If proofOutputs[0] and proofOutputs[1] are sent to different ZKAsset smart contracts, this proof can be used to define a bilateral swap of AZTEC notes, between two counter-parties and across two asset classes.
The ABI of bytes data is the following:
Dividend.sol
The Dividend proof validates that an AZTEC UTXO note is equal to a public percentage of a second AZTEC UTXO note. This proof is belongs to the UTILITY category, as in isolation it does not describe a balancing relationship.
The Dividend proof involves three AZTEC notes and two scalars za, zb. The scalars za, zb define a ratio and the proof proves the following:
note[1].value * za = note[2].value * zb + note[3].value
In this context, note[3] is a residual note. The residual note is required in order to accommodate rounding errors. Consider the scenario of a user computing an interest rate payment for values za, zb that are fixed by a smart contract.
In this context, zb > za and note[1].value is the source note. The target note is note[2]. The owner of note[1] wishes to prove that note[2].value = note[1].value * (za / zb), or as close as they can manage given the confines of integer arithmetic.
As the value of note[1] is unknown to all but the note owner, they have a free choice in choosing values for note[2] and note[3]. However in order to maximize the value of note[2], it is in the note owner's interest to minimize note[3].value.
It is worth highlighting the fact that the Dividend proof, like all AZTEC proofs, it is impossible to present a satisfying proof if any notes have negative value.
When utilizing the Dividend proof inside a smart contract, care should be taken to determine whether the proof is being utilized to validate a debit computation or a credit computation, as it important to ensure that the sender of the proof is incentivized to minimize the value of note[3] (not to maximize it).
In a debit computation, the note owner is proving that an AZTEC note correctly represents a transfer of value from the note owner. For example, a loan repayment. In this context, it is in the note owner's interest to minimize the value of the target note. It is therefore important to set note[1] as the target note and note[2] as the source note. Under this formulism, increasing note[3].value will also increase the value of the target note. The note owner, therefore, is incentivized to ensure that note[3].value is as small as possible. In this situation, malicious behaviour is prevented because of the AZTEC range proof: note[3].value cannot be negative.
In a credit computation, the incentives are reversed and it is neccessary to set note[1] as the source note, and note[2] as the target note.
Similarly to Swap, this proof performs no permissioning checks. It is the responsibliity of the smart contract invoking Dividend to imbue meaning into the notes being used in the proof, and to ensure that the correct permissioning flows have been observed.
The ABI of bytes data is the following:
PublicRange.sol
The PublicRange proof validates in zero-knowledge that the value of one AZTEC note is greater than or equal to, or less than or equal to a public integer. It belongs to the UTILITY proof category.
The proof involves three quantities:
originalNote= note who's inequality relation we seek to provepublicComparison= public integer, which theoriginalNoteis being compared againstutilityNote= helper note, used to construct an appropriate proof relation
These quantities are then used to construct a proof relation: originalNoteValue = publicComparison + utilityNoteValue.
In addition, a boolean isGreaterOrEqual is supplied to the proof. This is used to control whether the proof is for a greater than or equal to, or less than or equal to scenario.
If isGreaterOrEqual is true, then it is a greater than or equal proof and originalNoteValue >= publicComparison. If false, it is a less than or equal to proof that originalNoteValue <= publicComparison.
The ABI of bytes data is the following:
PrivateRange.sol
The PrivateRange proof validates in zero-knowledge that the value of one AZTEC note is greater than or less than the value of a second AZTEC note. It belongs to the UTILITY proof category as no true balancing relationship is satisfied.
The proof involves three AZTEC notes:
originalNote= note who's inequality relation we seek to provecomparisonNote= note being compared againstutilityNote= helper note, used to construct an appropriate proof relation
These notes are used to construct the following proof relation: originalNote.value = comparisonNote.value + utilityNote.value
If this is satisfied, it means that originalNote.value > comparisonNote.value. Note, that the range proof means it is not possible to construct notes with a value less than zero. In order to construct a less than proof (i.e. originalNote.value < comparisonNote.value), the user must change the input order to show that comparisonNote.value > originalNote.value
The proofOutputs object returned contains one proofOutput object. The inputNotes corresponds to originalNote and comparisonNote, with the outputNotes corresponding to utilityNote. The output note has no physical meaning and is used to construct a mathematically appropriate proof relation.
The ABI of bytes data is the following:
JoinSplitFluid.sol
The JoinSplitFluid contract enables proofs to be validated for the direct minting or burning of AZTEC notes, ifRegistry.adjustSupply = true.
Mint and burn proofs are both special cases of the joinSplit proof - they are the joinSplit proof but they have a restricted, specified set of inputs. This validator contract is used to validate both mint and burn proofs.
In the mint proof, notes are being directly created and added to a note registry, whilst in the burn proof notes are being removed from a note registry. In terms of notes, the joinSplitFluid validator takes three inputs:
currentCounterNote- note that describes the existing total minted/burned value in this note registrynewCounterNote- note that describes the new total minted/burned value in this note registry once the proof has been validated and the results enactedminted/burned notes- the notes that are to be minted and created in the note registry, or burned and removed from the note registry
The minted/burned notes are the notes being added or removed from the note registry. The purpose of the counter notes is to keep track of the total value that has been minted or burned in this note registry - this informatiom may be for accounting purposes, or an audit.
It is important to note that for a given note registry, only the registry owner can call ACE.mint or ACE.burn . Only the registry owner must know the value of the total notes - hashes of these notes are represented by the registry variables confidentialTotalMinted and confidentialTotalBurned.
The ABI-encoding of bytes data is identical to that of an AZTEC JoinSplit transaction. There is the added restriction that m = 1 and n >= 2.
When encoding bytes proofOutputs, the following mapping between input notes and notes in proofOutputs is used:
proofOutputs.length = 2proofOutputs[0].inputNotes = [currentCounterNote]proofOutputs[0].outputNotes = [newCounterNote]proofOutputs[0].publicOwner = address(0)proofOutputs[0].publicValue = 0proofOutputs[1].inputNotes = []proofOutputs[1].outputNotes = [minted/burned notes]
The ABI of bytes data is the following:
Specification of Utility libraries
There are various utility contracts/libraries that are used to make the protocol smart contract system more modulular and self documenting. These include:
LibEIP712.sol- helpers for validating EIP712 signaturesMetaDataUtils.sol- helpers for extracting Ethereum addresses from a note's metaDataModifiers.sol- base contract intended to define commonly used function modifiers. To be inherited by other contracts. Currently provides thecheckZeroAddress()modifierNoteUtils.sol- helpers that extract user-readable information fromproofOutputs. Detailed below.ProofUtils.sol- decompose auint24 proofIdinto it's three constituentuint8components:epoch,categoryandidSafeMath8.sol- SafeMath operations foruint8variablesVersioningUtils.sol- helper to extract the three constiutentuint8variables compressed into auint24
NoteUtils.sol
A particularly useful utility library is NoteUtils.sol . This was built to abstract away the complexities of an AZTEC proof's ABI-encoding from a digital asset builder. It provides helper methods that enable data to be extracted from bytes memory proofOutputs:
NoteUtils.getLength(bytes memory proofOutputsOrNotes) internal pure returns (uint256 length)
NoteUtils.getLength(bytes memory proofOutputsOrNotes) internal pure returns (uint256 length)When provided with an AZTEC ABI-encoded array (any one of bytes memory proofOutputs, bytes memory inputNotes, bytes memory outputNotes), this method will return the number of entries.
NoteUtils.get(bytes memory proofOutputsOrNotes, uint256 i) internal pure returns (bytes memory out)
NoteUtils.get(bytes memory proofOutputsOrNotes, uint256 i) internal pure returns (bytes memory out)This method will return the i'th entry of an AZTEC ABI-encoded array. If i is an invalid index an error will be thrown.
NoteUtils.extractProofOutput(bytes memory proofOutput) internal pure returns (bytes memory inputNotes, bytes memory outputNotes, address publicOwner, int256 publicValue)
NoteUtils.extractProofOutput(bytes memory proofOutput) internal pure returns (bytes memory inputNotes, bytes memory outputNotes, address publicOwner, int256 publicValue)This method will extract the constituent members of bytes proofOutput.
NoteUtils.extractNote(bytes memory note) internal pure returns (address owner, bytes32 noteHash, bytes memory metaData)
NoteUtils.extractNote(bytes memory note) internal pure returns (address owner, bytes32 noteHash, bytes memory metaData)This method will extract the constituent members of an AZTEC ABI-encoded note. Such as the notes contained inside proofOutput.inputNotes and proofOutput.outputNotes.
NoteUtils.getNoteType(bytes memory note) internal pure returns (uint256 noteType)
NoteUtils.getNoteType(bytes memory note) internal pure returns (uint256 noteType)Extracting the 'type' of a note is provided as a separate method, as this is a rare requirement and its including inside NoteUtils.extractNote would bloat the number of stack variables required by the method.
Appendix
A: Preventing collisions and front-running
For any AZTEC verification smart contract, the underlying zero-knowledge protocol must have a formal proof describing the protocol's completeness, soundness and honest-verifier zero-knowledge properties.
In addition to this, and faithfully implementing the logic of the protocol inside a smart contract, steps must be undertaken to prevent 'proof collision', where a bytes proofOutput instruction from a proof has an identical structure to a bytes proofOutput instruction from a different smart contract verifier. This is done by integrating the uint24 _proof variable associated with that specific verification smart contract into the uint256 challenge variable contained in each bytes proofOutput entry.
Secondly, the front-running of proofs must be prevented. This is the act of taking a valid zero-knowledge proof that is inside the transaction pool but not yet mined, and integrating the proof into a malicious transaction for some purpose that is different to that of the transaction sender. This is achieved by integrating the message sender into challenge variable - it will not be possible for a malicious actor to modify such a proof to create a valid proof of their own construction, unless they know the secret witnesses used in the proof.
Getting msg.sender into the verification contract is done by passing through this variable as an input argument from the contract that is calling ACE.sol. If this is not done correctly, the asset in question is susceptible to front-running. This does not expose any security risk for the protocol, as assets that correctly use ACE are not affected by assets that incorrectly implement the protocol.
B - Interest streaming via AZTEC notes
Consider a contract that accepts a DAI note (let's call it the origination note), and issues confidential Loan notes in exchange, where the sum of the values of the loan notes is equal to the sum of the values of the origination note (this is enforced).
When a deposit of confidential DAI is supplied to the contract in the form of an interest payment (call it an interest note), a ratio is defined between the value of the interest note and the origination note.
The AZTEC Cryptography Engine supports a zero-knowledge proof that allows loan 'note' holders to stream value out of the interest note. Effectively printing zkDAI notes whose value is defined by the above ratio and the absolute value of their loan note. In exchange, the interest note is destroyed.
What is important to highlight in this exchange, is that the zk-DAI contract is not having to make any assumptions about the zk-Loan contract, or trust in the correctness of the zk-Loan contract's logic.
The zero-knowledge proofs in ACE enable the above exchange to occur with a gaurantee that there is no double spending. The above mechanism cannot be used to 'print' zk-DAI notes whose sum is greater than the interest note. NoteRegistry and ACE only validate the mathematical correctness of the transaction - whether the loan notes (and resulting interest payments) are correctly distrubted according to the semantics of the loan's protocol is not relevant to ensure that there is no double spending.
Glossary
Link to our specification on Github.
Last updated
