Skip to content

Stellar: adapt token, votes and access control docs to latest stellar-contracts - #245

Draft
brozorec wants to merge 5 commits into
docs/stellar-confidential-tokenfrom
docs/stellar-token-breaking-changes
Draft

brozorec wants to merge 5 commits into
docs/stellar-confidential-tokenfrom
docs/stellar-token-breaking-changes

Conversation

@brozorec

@brozorec brozorec commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Adapts the Stellar docs to the changes on stellar-contracts main (checked at d075db5), mainly #821, #795, #879, #881, #885, #911 and #913 (plus #748 for the RWA compliance hooks and #928 for the error codes).

Stacked on #244. Retarget to main once that PR is merged.

Commits:

  1. Fungible and Non-Fungible pages.
  2. The other pages that were still on the old API: Votes, Access Control, RWA and Vault.
  3. Align RWA, vault and SAC admin docs with latest stellar-contracts.
  4. Align governance, access, utils and fee abstraction docs with latest stellar-contracts.
  5. Align the error code conventions with the upstream allocation (#928).

Breaking changes covered

Both token modules

  • ContractType is now selected uniformly with Compose<(...)>, e.g. Compose<(Base,)> or Compose<(AllowList, TotalSupply)>. Combinations are only reachable through it. The docs list the valid combinations, which are checked at compile time.
  • Minting goes through the contract type, <Self as XToken>::ContractType::mint*, instead of Base::mint / Enumerable::... / Consecutive::.... A callout explains why calling a primitive directly is unsafe.

Fungible

  • total_supply is no longer part of FungibleToken. It is now the opt-in TotalSupply contract type plus the FungibleTotalSupply trait (new section).
  • Capped is now a contract type (Compose<(Capped, TotalSupply)>) with a FungibleCapped trait exposing cap(). It used to be helper functions only.
  • AllowList and BlockList can now be combined. Votes also moves voting units on mint, and it can't be combined with TotalSupply / Capped.

Non-Fungible

  • sequential_mint(to) → mint(to), the old mint(to, id) → mint_with_id(to, id), and batch_mint → mint_range. A table shows which contract types support each one.
  • sequential_burn is removed. The Enumerable and Consecutive examples now use NonFungibleBurnable.
  • Royalty setters go through Self::ContractType::set_token_royalty / remove_token_royalty, which makes them work with Consecutive. Added an example.
  • NonFungibleVotes can be combined with Enumerable or Consecutive.
  • Fixed the broken Consecutive source link (non-fungible → non_fungible).

Votes (governance/votes.mdx)

  • The Callout uses Compose<(FungibleVotes,)> and notes that minting must go through the contract type for voting units to be tracked. The bare FungibleVotes still compiled, so this aligns the page with the documented form rather than fixing a compile error.

Access Control (access/access-control.mdx)

  • The NFT Base::mint(e, &to, token_id) no longer exists with that signature. The example now uses ContractType::mint_with_id with Compose<(Base,)>.
  • Both examples are now complete contracts. The usage example was missing imports and the NonFungibleToken impl, and the role-hierarchy example imported AccessControl without implementing it.

RWA (tokens/rwa/rwa.mdx)

  • RWAToken now requires FungibleTotalSupply. The example uses Compose<(RWA, TotalSupply)>, implements FungibleTotalSupply, and mints through the contract type. It also mentions Compose<(RWA, Capped, TotalSupply)>.
  • Compliance hooks: can_transfer / can_create are gone (#748). transferred / created / destroyed now run after the operation, reject by panicking, and receive AccountSnapshots plus a TransferKind. I updated the interface list, the hook descriptions, the ComplianceModule trait, both diagrams and the security callout.
  • Pre-existing errors fixed along the way:
    • The example never implemented Pausable or the 15 RWAToken functions that have no default body. It now does, with #[only_role(operator, "manager")].
    • The RWA::* helper snippets passed an operator argument these helpers don't take.
    • The sequence diagram used a non-existent is_verified; it's now verify_identity.
  • Fixed 5 source links that broke when the identity modules moved under rwa/identity_verification/. Also replaced 2 stale #L line anchors with plain file links.

Vault (tokens/vault/vault.mdx)

  • FungibleVault now requires FungibleTotalSupply. The example uses Compose<(Vault, TotalSupply)> and implements FungibleTotalSupply. It also mentions Compose<(Vault, Capped, TotalSupply)>.
  • The example's deposit / withdraw overrides called operator.require_auth() before Vault::deposit / Vault::withdraw, which already require it. The example now uses the default FungibleVault functions. The custom-authorization snippet drops the duplicate auth and goes through Self::ContractType::deposit, so a capped vault still checks the cap.

Error codes (index.mdx)

  • #928 moved GovernorError from 5000–5023 (which collided with Fee Abstraction) to 4200–4223, and ComplianceModuleError from 401–407 (which collided with Vault) to 383–389. No page cites any of those codes, and the overview already placed Governance in 4XXX, so the code now matches the docs.
  • The overview now lists the governance blocks (Timelock 40XX, Votes 41XX, Governor 42XX). It drops Upgradeable 11XX, since the Upgradeable module has no error enum (removed in #585). It also mentions the reserved 39XX block and that codes below 100 are left to contract-specific errors.
  • Every error code cited across the Stellar docs (29 citations) matches main at d075db5.

Verification

  • Every full contract snippet on the 8 Fungible, Non-Fungible, Votes, Access Control, RWA and Vault pages was extracted into its own crate inside the stellar-contracts workspace (on main at d075db5) and passed cargo check with no errors or warnings. The partial snippets were checked as combined contracts: the Total Supply section, the Votes callout and the vault custom-authorization override. Synthetic capped RWA and capped vault variants were checked the same way.
  • Negative control: the previous fungible, Enumerable, Access Control, RWA and Vault snippets fail to compile against main.
  • All 8 pages compile with the site's MDX + GFM pipeline.

…acts

- Select the contract type with Compose<(...)> and document the valid
  combinations for fungible and non-fungible tokens
- Document minting through Self::ContractType (fungible mint, NFT mint,
  mint_with_id and mint_range) instead of calling Base primitives
- Add the opt-in Total Supply extension and rework Capped as a contract
  type exposing FungibleCapped
- Route NFT royalty setters through the contract type
- Fix the consecutive source link
…ellar-contracts

- Votes: select FungibleVotes through Compose and note that minting must
  go through the contract type.
- Access Control: mint through ContractType::mint_with_id and make both
  examples complete contracts.
- RWA: use Compose<(RWA, TotalSupply)> with FungibleTotalSupply, implement
  Pausable and the required RWAToken functions, mint through the contract
  type, drop the operator argument from the RWA helpers, describe the
  snapshot-based compliance hooks (no more can_transfer/can_create), and
  fix the moved identity verification source links.
- Vault: use Compose<(Vault, TotalSupply)> with FungibleTotalSupply, rely
  on the default FungibleVault functions (which already require operator
  auth), and mention the capped variant.
@brozorec brozorec changed the title Stellar: adapt fungible and non-fungible docs to latest stellar-contracts Stellar: adapt token, votes and access control docs to latest stellar-contracts Oct 6, 2026
@brozorec
brozorec requested a review from ozgunozerk October 6, 2026 13:48
@brozorec brozorec self-assigned this Oct 6, 2026
…racts

- RWA: describe forced transfers accurately (only `to` is verified, pause
  and freezing are bypassed), document custodial (muxed) destinations and
  how to refuse them, batch operations and their sizing, per-token
  recovery including frozen zero-balance accounts, burn behaviour with
  frozen and locked tokens, and the identity registry removal and
  tombstoning rules. List the ready-made compliance modules with the hooks
  they need and their preset phase, replace the non-existent investor
  count module in the diagram, fix the verify_identity signature and the
  token binder capacity (100 tokens in a single entry).
- Vault: deposits that would mint zero shares now revert with
  VaultZeroShares and redemptions that would return zero assets with
  VaultZeroAssets; rewrite the inflation attack section after the upstream
  analysis, which no longer claims the offset makes the attack infeasible.
- SAC Admin Generic: import CustomAccountInterface from soroban_sdk::auth,
  add the missing stellar_tokens import and the ensure_minting_limit helper.
- Overview: fix the Vault description copied from the fungible token.
…h latest stellar-contracts

- Timelock Controller: add the missing auth_contexts/context_meta length
  check to the __check_auth example (without it, anyone could authorize
  arbitrary calls as the timelock), and rewrite the example around the
  Timelock trait and TimelockClient.
- Governor: implement Governor with #[contractimpl(contracttrait)] so the
  default methods are exported, add a constructor, document the non-zero
  voting period (InvalidVotingPeriod), the derived vs stored states and
  that the governor does not enforce the queue eta.
- Ownable: implement the Ownable trait in the examples, remove the
  duplicate owner auth in finalize_and_lock, fix the missing BytesN import
  and replace the deprecated update_current_contract_wasm.
- Pausable and Upgradeable: complete the examples (imports, access control
  on migrate, owner-gated Upgrader) and link the upstream examples. Use
  #[...] headings for the macros, also in Access Control.
- WAD: rename pow to powi, document ln, exp and powf, the operator
  overflow bounds and InvalidBase, and use the checked methods in the
  examples, which panicked on realistic inputs.
- Add a Fixed-Point Math page for the i128/I256 mul_div functions,
  Rounding and phantom overflow handling.
- Crypto and Merkle Distributor: fix the crate path, the broken source
  link and the non-compiling leaf clone, set the root in the constructor,
  and document Grumpkin, verify_with_index,
  verify_with_index_and_set_claimed, errors and events.
- Fee Abstraction: fix collect_fee_and_invoke, describe the current Eager
  (pull max, pay fee, refund) and Lazy (inline approval) flows and the
  balance-conserving token requirement, the allowlist behaviour, and
  point the relayer links to 1.5.x.
- Overview: list the WAD, Fixed-Point Math and Merkle Distributor pages.
- List the governance blocks (Timelock 40XX, Votes 41XX, Governor 42XX),
  now that GovernorError moved from 5000-5023 to 4200-4223 (#928).
- Drop Upgradeable 11XX: the Upgradeable module has no error enum.
- Mention the reserved 39XX block and that codes below 100 are left to
  contract-specific errors.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant