feat: make token transfer be recursive

[nventuro]

Replaces #7271
Closes #7142
Closes #7362

This is quite similar to the implementation in #7271: transfer consumes two notes, and if their amount is insufficient for the desired transfer it calls a second internal function which recursively consumes 8 notes per iteration until either the amount is reached, or no more notes are found. If the total amount consumed exceeds the transfer amount, a change note is created.

This results in a much smaller transfer function for the scenario in which two notes suffice, since we're using a limit value of 2 and therefore only doing two iterations of note constraining (the expensive part). Two notes is a good amount as it provides a way for change notes to be consumed in follow-up calls.

The recursive call has a much lower gate count, since it doesn't need to fetch keys, create notes, emit events, etc., and so we can afford to read more notes here while still resulting in a relatively small circuit.

I created a new e2e test in which the number of notes and their amounts are quite controlled in order to properly test this. The tests are unfortunately currently interdependent, but given the relative simplicity of the test suite it should be hopefully simple to maintain and expand, and maybe eventually fix.

[github-actions]

Changes to circuit sizes

Generated at commit: e0af4caf648392f7527d17c35dcd0d5ba3c0ebf2, compared to commit: 1c596eda3f09bea03467662fd98c6c222c97f182

🧾 Summary (100% most significant diffs)

Program	ACIR opcodes (+/-)	%	Circuit size (+/-)	%
private_kernel_empty	-26 ✅	-1.35%	+1,033,495 ❌	+11831.65%
private_kernel_tail_to_public	-904 ✅	-1.22%	+282,122 ❌	+161.30%
private_kernel_tail	+1,037 ❌	+5.59%	+283,782 ❌	+111.75%
private_kernel_reset	-912 ✅	-0.84%	+446,457 ❌	+91.22%
private_kernel_reset_big	-912 ✅	-1.12%	+223,001 ❌	+79.46%
private_kernel_reset_medium	-912 ✅	-1.34%	+111,273 ❌	+63.14%
parity_base	-2 ✅	-0.57%	+28,854 ❌	+56.62%
private_kernel_reset_small	-912 ✅	-1.49%	+55,409 ❌	+44.63%
private_kernel_reset_tiny	-912 ✅	-1.58%	+27,477 ❌	+27.98%
private_kernel_init	+351 ❌	+1.23%	+9,757 ❌	+25.09%
private_kernel_init_simulated	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_inner_simulated	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_reset_simulated	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_reset_simulated_big	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_reset_simulated_medium	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_reset_simulated_small	0 ➖	0.00%	+313 ❌	+14.39%
private_kernel_reset_simulated_tiny	0 ➖	0.00%	+313 ❌	+14.39%
public_kernel_app_logic_simulated	0 ➖	0.00%	+398 ❌	+11.00%
public_kernel_setup_simulated	0 ➖	0.00%	+398 ❌	+11.00%
public_kernel_teardown_simulated	0 ➖	0.00%	+398 ❌	+11.00%
private_kernel_tail_to_public_simulated	0 ➖	0.00%	+395 ❌	+10.91%
private_kernel_inner	+414 ❌	+0.83%	+4,444 ❌	+6.64%
public_kernel_app_logic	-6,726 ✅	-2.28%	+30,697 ❌	+5.15%
public_kernel_setup	-5,214 ✅	-2.40%	+33,568 ❌	+2.13%
public_kernel_teardown	-6,726 ✅	-2.27%	+32,050 ❌	+1.93%
rollup_merge	-2 ✅	-0.07%	-2,107 ✅	-0.10%
parity_root	-1 ✅	-0.02%	-5,884 ✅	-0.14%
rollup_root	-41 ✅	-0.95%	-33,971 ✅	-1.07%
rollup_base_simulated	0 ➖	0.00%	-1 ✅	-2.94%
public_kernel_tail_simulated	0 ➖	0.00%	-26 ✅	-5.83%
private_kernel_empty_simulated	0 ➖	0.00%	-29 ✅	-6.46%
private_kernel_tail_simulated	0 ➖	0.00%	-29 ✅	-6.46%
empty_nested	0 ➖	+∞%	-3 ✅	-37.50%
empty_nested_simulated	0 ➖	0.00%	-3 ✅	-37.50%
public_kernel_tail	-38,220 ✅	-3.81%	-4,621,768 ✅	-49.84%
rollup_base	-2,998 ✅	-0.87%	-4,772,520 ✅	-55.44%

---

Full diff report 👇

Program	ACIR opcodes (+/-)	%	Circuit size (+/-)	%
private_kernel_empty	1,893 (-26)	-1.35%	1,042,230 (+1,033,495)	+11831.65%
private_kernel_tail_to_public	73,499 (-904)	-1.22%	457,031 (+282,122)	+161.30%
private_kernel_tail	19,602 (+1,037)	+5.59%	537,715 (+283,782)	+111.75%
private_kernel_reset	108,030 (-912)	-0.84%	935,885 (+446,457)	+91.22%
private_kernel_reset_big	80,726 (-912)	-1.12%	503,637 (+223,001)	+79.46%
private_kernel_reset_medium	67,073 (-912)	-1.34%	287,512 (+111,273)	+63.14%
parity_base	347 (-2)	-0.57%	79,811 (+28,854)	+56.62%
private_kernel_reset_small	60,246 (-912)	-1.49%	179,553 (+55,409)	+44.63%
private_kernel_reset_tiny	56,834 (-912)	-1.58%	125,663 (+27,477)	+27.98%
private_kernel_init	28,972 (+351)	+1.23%	48,641 (+9,757)	+25.09%
private_kernel_init_simulated	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_inner_simulated	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_reset_simulated	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_reset_simulated_big	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_reset_simulated_medium	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_reset_simulated_small	1 (0)	0.00%	2,488 (+313)	+14.39%
private_kernel_reset_simulated_tiny	1 (0)	0.00%	2,488 (+313)	+14.39%
public_kernel_app_logic_simulated	1 (0)	0.00%	4,016 (+398)	+11.00%
public_kernel_setup_simulated	1 (0)	0.00%	4,016 (+398)	+11.00%
public_kernel_teardown_simulated	1 (0)	0.00%	4,016 (+398)	+11.00%
private_kernel_tail_to_public_simulated	1 (0)	0.00%	4,016 (+395)	+10.91%
private_kernel_inner	50,433 (+414)	+0.83%	71,395 (+4,444)	+6.64%
public_kernel_app_logic	287,730 (-6,726)	-2.28%	626,685 (+30,697)	+5.15%
public_kernel_setup	211,753 (-5,214)	-2.40%	1,609,990 (+33,568)	+2.13%
public_kernel_teardown	289,340 (-6,726)	-2.27%	1,689,212 (+32,050)	+1.93%
rollup_merge	2,850 (-2)	-0.07%	2,092,928 (-2,107)	-0.10%
parity_root	5,029 (-1)	-0.02%	4,173,282 (-5,884)	-0.14%
rollup_root	4,296 (-41)	-0.95%	3,145,771 (-33,971)	-1.07%
rollup_base_simulated	1 (0)	0.00%	33 (-1)	-2.94%
public_kernel_tail_simulated	1 (0)	0.00%	420 (-26)	-5.83%
private_kernel_empty_simulated	1 (0)	0.00%	420 (-29)	-6.46%
private_kernel_tail_simulated	1 (0)	0.00%	420 (-29)	-6.46%
empty_nested	0 (0)	+∞%	5 (-3)	-37.50%
empty_nested_simulated	1 (0)	0.00%	5 (-3)	-37.50%
public_kernel_tail	965,936 (-38,220)	-3.81%	4,651,312 (-4,621,768)	-49.84%
rollup_base	341,428 (-2,998)	-0.87%	3,836,417 (-4,772,520)	-55.44%

[AztecBot]

Benchmark results

Metrics with a significant change:

• app_circuit_witness_generation_time_in_ms (Token:transfer): 949 (-26%)
• protocol_circuit_simulation_time_in_ms (private-kernel-tail): 427 (-42%)
• protocol_circuit_output_size_in_bytes (private-kernel-init): 53,090 (+19%)
• protocol_circuit_output_size_in_bytes (private-kernel-inner): 53,266 (+19%)
• protocol_circuit_output_size_in_bytes (private-kernel-tail): 57,447 (+23%)
• protocol_circuit_output_size_in_bytes (public-kernel-setup): 80,246 (+22%)
• protocol_circuit_output_size_in_bytes (public-kernel-app-logic): 80,246 (+22%)
• protocol_circuit_output_size_in_bytes (private-kernel-reset-tiny): 52,961 (+19%)
• protocol_circuit_output_size_in_bytes (public-kernel-teardown): 80,246 (+22%)
• tx_size_in_bytes (0): 72,017 (+22%)
• avm_simulation_time_ms (Token:constructor): 125 (+35%)
• avm_simulation_time_ms (Token:assert_minter_and_mint): 54.7 (-40%)
• avm_simulation_time_ms (AuthRegistry:set_authorized): 43.9 (+389%)
• protocol_circuit_proving_time_in_ms (base-parity): 2,107 (+49%)
• protocol_circuit_num_public_inputs (public-kernel-setup): 4,027 (+17%)
• protocol_circuit_num_public_inputs (public-kernel-app-logic): 4,027 (+17%)
• protocol_circuit_num_public_inputs (public-kernel-teardown): 4,027 (+17%)

Detailed results

All benchmarks are run on txs on the Benchmarking contract on the repository. Each tx consists of a batch call to create_note and increment_balance, which guarantees that each tx has a private call, a nested private call, a public call, and a nested public call, as well as an emitted private note, an unencrypted log, and public storage read and write.

This benchmark source data is available in JSON format on S3 here.

Proof generation

Each column represents the number of threads used in proof generation.

Metric	1 threads	4 threads	16 threads	32 threads	64 threads
proof_construction_time_sha256_ms	5,748 (+1%)	1,554 (+1%)	705	748 (-1%)	768
proof_construction_time_sha256_30_ms	11,776 (+1%)	3,156 (+1%)	1,408	1,442	1,468
proof_construction_time_sha256_100_ms	43,986 (+1%)	12,394 (+1%)	5,643 (-1%)	5,569	5,491 (-1%)
proof_construction_time_poseidon_hash_ms	78.0	34.0	34.0	58.0	88.0 (-1%)
proof_construction_time_poseidon_hash_30_ms	1,526 (+1%)	420 (+1%)	201 (+1%)	222 (+2%)	268 (+1%)
proof_construction_time_poseidon_hash_100_ms	5,652 (+1%)	1,530 (+1%)	675 (+1%)	740	746

L2 block published to L1

Each column represents the number of txs on an L2 block published to L1.

Metric	4 txs	8 txs	16 txs
l1_rollup_calldata_size_in_bytes	708	708	708
l1_rollup_calldata_gas	6,576	6,590	6,600
l1_rollup_execution_gas	611,418	611,583	611,744
l2_block_processing_time_in_ms	734 (-5%)	1,440 (+1%)	2,709 (-1%)
l2_block_building_time_in_ms	10,474 (+4%)	21,082 (+7%)	41,426 (+6%)
l2_block_rollup_simulation_time_in_ms	10,474 (+4%)	21,081 (+7%)	41,425 (+6%)
l2_block_public_tx_process_time_in_ms	8,747 (+4%)	19,100 (+7%)	39,294 (+6%)

L2 chain processing

Each column represents the number of blocks on the L2 chain where each block has 8 txs.

Metric	3 blocks	5 blocks
node_history_sync_time_in_ms	7,181 (+2%)	10,069 (+2%)
node_database_size_in_bytes	12,714,064	16,904,272
pxe_database_size_in_bytes	16,254	26,813

Circuits stats

Stats on running time and I/O sizes collected for every kernel circuit run across all benchmarks.

Circuit	simulation_time_in_ms	witness_generation_time_in_ms	input_size_in_bytes	output_size_in_bytes	proving_time_in_ms	proof_size_in_bytes	num_public_inputs	size_in_gates
private-kernel-init	97.9 (-8%)	405	21,798	⚠️ 53,090 (+19%)	N/A	N/A	N/A	N/A
private-kernel-inner	179 (+3%)	705	80,891 (+12%)	⚠️ 53,266 (+19%)	N/A	N/A	N/A	N/A
private-kernel-tail	⚠️ 427 (-42%)	865 (-9%)	61,159 (+15%)	⚠️ 57,447 (+23%)	N/A	N/A	N/A	N/A
base-parity	6.42 (-2%)	672 (+6%)	160	96.0	⚠️ 2,107 (+49%)	13,188	19.0	131,072
root-parity	113 (+1%)	121 (-2%)	69,084	96.0	30,808 (-4%)	13,188	19.0	4,194,304
base-rollup	3,385 (+5%)	4,909 (-2%)	182,192	632	44,228 (-1%)	13,988	44.0	4,194,304
root-rollup	157 (+1%)	120 (-9%)	54,461	684	28,276 (-3%)	13,956	43.0	4,194,304
public-kernel-setup	98.1 (+13%)	2,685 (-2%)	112,985 (+15%)	⚠️ 80,246 (+22%)	18,086 (-3%)	141,444 (+15%)	⚠️ 4,027 (+17%)	2,097,152
public-kernel-app-logic	114 (+14%)	4,042 (+1%)	112,985 (+15%)	⚠️ 80,246 (+22%)	11,397 (+1%)	141,444 (+15%)	⚠️ 4,027 (+17%)	1,048,576
public-kernel-tail	636 (+2%)	26,889 (+3%)	410,726 (+4%)	10,814	67,928 (+1%)	26,372	431	8,388,608
private-kernel-reset-tiny	240 (+5%)	877 (-3%)	76,585 (+12%)	⚠️ 52,961 (+19%)	N/A	N/A	N/A	N/A
private-kernel-tail-to-public	6,187 (+14%)	1,556 (-5%)	888,733 (-3%)	1,697	N/A	N/A	N/A	N/A
public-kernel-teardown	92.5 (+12%)	3,927 (-4%)	112,985 (+15%)	⚠️ 80,246 (+22%)	20,489 (+4%)	141,444 (+15%)	⚠️ 4,027 (+17%)	2,097,152
merge-rollup	62.1 (+3%)	N/A	35,678	632	N/A	N/A	N/A	N/A
undefined	N/A	N/A	N/A	N/A	154,012 (-1%)	N/A	N/A	N/A

Stats on running time collected for app circuits

Function	input_size_in_bytes	output_size_in_bytes	witness_generation_time_in_ms	proof_size_in_bytes	proving_time_in_ms
ContractClassRegisterer:register	1,312	11,699	346 (-1%)	N/A	N/A
ContractInstanceDeployer:deploy	1,376	11,699	27.5 (-1%)	N/A	N/A
MultiCallEntrypoint:entrypoint	1,888	11,699	604 (-1%)	N/A	N/A
GasToken:deploy	1,344	11,699	438 (-1%)	N/A	N/A
SchnorrAccount:constructor	1,280	11,699	425 (-1%)	N/A	N/A
SchnorrAccount:entrypoint	2,272	11,699	804 (-2%)	N/A	N/A
Token:privately_mint_private_note	1,248	11,699	492 (-2%)	N/A	N/A
FPC:fee_entrypoint_public	1,312	11,699	83.4 (-8%)	N/A	N/A
Token:transfer	1,280	11,699	⚠️ 949 (-26%)	N/A	N/A
AuthRegistry:set_authorized (avm)	18,427	N/A	N/A	102,048	2,034 (-2%)
FPC:prepare_fee (avm)	22,894	N/A	N/A	102,112	2,329 (+2%)
Token:transfer_public (avm)	46,817	N/A	N/A	102,112	6,718 (+3%)
AuthRegistry:consume (avm)	26,670	N/A	N/A	102,080	2,644
FPC:pay_refund (avm)	26,163	N/A	N/A	102,080	3,676 (-1%)
Benchmarking:create_note	1,312	11,699	429 (+2%)	N/A	N/A
SchnorrAccount:verify_private_authwit	1,248	11,699	45.6	N/A	N/A
Token:unshield	1,344	11,699	1,088 (-1%)	N/A	N/A
FPC:fee_entrypoint_private	1,344	11,699	1,404	N/A	N/A

AVM Simulation

Time to simulate various public functions in the AVM.

Function	time_ms	bytecode_size_in_bytes
GasToken:_increase_public_balance	95.4	8,139
GasToken:set_portal	12.4 (-27%)	2,362
Token:constructor	⚠️ 125 (+35%)	16,400
FPC:constructor	92.0	9,304
GasToken:mint_public	82.7	6,150
Token:mint_public	68.7 (+12%)	11,720
Token:assert_minter_and_mint	⚠️ 54.7 (-40%)	8,028
AuthRegistry:set_authorized	⚠️ 43.9 (+389%)	4,537
FPC:prepare_fee	243 (-9%)	8,812
Token:transfer_public	49.4 (+2%)	32,641
FPC:pay_refund	68.2 (+2%)	12,114
Benchmarking:increment_balance	1,055 (+7%)	7,450
Token:_increase_public_balance	12.4	8,960
FPC:pay_refund_with_shielded_rebate	147 (+2%)	12,663

Public DB Access

Time to access various public DBs.

Function	time_ms
get-nullifier-index	0.159 (-2%)

Tree insertion stats

The duration to insert a fixed batch of leaves into each tree type.

Metric	1 leaves	16 leaves	64 leaves	128 leaves	256 leaves	512 leaves	1024 leaves
batch_insert_into_append_only_tree_16_depth_ms	10.4 (+1%)	16.8 (+1%)	N/A	N/A	N/A	N/A	N/A
batch_insert_into_append_only_tree_16_depth_hash_count	16.8	31.7	N/A	N/A	N/A	N/A	N/A
batch_insert_into_append_only_tree_16_depth_hash_ms	0.599	0.517 (+1%)	N/A	N/A	N/A	N/A	N/A
batch_insert_into_append_only_tree_32_depth_ms	N/A	N/A	48.1	76.6 (+1%)	127 (-4%)	250 (+2%)	484 (+2%)
batch_insert_into_append_only_tree_32_depth_hash_count	N/A	N/A	95.9	159	287	543	1,055
batch_insert_into_append_only_tree_32_depth_hash_ms	N/A	N/A	0.491	0.470 (+1%)	0.439 (-3%)	0.452 (+2%)	0.451 (+1%)
batch_insert_into_indexed_tree_20_depth_ms	N/A	N/A	59.4	112	177 (-4%)	359 (+2%)	700
batch_insert_into_indexed_tree_20_depth_hash_count	N/A	N/A	109	207	355	691	1,363
batch_insert_into_indexed_tree_20_depth_hash_ms	N/A	N/A	0.503	0.503	0.471 (-3%)	0.486 (+2%)	0.479
batch_insert_into_indexed_tree_40_depth_ms	N/A	N/A	73.3 (+1%)	N/A	N/A	N/A	N/A
batch_insert_into_indexed_tree_40_depth_hash_count	N/A	N/A	133	N/A	N/A	N/A	N/A
batch_insert_into_indexed_tree_40_depth_hash_ms	N/A	N/A	0.521 (+1%)	N/A	N/A	N/A	N/A

Miscellaneous

Transaction sizes based on how many contract classes are registered in the tx.

Metric	0 registered classes	1 registered classes
tx_size_in_bytes	⚠️ 72,017 (+22%)	666,910 (+1%)

Transaction size based on fee payment method

| Metric | |
| - | |

[benesjan]

[benesjan]

It's quite cool that in the recursive case we can afford to have a larger amount of notes which will probably result in the notes being consolidated for future cases as well --> so user will be less likely to fall into the recursive case soon.

In the future it might make sense to try make note getter return as many notes as possible such that it sums at least to the target amount.

[nventuro]

There's some discussion about this in #7731 - consuming more notes results in larger DA costs, but consuming only the largest notes can lead to excessive change notes being created.