Developer SDK

AZTEC uses a UTXO model under the hood. A user's balance is the sum of all the UTXO notes they own for any given asset. Each UTXO note has a unique viewing key, which can be used to decrypt the value of the note.

Managing a particular user's UTXO notes and associated viewing keys is complicated and can impact a user's privacy. To make this easier for developers and users we have built a JavaScript SDK that manages a user's notes and associated viewing keys.

This SDK is in ALPHA form and only suitable for hackathon projects. We expect to reach BETA at the start of December.

The eth-global-starter-kit

We have prepared a simple JavaScript demo package to test out the developer SDK.

GitHub - AztecProtocol/sdk-starter-kitGitHub

You can get started by:

git clone https://github.com/AztecProtocol/eth-global-starter-kit.git
cd eth-global-starter-kit
yarn install && yarn global add serve
serve -p 3000

Navigate back to localhost:3000. You are now ready to send private transactions!🕵️‍♀️

Getting Started

Installing the developer SDK in your own dApp

The AZTEC SDK can be installed with one line of JavaScript.

<script type="module" src="https://sdk.aztecprotocol.com/aztec.js" />

Once the SDK has loaded it will inject the following object to the window of every page:

window.aztec = {
    enable: async function (options) {}
}

To interact with the SDK in your dApp simply call the exposed function:

`window.aztec.enable(options)`

The .enable() function takes one optional argument. This argument can be used to override default values such as which web3Provider is used, or the contractAddresses of two key contracts ace and aztecAccountRegistry if you are running the SDK against a local network.

It can also be used to feed in an apiKey. This key gives you free transactions through GSN (Gas Station Network), but is not required to use the SDK.

{
    web3Provider: window.web3.currentProvider, // change this value to use a different web3 provider
    contractAddresses: {
        ace: '0xFA8eD6F76e8f769872a1f8a89085c56909EC8Cfc', // the address of the ace contract on the local network
        aztecAccountRegistry: '0xFA8eD6F76e8f769872a1f8a89085c56909EC8Cfc', // the address of the aztec account registry contract on the local network.    
    },
    apiKey: 'apiKey' // API key for use with GSN for free txs.
}

Calling .enable() will perform 3 key actions:

Create a keypair for the user, that is used for encrypting and decrypting AZTEC Note viewing keys.
Store the keypair in an encrypted keyvault in local storage of aztecprotocol.com, encrypted with the user's password.
Ensure the public key of the keypair has been linked to an ethereum address on chain via the AZTECAccountRegistry.sol contract.

The function returns a promise which resolves to the full AZTEC api if all checks pass.

Calling .enable() from a user's perspective

When window.aztec.enable() is called in browser for the first time, it will guide a user through the creation of a new AZTEC account.

The user will first be prompted to approve the web3 provider to be enabled on the page. If you are using MetaMask (recommended) this will show a popup like this:

Once approved, the AZTEC SDK will open a window asking the user to register the address to the SDK:

The user can either restore an existing set of keys or register a new set.

The user must then choose a password to encrypt the keyvault and ensure the keyvault can be stored safely in encrypted form.

Finally the user must link their Ethereum account the SDK by signing an EIP712 signature in MetaMask.

Interacting with zero-knowledge assets

Once the SDK is enabled, you can start interacting with zkAssets by calling window.aztec.asset(zkAssetAddress), where zkAssetAddress is the address of any deployed zkAsset.

const asset = await window.aztec.asset('0x3339C3c842732F4DAaCf12aed335661cf4eab66b');

If the page has not already requested access to a user's balance, calling the above will open a popup asking the user to grant the domain access to the asset's balance and allow the SDK to construct proofs for this asset.

Once this permission has been granted, the exposed methods on the asset object include:

`async asset.balance()`

Returns a promise that resolves to an integer representing the balance of the asset.

`async asset.fetchNotesFromBalance(query)`

Returns a promise that resolves to the list of AZTEC notes owned by the user which match the query, or all notes if no query is provided. The query object is structured:

{
    numberOfNotes: 1, // number of notes which match the query to return
    equalTo: 20, // the exact value all returned notes need to match
    greaterThan: 10, // if no equalTo parameter, the minimum value of notes returned
    lessThan: 30, // if no equalTo parameter, the maximum value of notes returned
}

`async asset.deposit(transactions)`

This method is used to convert ERC20 tokens of the linkedTokenAddress into AZTEC note form.

await asset.deposit([{
    to: '0x0563a36603911daaB46A3367d59253BaDF500bF9',
    amount: 50
}]);

`async asset.withdraw(amount)`

This method is used to convert AZTEC notes into ERC20 tokens of the linkedTokenAddress

await asset.withdraw([{
    to: '0x0563a36603911daaB46A3367d59253BaDF500bF9',
    amount: 50
}]);

`async asset.send([tx])`

This method is used to send AZTEC notes to another owner.

await asset.send([{
    to: '0x0563a36603911daaB46A3367d59253BaDF500bF9',
    amount: 50
}]);

`async asset.refresh()`

This method is used to refresh the balance of the asset to the latest indexed version.

Interacting with zero-knowledge notes

For some more advanced proofs, you may need to work with AZTEC notes directly. You can get a list of notes using asset.fetchNotesFromBalance() , which returns a list of note objects.

Alternatively, you can get an individual note you know the noteHash for by callingasync window.aztec.note(noteHash)

On each note object, you have access to the following methods and :

`async note.grantNoteAccess(address)`

This method grants the passed in address access to the note. This is needed if another party needs to use the note in a proof. e.g PrivateRange proof, or Swap proof.

This method will trigger a MetaMask transaction as the notes metadata needs to be updated and broadcast on chain.

`.value`

This is a static integer representing the value of the note if the user has access to it.

`.hash`

This is a static string containing the hash of the note.

`.owner`

This is a static string containing the ethereum address of the notes owner.

Use advanced proofs

If you want to make use of more advanced proofs, you will need to import aztec.js (available on NPM) in your project. An API spec for aztec.js is available here.

These more advanced proofs include:

PrivateRange, which enables comparisons between two encrypted notes.

PublicRange, which enables comparisons between a public integer and an encrypted note

JoinSplit, which is the underlying proof used in the .send() method in the SDK

BilateralSwap, which is for swapping notes between assets

Mint and Burn which allow you to mint and burn on zkAssets you own.

Interacting with some of these proofs will require fetching notes of specific values, which is facilitated through the SDK.

PreviousAZTEC 0.1.0 NextLoan dApp Starter Kit

Last updated 4 years ago