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
| Name | Type | Description |
|---|---|---|
authWitness | AuthWitness | The 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
| Name | Type | Description |
|---|---|---|
capsule | Fr[] | 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, scope?): Promise<void>
Adds a note to the database.
Parameters
| Name | Type | Description |
|---|---|---|
note | ExtendedNote | The note to add. |
scope? | AztecAddress | The scope to add the note under. Currently optional. |
Returns
Promise<void>
Throws
If the note hash of the note doesn't exist in the tree.
addNullifiedNote
▸ addNullifiedNote(note): Promise<void>
Adds a nullified note to the database.
Parameters
| Name | Type | Description |
|---|---|---|
note | ExtendedNote | The note to add. |
Returns
Promise<void>
Throws
If the note hash of the note doesn't exist in the tree.
Dev
We are not deriving a nullifier in this function since that would require having the nullifier secret key which is undesirable. Instead, we are just adding the note to the database as nullified and the nullifier is set to 0 in the db.
getAuthWitness
▸ getAuthWitness(messageHash): Promise<undefined | Fr[]>
Fetches the serialized auth witness for a given message hash or returns undefined if not found.
Parameters
| Name | Type | Description |
|---|---|---|
messageHash | Fr | The 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
| Name | Type | Description |
|---|---|---|
number | number | The 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.
getContractArtifact
▸ getContractArtifact(id): Promise<undefined | ContractArtifact>
Returns the contract artifact associated to a contract class.
Parameters
| Name | Type | Description |
|---|---|---|
id | Fr | Identifier of the class. |
Returns
Promise<undefined | ContractArtifact>
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
| Name | Type | Description |
|---|---|---|
id | Fr | Identifier 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
| Name | Type | Description |
|---|---|---|
address | AztecAddress | Deployment 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.
getEvents
▸ getEvents<T>(type, eventMetadata, from, limit, vpks): Promise<T[]>
Returns the events of a specified type given search parameters.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type | Description |
|---|---|---|
type | EventType | The type of the event to search for—Encrypted, or Unencrypted. |
eventMetadata | EventMetadata<T> | Identifier of the event. This should be the class generated from the contract. e.g. Contract.events.Event |
from | number | The block number to search from. |
limit | number | The amount of blocks to search. |
vpks | Point[] | (Used for encrypted logs only) The viewing (incoming and outgoing) public keys that correspond to the viewing secret keys that can decrypt the log. |
Returns
Promise<T[]>
- The deserialized events.
getIncomingNotes
▸ getIncomingNotes(filter): Promise<UniqueNote[]>
Gets incoming notes of accounts registered in this PXE based on the provided filter.
Parameters
| Name | Type | Description |
|---|---|---|
filter | IncomingNotesFilter | The filter to apply to the notes. |
Returns
Promise<UniqueNote[]>
The requested notes.
getL1ToL2MembershipWitness
▸ getL1ToL2MembershipWitness(contractAddress, messageHash, secret): Promise<[bigint, SiblingPath<16>]>
Fetches an L1 to L2 message from the node.
Parameters
| Name | Type | Description |
|---|---|---|
contractAddress | AztecAddress | Address of a contract by which the message was emitted. |
messageHash | Fr | Hash of the message. |
secret | Fr | Secret used to compute a nullifier. |
Returns
Promise<[bigint, SiblingPath<16>]>
The l1 to l2 membership witness (index of message in the tree and sibling path).
Dev
Contract address and secret are only used to compute the nullifier to get non-nullified messages
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.
getOutgoingNotes
▸ getOutgoingNotes(filter): Promise<UniqueNote[]>
Gets outgoing notes of accounts registered in this PXE based on the provided filter.
Parameters
| Name | Type | Description |
|---|---|---|
filter | OutgoingNotesFilter | The filter to apply to the notes. |
Returns
Promise<UniqueNote[]>
The requested notes.
getPXEInfo
▸ getPXEInfo(): Promise<PXEInfo>
Returns information about this PXE.
Returns
Promise<PXEInfo>
getProvenBlockNumber
▸ getProvenBlockNumber(): Promise<number>
Fetches the current proven block number.
Returns
Promise<number>
The block number.
getPublicStorageAt
▸ getPublicStorageAt(contract, slot): Promise<Fr>
Gets the storage value at the given contract storage slot.
Parameters
| Name | Type | Description |
|---|---|---|
contract | AztecAddress | Address of the contract to query. |
slot | Fr | Slot 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
| Name | Type | Description |
|---|---|---|
address | AztecAddress | The 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
| Name | Type | Description |
|---|---|---|
address | AztecAddress | The 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
| Name | Type | Description |
|---|---|---|
txHash | TxHash | The 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
| Name | Type | Description |
|---|---|---|
txHash | TxHash | The transaction hash. |
Returns
Promise<TxReceipt>
A receipt of the transaction.
getUnencryptedLogs
▸ getUnencryptedLogs(filter): Promise<GetUnencryptedLogsResponse>
Gets unencrypted logs based on the provided filter.
Parameters
| Name | Type | Description |
|---|---|---|
filter | LogFilter | The 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
| Name | Type | Description |
|---|---|---|
account | AztecAddress | The 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
| Name | Type | Description |
|---|---|---|
id | Fr | Identifier of the class. |
Returns
Promise<boolean>
isContractInitialized
▸ isContractInitialized(address): Promise<boolean>
Queries the node to check whether the contract instance with the given address has been initialized, by checking the standard initialization nullifier.
Parameters
| Name | Type | Description |
|---|---|---|
address | AztecAddress | Address of the contract to check. |
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
| Name | Type |
|---|---|
address | AztecAddress |
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, scopes?): 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
| Name | Type | Description |
|---|---|---|
txRequest | TxExecutionRequest | An authenticated tx request ready for simulation |
simulatePublic | boolean | Whether to simulate the public part of the transaction. |
scopes? | AztecAddress[] | (Optional) The accounts whose notes we can access in this call. Currently optional and will default to all. |
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
| Name | Type | Description |
|---|---|---|
secretKey | Fr | Secret key of the corresponding user master public key. |
partialAddress | Fr | The 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
| Name | Type | Description |
|---|---|---|
contract | Object | A contract instance to register, with an optional artifact which can be omitted if the contract class has already been registered. |
contract.artifact? | ContractArtifact | - |
contract.instance | ContractInstanceWithAddress | - |
Returns
Promise<void>
registerContractClass
▸ registerContractClass(artifact): Promise<void>
Registers a contract class in the PXE without registering any associated contract instance with it.
Parameters
| Name | Type | Description |
|---|---|---|
artifact | ContractArtifact | The 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
| Name | Type | Description |
|---|---|---|
recipient | CompleteAddress | The 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
| Name | Type | Description |
|---|---|---|
address | AztecAddress | The address of the account we want to rotate our key for. |
newNskM | Fq | The 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
| Name | Type | Description |
|---|---|---|
tx | Tx | The transaction as created via proveTx. |
Returns
Promise<TxHash>
A hash of the transaction, used to identify it.
simulateTx
▸ simulateTx(txRequest, simulatePublic, msgSender?, skipTxValidation?, scopes?): 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
| Name | Type | Description |
|---|---|---|
txRequest | TxExecutionRequest | An authenticated tx request ready for simulation |
simulatePublic | boolean | Whether to simulate the public part of the transaction. |
msgSender? | AztecAddress | (Optional) The message sender to use for the simulation. |
skipTxValidation? | boolean | (Optional) If false, this function throws if the transaction is unable to be included in a block at the current state. |
scopes? | AztecAddress[] | (Optional) The accounts whose notes we can access in this call. Currently optional and will default to all. |
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?, scopes?): 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
| Name | Type | Description |
|---|---|---|
functionName | string | The name of the function to be called in the contract. |
args | any[] | The arguments to be provided to the function. |
to | AztecAddress | The address of the contract to be called. |
from? | AztecAddress | (Optional) The msg sender to set for the call. |
scopes? | AztecAddress[] | (Optional) The accounts whose notes we can access in this call. Currently optional and will default to all. |
Returns
Promise<any>
The result of the view function call, structured based on the function ABI.