uniform contract type composition via Compose

[ozgunozerk]

The ContractType on FungibleToken and NonFungibleToken is now selected uniformly with the type-level Compose alias, by listing the contract types that override the Base behavior (e.g. Compose<(AllowList,)>). Invalid lists are rejected at compile time with a curated diagnostic. Additive extensions (burnable, capped, royalties) have no contract type and never appear in the list.

Also fixes the contract type bullet lists on both base traits: adds the missing Vault, FungibleVotes and NonFungibleVotes entries, and removes the incorrect claims that Enumerable/Consecutive are incompatible with NonFungibleBurnable.

Fixes #560

PR Checklist

• Tests
• Documentation

Summary by CodeRabbit

• New Features

  • Added a public composition helper for selecting supported fungible- and non-fungible-token behaviors.
  • Improved compile-time diagnostics for unsupported or conflicting token extension combinations.
  • Updated token examples to use the new composition approach consistently.

• Documentation

  • Expanded guidance and examples for selecting and combining token behaviors.
  • Clarified extension precedence and mutually exclusive combinations.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cab39713-9373-4198-83be-ca5fdbbf14f8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Changes

Compose contract-type selection

Layer / File(s)	Summary
Fungible Compose mappings packages/tokens/src/fungible/...	Adds Compose and Composable mappings for supported fungible contract types and updates related documentation.
Non-fungible Compose mappings packages/tokens/src/non_fungible/...	Adds corresponding non-fungible mappings, exports, diagnostics, and documentation.
Fungible example migration examples/fungible-*/..., examples/rwa/...	Changes fungible examples to use Compose<(...)>.
Non-fungible example migration examples/nft-*/...	Changes NFT examples to use Compose<(...)>.
Architecture examples Architecture.md	Updates documented ContractType selection patterns and explains overriding versus additive extensions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• OpenZeppelin/stellar-contracts#552: Added the fungible votes example whose ContractType is migrated here.
• OpenZeppelin/stellar-contracts#795: Updates the same Compose-based ContractType wiring patterns.

Suggested reviewers: brozorec

Poem

A rabbit arranged the types in a row,
With Compose wrapped neatly below.
Base, votes, and lists unite,
Compile-time paths now fit just right.
Hop, hop—examples shine bright!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR introduces Compose selection and diagnostics, but it only supports single-type lists, not the valid multi-extension composability described in #560.	Extend Compose to cover compatible multi-extension combinations and update the mappings so valid A+C-style mixes compile while invalid mixes still fail.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	All listed code changes support the Compose contract-type refactor and documentation updates; no unrelated changes stand out.
Title check	✅ Passed	The title clearly summarizes the main change: uniform contract type composition via Compose.
Description check	✅ Passed	The description matches the template with a fix reference, summary, and completed tests/documentation checklist.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/contract-type-compose

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/tokens/src/non_fungible/extensions/combinations/mod.rs`:
- Around line 28-33: Update the module documentation in the combinations module
to remove the claim that Enumerable and Consecutive are mutually exclusive.
Describe unsupported multi-type combinations as not yet curated, while
preserving the explanation about invalid extension-trait implementations and
their trait bounds.
- Around line 28-33: Remove the hard Enumerable/Consecutive incompatibility: in
packages/tokens/src/non_fungible/extensions/combinations/mod.rs:28-33, replace
the module documentation’s mutual-exclusion claim; in
packages/tokens/src/non_fungible/extensions/combinations/mod.rs:50-58, add the
supported Composable tuple mapping for Enumerable and Consecutive and remove the
diagnostic restriction; in packages/tokens/src/non_fungible/mod.rs:105-110,
remove the repeated incompatibility claim.

In `@packages/tokens/src/non_fungible/mod.rs`:
- Around line 105-110: Update the public documentation for the Consecutive and
Enumerable extension mappings near the Consecutive trait references, removing
the statement that they are incompatible. Keep the supported Compose selections
and mapping descriptions accurate without changing the implementation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 657a6a1b-5aff-41fb-98b0-d4764a85d04d

📥 Commits

Reviewing files that changed from the base of the PR and between 56d6e5b and dfd29e3.

📒 Files selected for processing (25)

• Architecture.md
• examples/fungible-allowlist/src/contract.rs
• examples/fungible-blocklist/src/contract.rs
• examples/fungible-capped/src/contract.rs
• examples/fungible-governor-timelock/token/src/token.rs
• examples/fungible-governor/token/src/token.rs
• examples/fungible-pausable/src/contract.rs
• examples/fungible-vault/src/contract.rs
• examples/fungible-votes/src/contract.rs
• examples/nft-access-control/src/contract.rs
• examples/nft-consecutive/src/contract.rs
• examples/nft-enumerable/src/contract.rs
• examples/nft-royalties/src/contract.rs
• examples/nft-sequential-minting/src/contract.rs
• examples/rwa/token/src/contract.rs
• packages/tokens/src/fungible/extensions/burnable/mod.rs
• packages/tokens/src/fungible/extensions/combinations/mod.rs
• packages/tokens/src/fungible/extensions/mod.rs
• packages/tokens/src/fungible/mod.rs
• packages/tokens/src/fungible/overrides.rs
• packages/tokens/src/non_fungible/extensions/burnable/mod.rs
• packages/tokens/src/non_fungible/extensions/combinations/mod.rs
• packages/tokens/src/non_fungible/extensions/mod.rs
• packages/tokens/src/non_fungible/mod.rs
• packages/tokens/src/non_fungible/overrides.rs