From 5ba8a798d188b45f081a53f0fa6b2cbe58d2ebf7 Mon Sep 17 00:00:00 2001 From: LHerskind Date: Tue, 2 Apr 2024 09:55:41 +0000 Subject: [PATCH] docs: remove view and update docs --- .../aztecjs/guides/call_view_function.md | 14 ++++++---- docs/docs/misc/migration_notes.md | 26 +++++++++++++++++++ docs/internal_notes/building_dapps.md | 1 - .../contract/contract_function_interaction.ts | 20 +++++++++++--- yarn-project/circuit-types/src/tx/tx.ts | 2 +- .../end-to-end/src/docs_examples.test.ts | 4 +-- .../end-to-end/src/e2e_avm_simulator.test.ts | 2 +- .../src/sequencer/abstract_phase_manager.ts | 8 +++--- yarn-project/simulator/README.md | 8 +++--- .../simulator/src/client/private_execution.ts | 2 +- 10 files changed, 65 insertions(+), 22 deletions(-) diff --git a/docs/docs/developers/aztecjs/guides/call_view_function.md b/docs/docs/developers/aztecjs/guides/call_view_function.md index 0e5cbbbd2586..5028bded9971 100644 --- a/docs/docs/developers/aztecjs/guides/call_view_function.md +++ b/docs/docs/developers/aztecjs/guides/call_view_function.md @@ -1,8 +1,8 @@ --- -title: How to Call a View Function +title: How to Simulate a Function Call --- -This guide explains how to call a `view` function using [Aztec.js](../main.md). +This guide explains how to `simulate` a function call using [Aztec.js](../main.md). To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#calling-an-unconstrained-view-function). @@ -26,9 +26,13 @@ Get a previously deployed contract like this: #include_code get_contract yarn-project/end-to-end/src/docs_examples.test.ts typescript -## Call view function +## Simulating function calls -Call the `view` function on the contract like this: +Call the `simulate` function on the typescript contract wrapper like this: -#include_code call_view_function yarn-project/end-to-end/src/docs_examples.test.ts typescript +#include_code simulate_function yarn-project/end-to-end/src/docs_examples.test.ts typescript +:::info Note +- If the simulated function is `unconstrained` you will get a properly typed value. +- If the simulated function is `public` or `private` it will return a Field array of size 4. +::: \ No newline at end of file diff --git a/docs/docs/misc/migration_notes.md b/docs/docs/misc/migration_notes.md index e21dedfe857a..224546c0b852 100644 --- a/docs/docs/misc/migration_notes.md +++ b/docs/docs/misc/migration_notes.md @@ -17,6 +17,32 @@ This change was made to communicate that we do not constrain the value in circui + let random_value = unsafe_rand(); ``` +### [AztecJS] Simulate and get return values for ANY call +Historically it have been possible to "view" `unconstrained` functions to simulate them and get the return values, but not for `public` nor `private` functions. +This have lead to a lot of bad code where we have the same function implemented thrice, once in `private`, once in `public` and once in `unconstrained`. +It is not possible to call `simulate` on any call to get the return values! +However, beware that it currently always return a Field array of size 4 for private and public. +This will change to become similar to the return values of the `unconstrained` with proper return times. + +```diff +- #[aztec(private)] +- fn get_shared_immutable_constrained_private() -> pub Leader { +- storage.shared_immutable.read_private() +- } +- +- unconstrained fn get_shared_immutable() -> pub Leader { +- storage.shared_immutable.read_public() +- } + ++ #[aztec(private)] ++ fn get_shared_immutable_private() -> pub Leader { ++ storage.shared_immutable.read_private() ++ } + +- const returnValues = await contract.methods.get_shared_immutable().view(); ++ const returnValues = await contract.methods.get_shared_immutable_private().simulate(); +``` + ## 0.31.0 ### [Aztec.nr] Public storage historical read API improvement diff --git a/docs/internal_notes/building_dapps.md b/docs/internal_notes/building_dapps.md index 4cc8792a3bde..f4b65fa93190 100644 --- a/docs/internal_notes/building_dapps.md +++ b/docs/internal_notes/building_dapps.md @@ -22,7 +22,6 @@ Explain how to write a dapp using [`aztec.js`](https://github.com/AztecProtocol/ - Instantiate a contract - Deploy a contract - How to generate a nice typescript interface for an Aztec.nr contract's functions (we have a little `.ts` program in `noir-contracts` to generate a types file at the moment... how would a user do this?) - - Call 'view' functions - Simulate functions (simulate the result, without sending to the 'network') - Execute functions (send them to the 'network') - Tx hashes and tx receipts diff --git a/yarn-project/aztec.js/src/contract/contract_function_interaction.ts b/yarn-project/aztec.js/src/contract/contract_function_interaction.ts index 683523ff005a..1c3fec195f0b 100644 --- a/yarn-project/aztec.js/src/contract/contract_function_interaction.ts +++ b/yarn-project/aztec.js/src/contract/contract_function_interaction.ts @@ -8,10 +8,11 @@ import { BaseContractInteraction, SendMethodOptions } from './base_contract_inte export { SendMethodOptions }; /** - * Represents the options for a view method in a contract function interaction. + * Represents the options for simulating a contract function interaction. * Allows specifying the address from which the view method should be called. + * Disregarded for simulation of public functions */ -export type ViewMethodOptions = { +export type SimulateMethodOptions = { /** * The sender's Aztec address. */ @@ -64,10 +65,20 @@ export class ContractFunctionInteraction extends BaseContractInteraction { /** * Simulate a transaction and get its return values + * Differs from prove in a few important ways: + * 1. It returns the values of the function execution + * 2. It supports `unconstrained`, `private` and `public` functions + * 3. For `private` execution it: + * 3.a SKIPS the entrypoint and starts directly at the function + * 3.b SKIPS public execution entirely + * 4. For `public` execution it: + * 4.a Removes the `txRequest` value after ended simulation + * 4.b Ignores the `from` in the options + * * @param options - An optional object containing additional configuration for the transaction. - * @returns The result of the view transaction as returned by the contract function. + * @returns The result of the transaction as returned by the contract function. */ - public async simulate(options: ViewMethodOptions = {}): Promise { + public async simulate(options: SimulateMethodOptions = {}): Promise { if (this.functionDao.functionType == FunctionType.UNCONSTRAINED) { return this.wallet.viewTx(this.functionDao.name, this.args, this.contractAddress, options.from); } @@ -93,6 +104,7 @@ export class ContractFunctionInteraction extends BaseContractInteraction { } else { const txRequest = await this.create(); const vue = await this.pxe.simulateTx(txRequest, true); + this.txRequest = undefined; return vue.publicReturnValues && vue.publicReturnValues[0]; } } diff --git a/yarn-project/circuit-types/src/tx/tx.ts b/yarn-project/circuit-types/src/tx/tx.ts index 908de35f0bb4..f8526a0ba7ed 100644 --- a/yarn-project/circuit-types/src/tx/tx.ts +++ b/yarn-project/circuit-types/src/tx/tx.ts @@ -7,7 +7,7 @@ import { SideEffect, SideEffectLinkedToNoteHash, } from '@aztec/circuits.js'; -import { ProcessReturnValues } from '@aztec/foundation/abi'; +import { type ProcessReturnValues } from '@aztec/foundation/abi'; import { arrayNonEmptyLength } from '@aztec/foundation/collection'; import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize'; diff --git a/yarn-project/end-to-end/src/docs_examples.test.ts b/yarn-project/end-to-end/src/docs_examples.test.ts index 517794359898..07512e922174 100644 --- a/yarn-project/end-to-end/src/docs_examples.test.ts +++ b/yarn-project/end-to-end/src/docs_examples.test.ts @@ -43,9 +43,9 @@ describe('docs_examples', () => { const _tx = await contract.methods.mint_public(wallet.getAddress(), 1).send().wait(); // docs:end:send_transaction - // docs:start:call_view_function + // docs:start:simulate_function const balance = await contract.methods.balance_of_public(wallet.getAddress()).simulate(); expect(balance).toEqual(1n); - // docs:end:call_view_function + // docs:end:simulate_function }, 120_000); }); diff --git a/yarn-project/end-to-end/src/e2e_avm_simulator.test.ts b/yarn-project/end-to-end/src/e2e_avm_simulator.test.ts index 86e1c392162e..a9c2df4e4118 100644 --- a/yarn-project/end-to-end/src/e2e_avm_simulator.test.ts +++ b/yarn-project/end-to-end/src/e2e_avm_simulator.test.ts @@ -27,7 +27,7 @@ describe('e2e_avm_simulator', () => { describe('Storage', () => { // FIX: Enable once the contract function works. // it('Read immutable (initialized) storage (Field)', async () => { - // expect(await avmContact.methods.view_storage_immutable().view()).toEqual(42n); + // expect(await avmContact.methods.view_storage_immutable().simulate()).toEqual(42n); // }); it('Modifies storage (Field)', async () => { diff --git a/yarn-project/sequencer-client/src/sequencer/abstract_phase_manager.ts b/yarn-project/sequencer-client/src/sequencer/abstract_phase_manager.ts index 912ee0a26a0f..c26f2a2e2a2a 100644 --- a/yarn-project/sequencer-client/src/sequencer/abstract_phase_manager.ts +++ b/yarn-project/sequencer-client/src/sequencer/abstract_phase_manager.ts @@ -43,10 +43,10 @@ import { } from '@aztec/circuits.js'; import { computeVarArgsHash } from '@aztec/circuits.js/hash'; import { - ABIType, - DecodedReturn, - FunctionArtifact, - ProcessReturnValues, + type ABIType, + type DecodedReturn, + type FunctionArtifact, + type ProcessReturnValues, decodeReturnValues, } from '@aztec/foundation/abi'; import { arrayNonEmptyLength, padArrayEnd } from '@aztec/foundation/collection'; diff --git a/yarn-project/simulator/README.md b/yarn-project/simulator/README.md index 41b8fe31baf6..ec524980fc84 100644 --- a/yarn-project/simulator/README.md +++ b/yarn-project/simulator/README.md @@ -28,13 +28,15 @@ They are run with the assistance of an oracle that provides any value read from Public functions can call other public function, but no private functions. -### Unconstrained (view) Functions +### Unconstrained Functions -Unconstrained functions are used to extract useful data for users, such as the user balance. They are not proved, and are simulated client-side. +Unconstrained functions are useful to extract useful data for users that could produce very large execution traces - such as the summed balance of all a users notes +They are not proved, and are simulated client-side. They are run with the assistance of a DB oracle that provides any private data requested by the function. -At the moment, unconstrained functions cannot call any other function. It would be possible to allow them to call other unconstrained functions. +At the moment, unconstrained functions cannot call any other function. +It would be possible to allow them to call other unconstrained functions. ## Usage diff --git a/yarn-project/simulator/src/client/private_execution.ts b/yarn-project/simulator/src/client/private_execution.ts index 74802c3e0355..2eb822b4b7a8 100644 --- a/yarn-project/simulator/src/client/private_execution.ts +++ b/yarn-project/simulator/src/client/private_execution.ts @@ -1,5 +1,5 @@ import { type FunctionData, PrivateCallStackItem, PrivateCircuitPublicInputs } from '@aztec/circuits.js'; -import { type FunctionArtifactWithDebugMetadata, decodeReturnValues, type ABIType } from '@aztec/foundation/abi'; +import { type ABIType, type FunctionArtifactWithDebugMetadata, decodeReturnValues } from '@aztec/foundation/abi'; import { type AztecAddress } from '@aztec/foundation/aztec-address'; import { Fr } from '@aztec/foundation/fields'; import { createDebugLogger } from '@aztec/foundation/log';