Skip to content

Encode beasts into token IDs #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
loothero merged 2 commits into from
May 21, 2026
Merged

Encode beasts into token IDs #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
162977a
encode beasts into token ids
codex May 21, 2026
8d238c7
point to AGENTS.md
codex May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,15 @@
- Export public APIs in `src/lib.cairo` via `pub mod ...`.
- Prefer traits over free helpers; use `panic` only for invariant checks.

## Beast Token ID Design
- `PackableBeast` in `src/pack.cairo` defines the canonical 53-bit token ID format. Use `encode_token_id(beast)` and `decode_token_id(token_id)`; do not duplicate the bit math elsewhere.
- ERC721 token IDs are deterministic, not sequential: `token_id == encode_token_id(PackableBeast)` for both genesis and non-genesis Beasts.
- The contract intentionally has no `Storage.beasts` map. Decode token IDs only after ERC721 ownership/existence checks where user-facing existence matters.
- `total_supply()` is backed by `supply_count` and is a count of minted NFTs, not the largest token ID.
- Genesis Beasts are minted in the constructor, have rank `0`, and must not rely on `token_id <= 75`. They remain excluded from the `minted` uniqueness map.
- Non-genesis uniqueness remains based on `(beast_id, prefix, suffix)` via `minted`; ranking, metadata bookmarks, and manual refresh timestamps still index by packed token ID.
- This storage/token-ID design is for fresh deployments only. Do not add migration behavior for legacy sequential token IDs unless explicitly requested.

## Testing Guidelines
- Framework: Starknet Foundry (`snforge_std`).
- Prefer test files in `src/` with `*_test.cairo` or `*_tests.cairo` suffixes; existing legacy files such as `tests.cairo` remain valid.
Expand Down
Loading
Loading