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.
getContacts
▸ getContacts(): Promise<AztecAddress[]>
Retrieves the addresses stored as contacts on this PXE Service.
Returns
Promise<AztecAddress[]>
An array of the contacts on this PXE Service.
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 Contract 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>
getContractClassLogs
▸ getContractClassLogs(filter): Promise<GetUnencryptedLogsResponse>
Gets contract class 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.
getContractInstance
▸ getContractInstance(address): Promise<undefined | ContractInstanceWithAddress>
Returns a Contract 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.
getEncryptedEvents
▸ getEncryptedEvents<T>(eventMetadata, from, limit, vpks): Promise<T[]>
Returns the enctypred events given search parameters.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type | Description |
|---|---|---|
eventMetadata | EventMetadataDefinition | Metadata 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[] | 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<39>]>
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<39>]>
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.
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.
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 | InBlock<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 | InBlock<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.
getUnencryptedEvents
▸ getUnencryptedEvents<T>(eventMetadata, from, limit): Promise<T[]>
Returns the unenctypred events given search parameters.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type | Description |
|---|---|---|
eventMetadata | EventMetadataDefinition | Metadata 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. |
Returns
Promise<T[]>
- The deserialized events.
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.
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, privateExecutionResult): Promise<TxProvingResult>
Creates a proving result based on the provided preauthenticated execution request and the results of executing the private part of the transaction. This will assemble the zero-knowledge proof for the private execution. It returns an object that contains the proof and public inputs of the tail circuit, which can be converted into a Tx ready to be sent to the network
Parameters
| Name | Type | Description |
|---|---|---|
txRequest | TxExecutionRequest | An authenticated tx request ready for proving |
privateExecutionResult | PrivateExecutionResult | The result of the private execution of the transaction |
Returns
Promise<TxProvingResult>
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.
registerContact
▸ registerContact(address): Promise<AztecAddress>
Registers a user contact in PXE.
Once a new contact is registered, the PXE Service will be able to receive notes tagged from this contact. Will do nothing if the account is already registered.
Parameters
| Name | Type | Description |
|---|---|---|
address | AztecAddress | Address of the user to add to the address book |
Returns
Promise<AztecAddress>
The address 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>
removeContact
▸ removeContact(address): Promise<void>
Removes a contact in the address book.
Parameters
| Name | Type |
|---|---|
address | AztecAddress |
Returns
Promise<void>
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?, profile?, scopes?): Promise<TxSimulationResult>
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), run the kernel circuits to ensure adherence to protocol rules (without generating a proof), and return the simulation results .
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. |
profile? | boolean | (Optional) If true, will run the private kernel prover with profiling enabled and include the result (gate count) in TxSimulationResult. |
scopes? | AztecAddress[] | (Optional) The accounts whose notes we can access in this call. Currently optional and will default to all. |
Returns
Promise<TxSimulationResult>
A simulated transaction result object that includes 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<AbiDecoded>
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<AbiDecoded>
The result of the view function call, structured based on the function ABI.