diff --git a/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md index 98a660a7c02..c94c39534e7 100644 --- a/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md @@ -203,7 +203,7 @@ First, storage is initialized. Then the function checks that the `msg_sender` is This public function allows an account approved in the public `minters` mapping to create new private tokens. -First, partial note is prepared by the call to `_prepare_transfer_to_private` for the minted tokens recipient. Then a public call to `_finalize_mint_to_private_unsafe` is enqueued while `msg_sender`, `amount` and the `hiding_point_slot` are passed in via arguments. Since we set `from` to `msg_sender` here the usage of the unsafe function is safe. The enqueued call then checks the minter permissions of `from` and it finalizes the partial note for `to`. +First, partial note is prepared by the call to `_prepare_private_balance_increase` for the minted tokens recipient. Then a public call to `_finalize_mint_to_private_unsafe` is enqueued while `msg_sender`, `amount` and the `hiding_point_slot` are passed in via arguments. Since we set `from` to `msg_sender` here the usage of the unsafe function is safe. The enqueued call then checks the minter permissions of `from` and it finalizes the partial note for `to`. #include_code mint_to_private /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust diff --git a/noir-projects/noir-contracts/contracts/nft_contract/src/main.nr b/noir-projects/noir-contracts/contracts/nft_contract/src/main.nr index 401e5b015ed..ccefcbef97f 100644 --- a/noir-projects/noir-contracts/contracts/nft_contract/src/main.nr +++ b/noir-projects/noir-contracts/contracts/nft_contract/src/main.nr @@ -150,8 +150,8 @@ contract NFT { let nft = NFT::at(context.this_address()); - // We prepare the transfer. - let hiding_point_slot = _prepare_transfer_to_private(to, &mut context, storage); + // We prepare the private balance increase. + let hiding_point_slot = _prepare_private_balance_increase(to, &mut context, storage); // At last we finalize the transfer. Usafe of the `unsafe` method here is safe because we set the `from` // function argument to a message sender, guaranteeing that he can transfer only his own NFTs. @@ -160,20 +160,20 @@ contract NFT { ); } - /// Prepares a transfer to a private balance of `to`. The transfer then needs to be - /// finalized by calling `finalize_transfer_to_private`. Returns a hiding point slot. + /// Prepares an increase of private balance of `to` (partial note). The increase needs to be finalized by calling + /// `finalize_transfer_to_private. Returns a hiding point slot. #[private] - fn prepare_transfer_to_private(to: AztecAddress) -> Field { - _prepare_transfer_to_private(to, &mut context, storage) + fn prepare_private_balance_increase(to: AztecAddress) -> Field { + _prepare_private_balance_increase(to, &mut context, storage) } - /// This function exists separately from `prepare_transfer_to_private` solely as an optimization as it allows + /// This function exists separately from `prepare_private_balance_increase` solely as an optimization as it allows /// us to have it inlined in the `transfer_to_private` function which results in one less kernel iteration. /// /// TODO(#9180): Consider adding macro support for functions callable both as an entrypoint and as an internal /// function. #[contract_library_method] - fn _prepare_transfer_to_private( + fn _prepare_private_balance_increase( to: AztecAddress, context: &mut PrivateContext, storage: Storage<&mut PrivateContext>, @@ -235,7 +235,7 @@ contract NFT { } /// Finalizes a transfer of NFT with `token_id` from public balance of `from` to a private balance of `to`. - /// The transfer must be prepared by calling `prepare_transfer_to_private` first and the resulting + /// The transfer must be prepared by calling `prepare_private_balance_increase` first and the resulting /// `hiding_point_slot` must be passed as an argument to this function. #[public] fn finalize_transfer_to_private(token_id: Field, hiding_point_slot: Field) { diff --git a/noir-projects/noir-contracts/contracts/nft_contract/src/test/transfer_to_private.nr b/noir-projects/noir-contracts/contracts/nft_contract/src/test/transfer_to_private.nr index 742109682dc..03f59109aec 100644 --- a/noir-projects/noir-contracts/contracts/nft_contract/src/test/transfer_to_private.nr +++ b/noir-projects/noir-contracts/contracts/nft_contract/src/test/transfer_to_private.nr @@ -6,7 +6,7 @@ use dep::aztec::{ }; use std::test::OracleMock; -/// Internal orchestration means that the calls to `prepare_transfer_to_private` +/// Internal orchestration means that the calls to `prepare_private_balance_increase` /// and `finalize_transfer_to_private` are done by the NFT contract itself. /// In this test's case this is done by the `NFT::transfer_to_private(...)` function called /// in `utils::setup_mint_and_transfer_to_private`. @@ -40,7 +40,7 @@ unconstrained fn transfer_to_private_external_orchestration() { // We prepare the transfer let hiding_point_slot: Field = NFT::at(nft_contract_address) - .prepare_transfer_to_private(recipient) + .prepare_private_balance_increase(recipient) .call(&mut env.private()); // Finalize the transfer of the NFT (message sender owns the NFT in public) @@ -96,7 +96,7 @@ unconstrained fn transfer_to_private_failure_not_an_owner() { // as the NFT owner check is before we use the value but that would made the test less robust against changes // in the contract.) let hiding_point_slot: Field = NFT::at(nft_contract_address) - .prepare_transfer_to_private(not_owner) + .prepare_private_balance_increase(not_owner) .call(&mut env.private()); // Try transferring someone else's public NFT diff --git a/noir-projects/noir-contracts/contracts/token_contract/src/main.nr b/noir-projects/noir-contracts/contracts/token_contract/src/main.nr index 912454a55d2..e327690b2f1 100644 --- a/noir-projects/noir-contracts/contracts/token_contract/src/main.nr +++ b/noir-projects/noir-contracts/contracts/token_contract/src/main.nr @@ -433,8 +433,8 @@ contract Token { let from = context.msg_sender(); let token = Token::at(context.this_address()); - // We prepare the transfer. - let hiding_point_slot = _prepare_transfer_to_private(from, to, &mut context, storage); + // We prepare the private balance increase (the partial note). + let hiding_point_slot = _prepare_private_balance_increase(from, to, &mut context, storage); // At last we finalize the transfer. Usage of the `unsafe` method here is safe because we set the `from` // function argument to a message sender, guaranteeing that he can transfer only his own tokens. @@ -444,21 +444,22 @@ contract Token { } // docs:end:transfer_to_private - /// Prepares a transfer to a private balance of `to`. The transfer then needs to be - /// finalized by calling `finalize_transfer_to_private`. Returns a hiding point slot. + /// Prepares an increase of private balance of `to` (partial note). The increase needs to be finalized by calling + /// some of the finalization functions (`finalize_transfer_to_private`, `finalize_mint_to_private`). + /// Returns a hiding point slot. #[private] - fn prepare_transfer_to_private(to: AztecAddress) -> Field { + fn prepare_private_balance_increase(to: AztecAddress) -> Field { let from = context.msg_sender(); - _prepare_transfer_to_private(from, to, &mut context, storage) + _prepare_private_balance_increase(from, to, &mut context, storage) } - /// This function exists separately from `prepare_transfer_to_private` solely as an optimization as it allows + /// This function exists separately from `prepare_private_balance_increase` solely as an optimization as it allows /// us to have it inlined in the `transfer_to_private` function which results in one less kernel iteration. /// /// TODO(#9180): Consider adding macro support for functions callable both as an entrypoint and as an internal /// function. #[contract_library_method] - fn _prepare_transfer_to_private( + fn _prepare_private_balance_increase( from: AztecAddress, // recipient of the outgoing: TODO(#9887): this is not great? to: AztecAddress, context: &mut PrivateContext, @@ -504,7 +505,7 @@ contract Token { } /// Finalizes a transfer of token `amount` from public balance of `from` to a private balance of `to`. - /// The transfer must be prepared by calling `prepare_transfer_to_private` first and the resulting + /// The transfer must be prepared by calling `prepare_private_balance_increase` first and the resulting /// `hiding_point_slot` must be passed as an argument to this function. #[public] fn finalize_transfer_to_private(amount: Field, hiding_point_slot: Field) { @@ -557,7 +558,7 @@ contract Token { let token = Token::at(context.this_address()); // We prepare the partial note to which we'll "send" the minted amount. - let hiding_point_slot = _prepare_transfer_to_private(from, to, &mut context, storage); + let hiding_point_slot = _prepare_private_balance_increase(from, to, &mut context, storage); // At last we finalize the mint. Usage of the `unsafe` method here is safe because we set the `from` // function argument to a message sender, guaranteeing that only a message sender with minter permissions @@ -569,7 +570,7 @@ contract Token { // docs:end:mint_to_private /// Finalizes a mint of token `amount` to a private balance of `to`. The mint must be prepared by calling - /// `prepare_transfer_to_private` first and the resulting + /// `prepare_private_balance_increase` first and the resulting /// `hiding_point_slot` must be passed as an argument to this function. /// /// Note: This function is only an optimization as it could be replaced by a combination of `mint_to_public` @@ -667,11 +668,11 @@ contract Token { )); // 4. We prepare the partial notes - // TODO(#9887): In each `_prepare_transfer_to_private` call we fetch the user's ovpk_m 2 more times. This is + // TODO(#9887): In each `_prepare_private_balance_increase` call we fetch the user's ovpk_m 2 more times. This is // very inefficient. let fee_payer_point_slot = - _prepare_transfer_to_private(user, fee_payer, &mut context, storage); - let user_point_slot = _prepare_transfer_to_private(user, user, &mut context, storage); + _prepare_private_balance_increase(user, fee_payer, &mut context, storage); + let user_point_slot = _prepare_private_balance_increase(user, user, &mut context, storage); // 5. Set the public teardown function to `complete_refund(...)`. Public teardown is the only time when a public // function has access to the final transaction fee, which is needed to compute the actual refund amount. diff --git a/noir-projects/noir-contracts/contracts/token_contract/src/test/transfer_to_private.nr b/noir-projects/noir-contracts/contracts/token_contract/src/test/transfer_to_private.nr index 52ff6d43915..f48bfb6127e 100644 --- a/noir-projects/noir-contracts/contracts/token_contract/src/test/transfer_to_private.nr +++ b/noir-projects/noir-contracts/contracts/token_contract/src/test/transfer_to_private.nr @@ -1,11 +1,8 @@ use crate::{test::utils, Token}; -use dep::aztec::{ - keys::getters::get_public_keys, oracle::random::random, - protocol_types::storage::map::derive_storage_slot_in_map, -}; +use dep::aztec::oracle::random::random; use std::test::OracleMock; -/// Internal orchestration means that the calls to `prepare_transfer_to_private` +/// Internal orchestration means that the calls to `prepare_private_balance_increase` /// and `finalize_transfer_to_private` are done by the TOKEN contract itself. /// In this test's case this is done by the `Token::transfer_to_private(...)` function called /// in `utils::setup_mint_and_transfer_to_private`. @@ -36,7 +33,7 @@ unconstrained fn transfer_to_private_external_orchestration() { // We prepare the transfer let hiding_point_slot: Field = Token::at(token_contract_address) - .prepare_transfer_to_private(recipient) + .prepare_private_balance_increase(recipient) .call(&mut env.private()); // Finalize the transfer of the tokens (message sender owns the tokens in public) @@ -82,7 +79,7 @@ unconstrained fn transfer_to_private_failure_not_an_owner() { // as the token balance check is before we use the value but that would made the test less robust against changes // in the contract.) let hiding_point_slot: Field = Token::at(token_contract_address) - .prepare_transfer_to_private(not_owner) + .prepare_private_balance_increase(not_owner) .call(&mut env.private()); // Try transferring someone else's token balance