docs: expand fungible asset secondary store documentation

[gregnazario]

Summary

Expands the Managing Stores (Advanced) section of the Fungible Asset (FA) Standard docs with dedicated, thorough coverage of secondary FungibleStores. Details were sourced from the aptos-core framework at aptos-move/framework/aptos-framework/sources/fungible_asset.move (and primary_fungible_store.move) to keep struct definitions, function signatures, and behavior accurate.

What changed

• Added the FungibleStore struct definition and clarified that primary and secondary stores are the same underlying resource, differing only in how the Object is created/addressed.
• Added a Primary vs. secondary stores comparison table (addressing, count per owner, creation, deletability, typical owner/use).
• Documented concrete secondary store use cases (liquidity pools, escrow/vesting, marketplace/staking custody).
• Added an ownership caveats callout: secondary stores can be controlled by their creators (including transferring the Object to a new owner), while primary stores keep the same owner in perpetuity. Recommends primary stores as the default, and advises exchanges/indexers to rely only on primary stores.
• Creating a secondary store: added a full contract-owned example that creates a deletable Object, calls fungible_asset::create_store, and retains an ExtendRef so the contract can act as the store owner.
• Interacting with a secondary store: documented withdraw/deposit/transfer by passing the Object<FungibleStore> directly, an example that generates the owner signer from a stored ExtendRef, and a caution to prefer dispatchable_fungible_asset::* for assets with dispatch hooks.
• Inspecting a store: documented the store_exists, store_metadata, balance, and is_frozen view functions.
• Deleting a secondary store: documented remove_store (requires a DeleteRef, aborts with EBALANCE_IS_NOT_ZERO unless empty) and the emitted FungibleStoreDeletion event.
• Mirrored all of the above into the Chinese translation (zh/).

Testing

• pnpm lint — passes (Biome + Prettier).
• pnpm test tests/agent-discovery.test.ts tests/markdown-negotiation.test.ts — 42 tests pass.
• Content formatted via Prettier.

Notes

• Docs-only change; no agent-discovery endpoints, middleware, or well-known files were touched.
• The pre-push hook (astro check --noSync) reports 48 pre-existing TypeScript errors in unrelated files (e.g. src/utils/groupPagesByLang.ts) that also exist on main; the push bypassed the hook since this change only edits MDX content.

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aptos-docs	Ready	Preview, Comment	Jul 16, 2026 5:39pm