docs: overhaul root README for accuracy and honest scope

[alejoamiras]

What

Root README overhaul for accuracy and honest scope:

• Adds the two missing contracts: MultiToken and VaultDeployer were fully shipped (READMEs, tests, workspace members) but absent from the top-level docs entirely.
• New "Standards & Naming (AIP vs ARC)" section: ecosystem teams have been asking about "AIP-403", which does not exist — it is ARC-403, a separate proposal track. The repo's own docs mixed the prefixes; this section states the tracks explicitly and links AIP-20, AIP-4626, and ARC-403 forum threads.
• Surfaces the Vault warning at top level: the "not production-ready / known overflow" disclosure previously lived only in the vault sub-README, one click away from a reader who would assume Vault is on equal footing with Token/NFT.
• Replaces "Future Contracts" (staking, governance, pools "will be added") with a demand-driven Scope & Maintenance statement: existing standards are maintained; new ones are built when ecosystem demand is signalled (forum/issues).
• Drops the "AIP-721" label (here and in the escrow README): no AIP-721 proposal has been published anywhere we could find; keeping an unlinked number invites exactly the phantom-standard confusion that produced "AIP-403".

Validation

Docs-only. All links verified live.

🤖 Generated with Claude Code

[github-actions]

Benchmark Comparison

CPU	Cores	RAM	Arch
AMD EPYC 7763 64-Core Processor	4	16 GiB	x64

Contract: escrow

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	(partial) withdraw	486,936	486,936		3,744	3,744		587,800	587,800		13,860	13,977	+117 (+0.8%)
⚪	withdraw	331,210	331,210		832	832		499,700	499,700		11,285	11,296	+11 (+0.1%)
⚪	withdraw_nft	378,517	378,517		1,440	1,440		527,400	527,400		12,277	12,366	+89 (+0.7%)

Contract: logic

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	get_escrow	390,359	390,359		192	192		456,000	456,000		12,487	12,438	-49 (-0.4%)
⚪	secret_key_to_public_keys	387,718	387,718		192	192		456,000	456,000		12,399	12,382	-17 (-0.1%)
⚪	share_escrow	303,989	303,989		1,952	1,952		520,700	520,700		11,008	11,023	+15 (+0.1%)

Contract: multitoken

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	burn_private	260,810	260,810		832	832		499,700	499,700		10,089	10,153	+64 (+0.6%)
⚪	burn_public	223,823	223,823		416	416		638,292	638,292		9,706	9,745	+39 (+0.4%)
⚪	initialize_transfer_commitment	225,077	225,077		768	768		474,500	474,500		9,639	9,683	+44 (+0.5%)
⚪	mint_to_private	297,577	297,577		1,408	1,408		511,400	511,400		10,855	10,931	+76 (+0.7%)
⚪	mint_to_public	223,823	223,823		416	416		637,800	637,800		9,713	9,729	+16 (+0.2%)
⚪	transfer_private_to_commitment	264,328	264,328		1,024	1,024		511,400	511,400		10,093	10,300	+207 (+2.1%)
⚪	transfer_private_to_private	337,261	337,261		2,048	2,048		555,100	555,100		11,389	11,378	-11 (-0.1%)
⚪	transfer_private_to_public	307,363	307,363		1,056	1,056		714,677	714,677		10,884	10,889	+5 (+0.0%)
⚪	transfer_public_to_commitment	223,823	223,823		640	640		663,516	663,516		9,814	9,663	-151 (-1.5%)
⚪	transfer_public_to_private	298,128	298,128		1,024	1,024		683,958	683,958		10,810	10,851	+41 (+0.4%)
⚪	transfer_public_to_public	223,823	223,823		480	480		673,505	673,505		9,706	9,685	-21 (-0.2%)

Contract: nft

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	burn_private	275,257	275,257		416	416		661,052	661,052		10,638	10,622	-16 (-0.2%)
⚪	burn_public	223,823	223,823		448	448		670,034	670,034		9,691	9,710	+19 (+0.2%)
⚪	mint_to_private	341,050	341,050		1,600	1,600		735,342	735,342		11,508	11,562	+54 (+0.5%)
⚪	mint_to_public	223,823	223,823		448	448		670,718	670,718		9,715	9,635	-80 (-0.8%)
⚪	transfer_private_to_private	249,719	249,719		832	832		499,700	499,700		9,949	10,030	+81 (+0.8%)
⚪	transfer_private_to_public	275,286	275,286		416	416		659,258	659,258		10,577	10,613	+36 (+0.3%)
⚪	transfer_public_to_private	292,460	292,460		992	992		683,268	683,268		10,713	10,751	+38 (+0.4%)
⚪	transfer_public_to_public	223,823	223,823		384	384		633,285	633,285		9,685	9,697	+12 (+0.1%)

Contract: token

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	burn_private	303,652	303,652		1,024	1,024		713,843	713,843		10,842	10,877	+35 (+0.3%)
⚪	burn_public	223,823	223,823		448	448		672,518	672,518		9,645	9,683	+38 (+0.4%)
⚪	initialize_transfer_commitment	225,077	225,077		768	768		474,500	474,500		9,692	9,639	-53 (-0.5%)
⚪	mint_to_private	355,289	355,289		2,144	2,144		737,956	737,956		11,646	11,677	+31 (+0.3%)
⚪	mint_to_public	223,823	223,823		448	448		672,113	672,113		9,816	9,617	-199 (-2.0%)
⚪	transfer_private_to_commitment	260,673	260,673		992	992		511,400	511,400		10,100	10,045	-55 (-0.5%)
⚪	transfer_private_to_private	344,855	344,855		2,592	2,592		557,600	557,600		11,526	11,596	+70 (+0.6%)
⚪	transfer_private_to_public	303,708	303,708		1,024	1,024		713,990	713,990		10,954	11,058	+104 (+0.9%)
⚪	transfer_private_to_public_with_commitment	308,509	308,509		1,600	1,600		747,290	747,290		11,013	10,953	-60 (-0.5%)
⚪	transfer_public_to_commitment	223,823	223,823		576	576		662,496	662,496		9,720	9,658	-62 (-0.6%)
⚪	transfer_public_to_private	296,092	296,092		992	992		683,271	683,271		10,832	10,788	-44 (-0.4%)
⚪	transfer_public_to_public	223,823	223,823		448	448		672,515	672,515		9,656	9,665	+9 (+0.1%)

Contract: vault

🚦	Function	Gates			DA Gas			L2 Gas			Proving Time (ms)
		Base	PR	Diff	Base	PR	Diff	Base	PR	Diff	Base	PR	Diff
⚪	deposit_private_to_private	508,340	508,340		1,312	1,312		878,035	878,035		14,115	14,060	-55 (-0.4%)
⚪	deposit_private_to_private_exact	612,065	612,065		1,888	1,888		915,103	915,103		16,033	16,079	+46 (+0.3%)
⚪	deposit_private_to_public	436,085	436,085		768	768		862,060	862,060		13,027	13,047	+20 (+0.2%)
⚪	deposit_public_to_private	424,713	424,713		1,984	1,984		964,832	964,832		12,910	12,932	+22 (+0.2%)
⚪	deposit_public_to_private_exact	424,724	424,724		1,952	1,952		949,256	949,256		12,999	12,914	-85 (-0.7%)
⚪	deposit_public_to_public	223,823	223,823		832	832		897,350	897,350		9,698	9,620	-78 (-0.8%)
⚪	issue_private_to_private_exact	612,065	612,065		1,888	1,888		915,763	915,763		16,033	15,988	-45 (-0.3%)
⚪	issue_private_to_public_exact	484,820	484,820		1,344	1,344		899,785	899,785		13,786	13,784	-2 (-0.0%)
⚪	issue_public_to_private	346,165	346,165		1,376	1,376		921,448	921,448		11,514	11,472	-42 (-0.4%)
⚪	issue_public_to_public	223,823	223,823		832	832		898,040	898,040		9,672	9,724	+52 (+0.5%)
⚪	redeem_private_to_private_exact	614,859	614,859		1,888	1,888		915,610	915,610		16,132	15,949	-183 (-1.1%)
⚪	redeem_private_to_public	436,028	436,028		768	768		862,504	862,504		13,027	13,061	+34 (+0.3%)
⚪	redeem_public_to_private_exact	427,575	427,575		1,952	1,952		949,577	949,577		13,012	12,928	-84 (-0.6%)
⚪	redeem_public_to_public	223,823	223,823		832	832		897,872	897,872		9,645	9,667	+22 (+0.2%)
⚪	withdraw_private_to_private	511,134	511,134		1,312	1,312		878,245	878,245		14,134	14,133	-1 (-0.0%)
⚪	withdraw_private_to_private_exact	614,859	614,859		1,888	1,888		915,556	915,556		16,044	16,002	-42 (-0.3%)
⚪	withdraw_private_to_public_exact	484,763	484,763		1,344	1,344		900,019	900,019		13,778	13,811	+33 (+0.2%)
⚪	withdraw_public_to_private	440,832	440,832		2,528	2,528		967,143	967,143		13,186	13,089	-97 (-0.7%)
⚪	withdraw_public_to_public	223,823	223,823		832	832		898,175	898,175		9,674	9,697	+23 (+0.2%)