fix(contracts): move per-token bookkeeping to persistent storage

[Darkdante9]

Summary

Every piece of per-token state — TokenInfo(index), the CreatorTokens(Address) list, TokenIndex(Address), Metadata(Address), the per-token owner/supply keys, and whitelist entries — lived in env.storage().instance(), a single ledger entry shared with the contract instance itself. That entry is capped at ~64 KiB and is loaded/reserialized in full on every invocation, so as token_count grew:

1. Every state-writing call (create_token, set_metadata, even pause) would eventually fail once cumulative instance data approached the entry-size limit, with no admin recovery path — the factory would be permanently bricked.
2. Every invocation would pay read/write fees proportional to the entire instance entry, so create_token would get progressively more expensive for everyone as unrelated tokens accumulated.
3. A single TTL/archival event would take down all bookkeeping at once.

This PR moves per-token bookkeeping to Soroban persistent storage, keyed per-entry, so instance storage stays O(1) in token_count.

Changes

• Storage split: TokenInfo, TokenIndex, Metadata, the per-token owner/supply/bkfld keys, and whitelist entries now live in persistent storage. Only FactoryState and the (already-bounded, ≤10-recipient) fee split remain in instance storage.
• Paginated creator lists: the monolithic CreatorTokens(Address) -> Vec<u32> is replaced with CreatorTokens(Address, page) buckets of ≤ MAX_TOKENS_BY_CREATOR_PAGE (50) indices each, plus a CreatorTokenCount(Address) counter, so no single entry grows unboundedly as a creator registers more tokens. get_tokens_by_creator was rewritten to walk across page boundaries.
• TTL per key: every persistent read/write goes through helpers (set_persistent, migrate_addr_keyed, read_addr_keyed) that extend that specific key's TTL on access, rather than one shared instance TTL.
• Migration (CURRENT_SCHEMA_VERSION 2 → 3):
  • TokenInfo's key space (1..=token_count) is the only migrated key space that's cheaply enumerable, so migrate's new v3 step walks it in bounded, resumable chunks (20 per call, tracked via an on-chain cursor) — safe to call repeatedly if token_count is too large to finish in one invocation's budget. schema_version only advances to 3 once the walk completes.
  • Every other migrated key (TokenIndex, Metadata, owner, supply, bkfld) is address-keyed, not enumerable, so it migrates lazily on first mutating access instead (checks persistent first, falls back to the legacy instance copy, and moves it over as a side effect). Pure view entrypoints (get_token_info, get_metadata, etc.) use the same fallback but never write, so simulated read calls stay free of a write footprint.
  • CreatorTokens migrates lazily per-creator the first time a page is next appended to, since creator addresses aren't enumerable from factory state either.
  • Whitelist entries need no migration mechanism at all — they're already address-scoped by the caller (add_to_whitelist/remove_from_whitelist take the address directly), so writes go straight to persistent and reads fall back to instance for any pre-migration entry.
  • Both the chunked and lazy paths are idempotent and safe in any order/interleaving.
• Stress test: test_instance_storage_size_stays_flat_under_load seeds 300 tokens for one creator (spanning 6 CreatorTokens pages) and asserts (a) the instance-stored FactoryState entry's exact serialized XDR size is unchanged, (b) sampled TokenInfo entries live in persistent storage, not instance, (c) the legacy monolithic CreatorTokens key is absent for a post-migration creator, and (d) get_tokens_by_creator returns correct, contiguous results across a page boundary.
• Docs: added a "Storage architecture" section to docs/contract-abi.md (storage-backend table, TTL behavior, migration mechanics) and updated the README's schema-versioning table and factory-pattern description.

Also fixed (pre-existing, compile-blocking)

Found while starting this work: set_fee_split had a merge-conflict artifact — two overlapping cap checks with a dangling brace and unreachable code — that made the crate fail to compile outright on main. It also left a duplicate MAX_FEE_SPLIT_RECIPIENTS constant (10 vs. 20) and a duplicate error discriminant (TooManyFeeSplitRecipients and AlreadyBackfilled both = 18). Fixed by keeping the single documented cap check, removing the duplicate constant (kept at 10, matching the existing test suite's assumption), and renumbering TooManyFeeSplitRecipients to 19. This was a prerequisite — without it nothing in the crate builds or tests — and is called out in docs/contract-abi.md's error table.

Test plan

• cargo test -p token-factory — 120/120 pass (119 pre-existing + the new stress test)
• cargo clippy -p token-factory --all-targets (and --features bench) — clean (only pre-existing, unrelated warnings)
• cargo build -p token-factory --release --target wasm32v1-none — release WASM builds successfully
• Verified via a scratch revert that the compile-blocking set_fee_split bug and the bench-suite deploy failures (dummy zero WASM hash, no real WASM registered) are pre-existing on main/unrelated to this change — the bench job is already non-blocking (continue-on-error: true) in CI
• npm test (frontend, 585 tests) — untouched by this PR, ran clean via the pre-push hook

Closes #1007

[github-actions]

🎉 This PR is included in version 1.3.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀