Source – Alkane 2:89503 — SUBFROST Explorer

CLAUDE.md11,601 B

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What This Is
FIRE is a utility token system built on the ALKANES metaprotocol (Bitcoin). It meters production based on timelocked LP positions in the DIESEL/frBTC pool. 0% premine, 100% emission via staking (85%) and bonding (15%). The repo contains Rust smart contracts compiled to WASM, shared crates, and integration tests.
## Build Commands
```bash
# Build all workspace crates (native, for IDE/check)
cargo build
# Build individual contract for WASM deployment
cargo build --release --target wasm32-unknown-unknown -p fire-token
cargo build --release --target wasm32-unknown-unknown -p fire-staking
# etc. for fire-treasury, fire-bonding, fire-redemption, fire-position-token, fire-bond-token, fire-price-oracle
# Build all WASM contracts + copy to test dir
./scripts/build-wasms.sh
# Run all integration tests (WASM target required)
cargo test --target wasm32-unknown-unknown
# Run a specific test
cargo test test_stake_with_no_lock --target wasm32-unknown-unknown -- --nocapture
# Run unit tests in support crates (native target OK)
cargo test -p fire-support
cargo test -p fire-constants
# Deploy on regtest
./scripts/deploy-proxied.sh # mainnet params (ACTIVATION_BLOCK=950420)
DEVNET=1 ./scripts/deploy-proxied.sh # short epochs (HALVING_INTERVAL=200)
# Verify the deploy (reads .deploy-ids.env)
./scripts/test-upgrade.sh # upgrade roundtrip on all 6 proxies + 2 beacons + no-auth check
./scripts/test-state.sh # state preservation across upgrade
# Deploy on mainnet (production-hardened: preflight + cost gate + revert detection)
DEPLOY_PASSWORD=$(security find-generic-password -s fire-deploy -w) \
FEE_RATE=10 LP_BLOCK=2 LP_TX=77087 \
./scripts/deploy-mainnet.sh
```
## Architecture
### Upgradeable Proxy Pattern
All FIRE contracts behind upgradeable proxies / beacons. Bug fixes possible without
redeploying or losing state. Position NFTs and staking clones use beacon-proxy
pattern so logic upgrades apply atomically to all existing instances.
**Singletons** use FIRE-customized `fire-upgradeable`:
- Proxy stores `/implementation` AlkaneId and delegates all calls via `delegatecall`
- Master-auth holder calls `upgrade(new_impl)` (opcode 32766) to swap logic
- Storage lives on the proxy; implementation is stateless bytecode
**Staking clones + position NFTs** use `fire-upgradeable-beacon` + `alkanes-std-beacon-proxy`:
- Beacon stores the current implementation; separate beacon per contract type
- Each clone is a beacon-proxy instance created via CREATECHILD
- On every call, beacon-proxy queries beacon for current impl → delegatecall
- Upgrading beacon = all existing clones instantly use new logic
**Master auth** (FIRE-AUTH): single shared fungible NFT controls every
upgradeable proxy and beacon in the system. `set_auth_token(shared_auth)` in proxy
init points `/auth-token-id` at this fixed slot for ALL proxies.
- Mainnet: `4:666` (initial 4:255 was burned in a failed deploy attempt, replaced)
- Regtest: `4:255` (default reserved slot, `./scripts/deploy-proxied.sh`)
### Deploy Mechanics
Shared bytecode is uploaded once and cloned via `CREATECHILD`:
- `fire_upgradeable.wasm` at 4:530 → cloned 6× for the singleton proxies
- `fire_upgradeable_beacon.wasm` at 4:531 → cloned 2× for staking-beacon + position-beacon
- `alkanes_std_beacon_proxy.wasm` at 4:520 → shared by epoch staking-clones AND position NFTs
(same bytecode, different beacons in init args determine behaviour)
Proxy and beacon AlkaneIds are **dynamic** (2:N, assigned at deploy time, exported to
`.deploy-ids.env` after Phase 6). Impl / template / immutable-token slots stay fixed.
```
User → Proxy 2:N → delegatecall → Impl (4:512-517)
User → Epoch Clone 2:N → staticcall Staking-Beacon → delegatecall → Impl 4:518
User → Position NFT 2:M → staticcall Position-Beacon → delegatecall → Impl 4:521
```
### Slot Layout
| Contract | Public ID | Implementation | Type |
|---|---|---|---|
| fire-master-auth | mainnet 4:666 / regtest 4:255 | — | single shared auth NFT (FIRE-AUTH) |
| fire-token | mainnet 2:77623 | 4:512 (0x200) | upgradeable proxy |
| fire-staking-factory | mainnet 2:77624 | 4:513 (0x201) | upgradeable proxy |
| fire-treasury | mainnet 2:77628 | 4:514 (0x202) | upgradeable proxy |
| fire-bonding | mainnet 2:77627 | 4:515 (0x203) | upgradeable proxy |
| fire-redemption | mainnet 2:77625 | 4:516 (0x204) | upgradeable proxy |
| fire-price-oracle | mainnet 2:77626 | 4:517 (0x205) | upgradeable proxy |
| staking beacon | mainnet 2:77621 | — | beacon (under master auth) → 4:518 |
| position beacon | mainnet 2:77622 | — | beacon (under master auth) → 4:521 |
| fire-staking (epoch-0 clone, mainnet) | 2:77631 | via staking beacon → 4:518 | beacon-proxy clone |
| wLP series-0 "FIRE-PT-0" (mainnet) | 2:77632 | — | direct (immutable) |
| fire-staking (clones, per epoch) | 2:N | 4:518 (0x206) | beacon-proxy clones |
| fire-position-token (clones, per stake) | 2:M | 4:521 (0x209) | beacon-proxy clones |
| beacon-proxy template | 4:520 | — | template (shared by staking + position clones) |
| fire-upgradeable template | 4:530 | — | template (CREATECHILD source for 6 proxies) |
| fire-upgradeable-beacon template | 4:531 | — | template (CREATECHILD source for both beacons) |
| fire-bond-token | 4:263 (0x107) | — | direct (immutable) |
| fire-series-token (wLP) | 4:264 (0x108) | — | direct (immutable) |
### Proxy Opcodes (reserved, high-range)
- `32767` (0x7FFF): `initialize` — one-time setup, binds proxy to shared auth + impl
- `32766` (0x7FFE): `upgrade` / `upgrade_to` — swap implementation (requires master auth in incoming)
- `32765` (0x7FFD): `implementation` — view, returns current impl AlkaneId (beacon only)
- `36863` (0x8FFF): `forward` — passthrough, returns incoming alkanes unchanged
### Contract Pattern
Every contract follows this pattern using alkanes-runtime macros:
1. Define a unit struct (e.g., `FireToken(())`)
2. Implement `AlkaneResponder`
3. Define a `MessageDispatch` enum with `#[opcode(N)]` variants
4. Implement handler methods matching each enum variant
5. Wrap with `declare_alkane!` macro
Storage uses `StoragePointer::from_keyword("/key")` with `get_value::<T>()`/`set_value(v)` for scalars, and `get()`/`set(Arc<Vec<u8>>)` for `AlkaneId`s.
### Tokenomics (Zero Premine)
- 0% premine, 100% emission. total_supply starts at 0.
- 85/15 split: staking (1,785,000 FIRE) / bonding (315,000 FIRE)
- Emission per block: staking 850,000,000 units/block, bonding 150,000,000 units/block
- Halving every 105,000 blocks (~2 years). Geometric sum converges to 2.1M.
- First FIRE halving coincides with next Bitcoin halving (block 1,050,000). Every other FIRE halving = BTC halving.
- All durations in blocks: WEEK=1050, MONTH=4375, YEAR=52500, HALVING_INTERVAL=105000
### Position Token Architecture
Staking uses NFT position tokens instead of per-user storage keyed by `context.caller`:
- `fire-staking` creates a `fire-position-token` instance via factory cellpack (`AlkaneId { block: 6, tx: template }`) on each `stake()` call
- Position token stores: deposit_amount, weighted_amount, lock_end, multiplier, reward_checkpoint
- `unstake()`, `claim_rewards()`, `split()`, `merge()` accept `target_position: AlkaneId` parameter to select specific NFT when multiple are in same UTXO ({0,0} = first found, backward compatible)
- Position token stores `deposit_token_id` so `unstake()` returns exactly the token that was deposited
- Position tokens are registered/deregistered as children of the staking contract
- Only the vault (staking contract, stored as `context.caller` during factory create) can mutate reward checkpoint/pending via opcodes 1 and 2
- `GetPositionSplitStatus` (opcode 37) lets clients check if a position has been split
### Inter-Contract Communication
- Staking mints FIRE via `call` to fire-token opcode 77 (`MintFromStakingPool`)
- Bonding mints FIRE via `call` to fire-token opcode 78 (`MintFromBondingPool`)
- Bonding queries treasury opcode 23 (`GetRedemptionRate`) for floor price guard
- Auth is checked via `context.caller` comparison (e.g., only staking contract can mint from staking pool)
- View functions use `staticcall`; mutations use `call`
- All user-facing contract IDs use proxy addresses (`block: 4, tx: PUBLIC_ID`). Inter-contract calls go through proxies — delegatecall is transparent to callers.
- Bonding `Bond` accepts `lp_to_bond` + `min_fire_out` parameters; returns LP change from UTXO
- Bonding `ClaimVested` accepts `target_position: AlkaneId` for NFT selection
- Bonding tracks `total_claimed_fire` (opcode 33) for accurate circulating supply
- Staking tracks `total_raw_stake` (opcode 34) — raw LP across all positions, no multiplier/duration filter
- Treasury `deposit()` returns non-LP tokens to caller (no auth, anyone can call)
### Reward Math
- Block-height based (`self.height()`), not timestamp
- Global `reward_per_token_stored` accumulator, Synthetix-style
- Emission rate halves every TWO_YEARS blocks (epoch = elapsed / TWO_YEARS)
- Weighted stake = deposit * multiplier / 100 (multiplier in basis points)
- U256 arithmetic for reward_per_token increment (prevents overflow)
- Constants defined in `fire-constants` crate (`no_std`)
### Key Design Decisions
- **Upgradeable proxies**: All singletons behind `alkanes-std-upgradeable`, staking clones behind beacon pattern. Auth tokens control upgrades.
- **Minimal treasury**: Only 6 opcodes (Init, Deposit, RedeemBacking, GetRedemptionRate, GetTotalBacking, GetName). Bonding/redemption set at init, no admin.
- **No distributor**: Deleted. With 0% premine there is nothing to distribute.
- **No redemption cooldown**: Self-limiting via fee. Bond-redeem cycle proven unprofitable.
- **Bond price floor guard**: `max(oracle_discounted, floor)`. No premium — bond at floor is neutral (floor unchanged). Bond-redeem cycle unprofitable via 1% redemption fee.
- **DEFAULT_VESTING_PERIOD**: 1,050 blocks (WEEK = HALVING_INTERVAL / 100). Immutable after deploy.
- **epoch_start = deploy height**: Bonding init sets epoch_start to current_height, not epoch_boundary. Prevents instant capacity unlock when genesis is in the past.
- **incoming_alkanes uses .find()**: Runtime guarantees one transfer per token ID (BalanceSheet is BTreeMap). All handlers use `.find()` consistently.
## Testing
Tests run as `wasm_bindgen_test` functions targeting `wasm32-unknown-unknown`. The test harness:
- Lives in `src/tests/` — root crate is the test harness, not a deployable contract
- `vendor.rs` includes WASM bytes via `include_bytes!("./wasm/*.wasm")` — WASMs must be built first via `./scripts/build-wasms.sh`
- `helpers.rs` provides `clear_test_environment()`, `create_deployment_block()`, `create_operation_block()`, block indexing, and balance sheet inspection
- `fire_foundation.rs` handles deploying and initializing the FIRE contract stack
- Tests verify contract behavior by indexing blocks and checking output balance sheets
- Unit tests in `fire-support` (142 tests): emission math, lock multipliers, epoch alignment, target_position selection, token return flow, proxy architecture constants
## Prerequisites
- Rust stable with `wasm32-unknown-unknown` target: `rustup target add wasm32-unknown-unknown`
- wasm-bindgen-cli 0.2.100: `cargo install -f wasm-bindgen-cli --version 0.2.100`
- alkanes-rs (for proxy WASMs + CLI): `../alkanes-rs/`

Verified Source