Skip to main content

Interface: PXE

Private eXecution Environment (PXE) runs locally for each user, providing functionality for all the operations needed to interact with the Aztec network, including account management, private data management, transaction local simulation, and access to an Aztec node. This interface, as part of a Wallet, is exposed to dapps for interacting with the network on behalf of the user.

Methods

addAuthWitness

addAuthWitness(authWitness): Promise<void>

Insert an auth witness for a given message hash. Auth witnesses are used to authorize actions on behalf of a user. For instance, a token transfer initiated by a different address may request authorization from the user to move their tokens. This authorization is granted by the user account contract by verifying an auth witness requested to the execution oracle. Witnesses are usually a signature over a hash of the action to be authorized, but their actual contents depend on the account contract that consumes them.

Parameters

NameTypeDescription
authWitnessAuthWitnessThe auth witness to insert. Composed of an identifier, which is the hash of the action to be authorized, and the actual witness as an array of fields, which are to be deserialized and processed by the account contract.

Returns

Promise<void>


addCapsule

addCapsule(capsule): Promise<void>

Adding a capsule to the capsule dispenser.

Parameters

NameTypeDescription
capsuleFr[]An array of field elements representing the capsule.

Returns

Promise<void>

Remarks

A capsule is a "blob" of data that is passed to the contract through an oracle.


addNote

addNote(note): Promise<void>

Adds a note to the database.

Parameters

NameTypeDescription
noteExtendedNoteThe note to add.

Returns

Promise<void>

Throws

If the note hash of the note doesn't exist in the tree.


getAuthWitness

getAuthWitness(messageHash): Promise<undefined | Fr[]>

Fetches the serialized auth witness for a given message hash or returns undefined if not found.

Parameters

NameTypeDescription
messageHashFrThe hash of the message for which to get the auth witness.

Returns

Promise<undefined | Fr[]>

The serialized auth witness for the given message hash.


getBlock

getBlock(number): Promise<undefined | L2Block>

Get the given block.

Parameters

NameTypeDescription
numbernumberThe block number being requested.

Returns

Promise<undefined | L2Block>

The blocks requested.


getBlockNumber

getBlockNumber(): Promise<number>

Fetches the current block number.

Returns

Promise<number>

The block number.


getContractClass

getContractClass(id): Promise<undefined | ContractClassWithId>

Returns a Contact Class given its identifier. TODO(@spalladino): The PXE actually holds artifacts and not classes, what should we return? Also, should the pxe query the node for contract public info, and merge it with its own definitions?

Parameters

NameTypeDescription
idFrIdentifier of the class.

Returns

Promise<undefined | ContractClassWithId>


getContractInstance

getContractInstance(address): Promise<undefined | ContractInstanceWithAddress>

Returns a Contact Instance given its address, which includes the contract class identifier, initialization hash, deployment salt, and public keys hash. TODO(@spalladino): Should we return the public keys in plain as well here?

Parameters

NameTypeDescription
addressAztecAddressDeployment address of the contract.

Returns

Promise<undefined | ContractInstanceWithAddress>


getContracts

getContracts(): Promise<AztecAddress[]>

Retrieves the addresses of contracts added to this PXE Service.

Returns

Promise<AztecAddress[]>

An array of contracts addresses registered on this PXE Service.


getNodeInfo

getNodeInfo(): Promise<NodeInfo>

Returns the information about the server's node. Includes current Node version, compatible Noir version, L1 chain identifier, protocol version, and L1 address of the rollup contract.

Returns

Promise<NodeInfo>

  • The node information.

getNoteNonces

getNoteNonces(note): Promise<Fr[]>

Finds the nonce(s) for a given note.

Parameters

NameTypeDescription
noteExtendedNoteThe note to find the nonces for.

Returns

Promise<Fr[]>

The nonces of the note.

Remarks

More than a single nonce may be returned since there might be more than one nonce for a given note. TODO(#4956): Un-expose this


getNotes

getNotes(filter): Promise<ExtendedNote[]>

Gets notes of accounts registered in this PXE based on the provided filter.

Parameters

NameTypeDescription
filterNoteFilterThe filter to apply to the notes.

Returns

Promise<ExtendedNote[]>

The requested notes.


getPXEInfo

getPXEInfo(): Promise<PXEInfo>

Returns information about this PXE.

Returns

Promise<PXEInfo>


getPublicStorageAt

getPublicStorageAt(contract, slot): Promise<Fr>

Gets the storage value at the given contract storage slot.

Parameters

NameTypeDescription
contractAztecAddressAddress of the contract to query.
slotFrSlot to query.

Returns

Promise<Fr>

Storage value at the given contract slot.

Remarks

The storage slot here refers to the slot as it is defined in Noir not the index in the merkle tree. Aztec's version of eth_getStorageAt.

Throws

If the contract is not deployed.


getRecipient

getRecipient(address): Promise<undefined | CompleteAddress>

Retrieves the complete address of the recipient corresponding to the provided aztec address. Complete addresses include the address, the partial address, and the encryption public key.

Parameters

NameTypeDescription
addressAztecAddressThe aztec address of the recipient.

Returns

Promise<undefined | CompleteAddress>

The complete address of the requested recipient.


getRecipients

getRecipients(): Promise<CompleteAddress[]>

Retrieves the recipients added to this PXE Service.

Returns

Promise<CompleteAddress[]>

An array of recipients registered on this PXE Service.


getRegisteredAccount

getRegisteredAccount(address): Promise<undefined | CompleteAddress>

Retrieves the complete address of the account corresponding to the provided aztec address. Complete addresses include the address, the partial address, and the encryption public key.

Parameters

NameTypeDescription
addressAztecAddressThe address of account.

Returns

Promise<undefined | CompleteAddress>

The complete address of the requested account if found.


getRegisteredAccounts

getRegisteredAccounts(): Promise<CompleteAddress[]>

Retrieves the user accounts registered on this PXE Service.

Returns

Promise<CompleteAddress[]>

An array of the accounts registered on this PXE Service.


getSyncStats

getSyncStats(): Promise<{ [key: string]: NoteProcessorStats; }>

Returns the note processor stats.

Returns

Promise<{ [key: string]: NoteProcessorStats; }>

The note processor stats for notes for each public key being tracked.


getSyncStatus

getSyncStatus(): Promise<SyncStatus>

Returns the latest block that has been synchronized globally and for each account. The global block number indicates whether global state has been updated up to that block, whereas each address indicates up to which block the private state has been synced for that account.

Returns

Promise<SyncStatus>

The latest block synchronized for blocks, and the latest block synched for notes for each public key being tracked.


getTxEffect

getTxEffect(txHash): Promise<undefined | TxEffect>

Get a tx effect.

Parameters

NameTypeDescription
txHashTxHashThe hash of a transaction which resulted in the returned tx effect.

Returns

Promise<undefined | TxEffect>

The requested tx effect.


getTxReceipt

getTxReceipt(txHash): Promise<TxReceipt>

Fetches a transaction receipt for a given transaction hash. Returns a mined receipt if it was added to the chain, a pending receipt if it's still in the mempool of the connected Aztec node, or a dropped receipt if not found in the connected Aztec node.

Parameters

NameTypeDescription
txHashTxHashThe transaction hash.

Returns

Promise<TxReceipt>

A receipt of the transaction.


getUnencryptedLogs

getUnencryptedLogs(filter): Promise<GetUnencryptedLogsResponse>

Gets unencrypted logs based on the provided filter.

Parameters

NameTypeDescription
filterLogFilterThe filter to apply to the logs.

Returns

Promise<GetUnencryptedLogsResponse>

The requested logs.


isAccountStateSynchronized

isAccountStateSynchronized(account): Promise<boolean>

Checks if the specified account is synchronized.

Parameters

NameTypeDescription
accountAztecAddressThe aztec address for which to query the sync status.

Returns

Promise<boolean>

True if the account is fully synched, false otherwise.

Deprecated

Use getSyncStatus instead.

Remarks

Checks whether all the notes from all the blocks have been processed. If it is not the case, the retrieved information from contracts might be old/stale (e.g. old token balance).

Throws

If checking a sync status of account which is not registered.


isContractClassPubliclyRegistered

isContractClassPubliclyRegistered(id): Promise<boolean>

Queries the node to check whether the contract class with the given id has been publicly registered. TODO(@spalladino): This method is strictly needed to decide whether to publicly register a class or not during a public deployment. We probably want a nicer and more general API for this, but it'll have to do for the time being.

Parameters

NameTypeDescription
idFrIdentifier of the class.

Returns

Promise<boolean>


isContractPubliclyDeployed

isContractPubliclyDeployed(address): Promise<boolean>

Queries the node to check whether the contract instance with the given address has been publicly deployed, regardless of whether this PXE knows about the contract or not. TODO(@spalladino): Same notes as above.

Parameters

NameType
addressAztecAddress

Returns

Promise<boolean>


isGlobalStateSynchronized

isGlobalStateSynchronized(): Promise<boolean>

Checks whether all the blocks were processed (tree roots updated, txs updated with block info, etc.).

Returns

Promise<boolean>

True if there are no outstanding blocks to be synched.

Remarks

This indicates that blocks and transactions are synched even if notes are not. Compares local block number with the block number from aztec node.

Deprecated

Use getSyncStatus instead.


proveTx

proveTx(txRequest, simulatePublic): Promise<Tx>

Creates a transaction based on the provided preauthenticated execution request. This will run a local simulation of the private execution (and optionally of public as well), assemble the zero-knowledge proof for the private execution, and return the transaction object.

Parameters

NameTypeDescription
txRequestTxExecutionRequestAn authenticated tx request ready for simulation
simulatePublicbooleanWhether to simulate the public part of the transaction.

Returns

Promise<Tx>

A transaction ready to be sent to the network for execution.

Throws

If the code for the functions executed in this transaction has not been made available via addContracts. Also throws if simulatePublic is true and public simulation reverts.


registerAccount

registerAccount(secretKey, partialAddress): Promise<CompleteAddress>

Registers a user account in PXE given its master encryption private key. Once a new account is registered, the PXE Service will trial-decrypt all published notes on the chain and store those that correspond to the registered account. Will do nothing if the account is already registered.

Parameters

NameTypeDescription
secretKeyFrSecret key of the corresponding user master public key.
partialAddressFrThe partial address of the account contract corresponding to the account being registered.

Returns

Promise<CompleteAddress>

The complete address of the account.


registerContract

registerContract(contract): Promise<void>

Adds deployed contracts to the PXE Service. Deployed contract information is used to access the contract code when simulating local transactions. This is automatically called by aztec.js when deploying a contract. Dapps that wish to interact with contracts already deployed should register these contracts in their users' PXE Service through this method.

Parameters

NameTypeDescription
contractObjectA contract instance to register, with an optional artifact which can be omitted if the contract class has already been registered.
contract.artifact?ContractArtifact-
contract.instanceContractInstanceWithAddress-

Returns

Promise<void>


registerContractClass

registerContractClass(artifact): Promise<void>

Registers a contract class in the PXE without registering any associated contract instance with it.

Parameters

NameTypeDescription
artifactContractArtifactThe build artifact for the contract class.

Returns

Promise<void>


registerRecipient

registerRecipient(recipient): Promise<void>

Registers a recipient in PXE. This is required when sending encrypted notes to a user who hasn't deployed their account contract yet. Since their account is not deployed, their encryption public key has not been broadcasted, so we need to manually register it on the PXE Service in order to be able to encrypt data for this recipient.

Parameters

NameTypeDescription
recipientCompleteAddressThe complete address of the recipient

Returns

Promise<void>

Remarks

Called recipient because we can only send notes to this account and not receive them via this PXE Service. This is because we don't have the associated private key and for this reason we can't decrypt the recipient's notes. We can send notes to this account because we can encrypt them with the recipient's public key.


rotateNskM

rotateNskM(address, newNskM): Promise<void>

Rotates master nullifier keys.

Parameters

NameTypeDescription
addressAztecAddressThe address of the account we want to rotate our key for.
newNskMFqThe new master nullifier secret key we want to use.

Returns

Promise<void>

Remarks

  • One should not use this function directly without also calling the canonical key registry to rotate the new master nullifier secret key's derived master nullifier public key. Therefore, it is preferred to use rotateNullifierKeys on AccountWallet, as that handles the call to the Key Registry as well.

This does not hinder our ability to spend notes tied to a previous master nullifier public key, provided we have the master nullifier secret key for it.


sendTx

sendTx(tx): Promise<TxHash>

Sends a transaction to an Aztec node to be broadcasted to the network and mined.

Parameters

NameTypeDescription
txTxThe transaction as created via proveTx.

Returns

Promise<TxHash>

A hash of the transaction, used to identify it.


simulateTx

simulateTx(txRequest, simulatePublic, msgSender?): Promise<SimulatedTx>

Simulates a transaction based on the provided preauthenticated execution request. This will run a local simulation of private execution (and optionally of public as well), assemble the zero-knowledge proof for the private execution, and return the transaction object along with simulation results (return values).

Note that this is used with ContractFunctionInteraction::simulateTx to bypass certain checks. In that case, the transaction returned is only potentially ready to be sent to the network for execution.

Parameters

NameTypeDescription
txRequestTxExecutionRequestAn authenticated tx request ready for simulation
simulatePublicbooleanWhether to simulate the public part of the transaction.
msgSender?AztecAddress(Optional) The message sender to use for the simulation.

Returns

Promise<SimulatedTx>

A simulated transaction object that includes a transaction that is potentially ready to be sent to the network for execution, along with public and private return values.

Throws

If the code for the functions executed in this transaction has not been made available via addContracts. Also throws if simulatePublic is true and public simulation reverts.


simulateUnconstrained

simulateUnconstrained(functionName, args, to, from?): Promise<any>

Simulate the execution of an unconstrained function on a deployed contract without actually modifying state. This is useful to inspect contract state, for example fetching a variable value or calling a getter function. The function takes function name and arguments as parameters, along with the contract address and optionally the sender's address.

Parameters

NameTypeDescription
functionNamestringThe name of the function to be called in the contract.
argsany[]The arguments to be provided to the function.
toAztecAddressThe address of the contract to be called.
from?AztecAddress(Optional) The msg sender to set for the call.

Returns

Promise<any>

The result of the view function call, structured based on the function ABI.