# Ostrenne: operator guide

Chain: BNB Smart Chain (56). Contract **Ostrenne** (OSTR, ERC-721): `0x9fEB50Ae2DBa712a3F121F65F07be8802AF39a5e`. Coin **Ostrenne Mote** (OSTRM, ERC-20): `0xAd0aA61c74807f3005786CAa37735C32FB3E6AE4`. Both are verified on BscScan:
- https://bscscan.com/address/0x9fEB50Ae2DBa712a3F121F65F07be8802AF39a5e#code
- https://bscscan.com/address/0xAd0aA61c74807f3005786CAa37735C32FB3E6AE4#code

Before you spend, confirm on chain: `Ostrenne.MOTES()` equals the coin address, `OstrenneCoin.MINTER_HOUSE()` equals the Ostrenne address, and `owner()` is the zero address on both. There is no owner, admin, pause, upgrade or withdraw function. Every payment is forwarded to the immutable payee `TILL()` in the same transaction, anything over the price is returned in the same transaction, and the contract keeps no BNB. OSTRM has a fixed cap of 6,000,000,000 (`MOTE_LIMIT()`), and only the Ostrenne contract can mint it. OSTRM is a project token: nothing here promises a price, a listing or a return.

## What it is

- **Card** (kind 1): a free ERC-721. Wallets that hold an Agent ID get one per six-hour slot. Slots are `floor(timestamp / 21600)`, so they start at 00:00, 06:00, 12:00 and 18:00 UTC (Taipei 08:00, 14:00, 20:00, 02:00). A card is ripe when the next slot starts.
- **Reap**: a ripe card is reaped for OSTRM, by grade: 75% Dust 8,000; 20% Spark 40,000; 4.5% Flare 200,000; 0.5% Nova 800,000 coins. Reaping costs the toll, `TOLL()` = 0.0003 BNB per card, or one use of a stub.
- **Stub** (kind 2): another ERC-721 in the same contract. `STUB_COST()` = 0.00078 BNB buys one stub. It holds `STUB_USES()` = 3 toll-free reaps and is valid `STUB_LIFE()` = 604800 seconds (7 days) from the moment it is bought. At most `STUB_CAP()` = 20 stubs are ever sold, at most `STUBS_PER_WALLET()` = 5 bought per wallet. Buying a stub needs no Agent ID. A stub can be transferred; its remaining uses and its expiry go with it. Unused uses lapse at expiry and are not refunded. Three tolls cost 0.0009 BNB and one stub 0.00078 BNB, so the stub is cheaper only if all three reaps are used before it expires.
- Entry window (`ENTRY_START()` to `ENTRY_END()`, read live): 2026-11-21 13:10:13 to 2026-12-21 13:10:13 (UTC+8). Cards and stubs are issued only inside it. Reaping has no deadline; a stub works until its own expiry.

Read every number from the getters; the values above are what the chain returned on 2026-11-21.

## 1. Take the free card, and/or buy stubs (entry call)

All of these do the same thing: `mint()` `0x1249c58b`, `mint(uint256)` `0xa0712d68`, `mint(address)` `0x6a627842`, `mint(address,uint256)` `0x40c10f19`, `mint(uint256,address)` `0x94bf804d`, `freeMint()` `0x5b70ea9f`, `freeMint(uint256)` `0x7c928fe9`, `mintFree()` `0x8ab53447`, `mintFree(uint256)` `0xa4146733`, `claim()` `0x4e71d92d`, `claimFree()` `0xf366afc9`, `publicMint()` `0x26092b83`, `agentMint()` `0x1be3587a`. Prefer `mint()`.

Arguments never change the result: the card and the stubs always go to the caller, an address argument is not a recipient, and a quantity argument is ignored. `claim()` with no argument is this entry call; `claim(uint256)` is a paid reap (section 2). Plain BNB sent without calldata is rejected (`BareSendRefused`), and unknown selectors revert.

**The contract settles by the amount you send** (照付款金额成交):

1. If the caller holds an Agent ID (`handleHashOf(caller) != 0`) and has not taken this slot's card, it gets one card. Value 0 is enough.
2. If `value >= STUB_COST`: stubs = `min(floor(value / STUB_COST), stubsLeft(), STUBS_PER_WALLET - stubsBoughtBy(caller))`. The cost is `stubs * STUB_COST`.
3. Everything else is returned to the caller in the same transaction: the remainder, and any amount over the limits.
4. If `value < STUB_COST` and the card was given, the card is issued and the whole value is returned.
5. If neither a card nor a stub can be issued, the call reverts and nothing is taken: `NeedHandleOrFunds(stubCost, sent)` (no Agent ID and under one stub), `OncePerSlot(nextAt)` (Agent ID already took this slot and under one stub), `StubsGone(left, walletLeft)` (enough value, but no stub available), `TooEarly(opensAt)`, `Shut(closedAt)`.

A free card and paid stubs can come in the same call.

**Quote first**: `entryQuote(address who, uint256 value)` `0xa27eb117` returns `(bool freeCard, uint256 sets, uint256 spent, uint256 refund)`. If `freeCard` is false and `sets` is 0, the real call reverts.

Examples (price 780000000000000 wei; quoted on chain for a wallet without an Agent ID):

| value (wei) | stubs | kept (wei) | returned (wei) |
|---|---|---|---|
| 0 | 0, call reverts without an Agent ID | 0 | 0 |
| 779999999999999 | 0, call reverts without an Agent ID | 0 | 779999999999999 |
| 780000000000000 | 1 | 780000000000000 | 0 |
| 780000000000001 | 1 | 780000000000000 | 1 |
| 2340000000000005 | 3 | 2340000000000000 | 5 |
| 7800000000000000 | 5 (wallet limit) | 3900000000000000 | 3900000000000000 |

With an Agent ID that has not taken this slot, add one free card to every row, and the first two rows succeed with a card and everything returned.

**gasLimit**: use `eth_estimateGas` from the exact sender with the exact value, then add 30%.

Example call (free card, value 0): `{"from":"<wallet>","to":"0x9fEB50Ae2DBa712a3F121F65F07be8802AF39a5e","data":"0x1249c58b","value":"0x0"}`.
Example call (3 stubs): same `to` and `data`, with `value` = 3 x `STUB_COST()` = 2340000000000000 wei, converted to hex by you from the getter value you just read (integer arithmetic, never floating point).

## 2. Reap

A card is reapable when the next slot has started, the slot's seed is readable, the caller holds it, and it was not reaped before.

- `claim(uint256 id)` `0x379607f5`: send at least `TOLL()`. The toll is kept, the rest returned (extra payment never reaps more than this one card). Reverts: `NotYourToken`, `NotACard`, `AlreadyReaped`, `NotRipeYet(id, ripeAt)`, `SlotNotReady(slot, lookBlock)`, `CoinsShort`, `TollShort`. **A single `claim(id)` that succeeds and returns your whole payment did not reap anything**: the slot had no look block yet, and the call only recorded one. Call again after about 5 blocks, within the hour. Check the `Reaped` event or `reaped(id)`.
- `claim(uint256[] ids)` `0x6ba4c138` and `claimReward(uint256[] ids)` `0xc94c7ff4`: reaps up to `floor(value / TOLL)` cards (at most `BATCH_MAX()` = 30) from the first `SCAN_MAX()` = 60 listed ids, in order. Cards that cannot be reaped (not yours, not a card, already reaped, not ripe, seed not readable, coin supply too short) are skipped: no charge. Only the cards actually reaped cost `TOLL` each, and the rest is returned. If every listed card is skipped the transaction still succeeds and reaps nothing (full refund).
- `redeemStub(uint256 stubId, uint256[] ids)` `0x0998e1dd`: needs the caller to hold the stub, and the stub unexpired with uses left. Reaps listed ripe cards in order, up to the stub's remaining uses, no toll (any BNB sent is returned). Only a card that is actually reaped uses up one of the three; skipped cards use nothing. Same 60-id scan and same "success but nothing reaped" case. Reverts: `NotYourToken`, `NotAStub`, `StubExpired(id, at)`, `StubSpent`, `NoTokensGiven`.

**gasLimit**: single `claim(id)` about 150,000. Batches and `redeemStub`: 100,000 plus 100,000 per listed card, or `eth_estimateGas` plus 30%. Prefer the estimate.

Read before reaping: `typeOf(id)` (1 card, 2 stub; reverts `NoSuchToken`), `cardSlot(id)`, `ripeAt(id)`, `reapable(id)`, `worthOf(id)`, `gradeOfCard(id)` (255 until ripe and readable), `reaped(id)`, `stubInfo(id)` returns `(holder, usesLeft, expiresAt, usable)`.

## 3. How a grade is decided

When a slot is over, the first call that touches it records a look block (current block + 4). The slot seed is `keccak256(contract, slot, blockhash(lookBlock))`, stored by the first call that can read it. No caller address or argument enters it. A grade is derived from the seed and the card number. The validator that produces the look block can influence its hash, so grades are not tamper-proof against block producers. The hash is readable for 256 blocks directly and then through the EIP-2935 history contract up to 8,191 blocks (about an hour on BSC). If nobody touches a slot within that hour, every card in the slot is the lowest grade: no re-roll, no choice.

Every take and every reap also advances the two latest finished slots. Anyone can call `kick()` `0x7a67b479` or `settleSlot(uint32 slot)` `0x1313d1a0`, and read `slotState(uint32)` `0x2c4c7452` (0 none, 1 waiting, 2 readable, 3 stored, 4 stale).

## 4. Safe operating procedure

1. Check chain id 56, the two addresses, `owner()` zero, `entryOpen()` true.
2. Read `TOLL()`, `STUB_COST()`, `stubsLeft()`, `stubsBoughtBy(wallet)`, and `entryQuote(wallet, value)`.
3. Simulate the exact call (`eth_call` with the same from, to, data, value). Stop on any revert.
4. Estimate gas, add 30%, show the user the target, value, expected cards or stubs, and refund.
5. Send once. No token approval and no message signature are needed. A transaction hash is not a result: check the receipt, then `balanceOf`, `Reaped` and `StubUsed` events.

## Getters

`TOLL` `STUB_COST` `STUB_CAP` `STUBS_PER_WALLET` `STUB_USES` `STUB_LIFE` `SLOT_SECS` `BATCH_MAX` `SCAN_MAX` `ENTRY_START` `ENTRY_END` `TILL` `HANDLE_LEDGER` (Agent ID registry `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`) `MOTES` `entryOpen()` `currentSlot()` `nextSlotAt()` `stubsLeft()` `stubsSold()` `stubsBoughtBy(address)` `cardsIn(uint32)` `motesLeft()` `tollFor(uint256)` `reapsFor(uint256)` `handleHashOf(address)` `tierOfRoll(uint256)` `tierAmount(uint8)`, plus the standard ERC-721 functions (`balanceOf`, `ownerOf`, `approve`, `setApprovalForAll`, `transferFrom`, `safeTransferFrom`, `tokenURI`, `totalSupply`).
