# Voltrune operator's bench

Voltrune Rigs (VTRN) is the NFT. The Forge pays Voltrune Coin (VTRNC). These names are fixed in the source; addresses are final and the window opened at 2026-11-21 09:57:43 (UTC+8). This manual describes transactions; it grants no permission to submit them.

## Wire the three contracts

On BNB Smart Chain, chain ID 56 / 0x38:

| Job | Contract | Address |
| --- | --- | --- |
| Obtain a rig; settle its tier | VoltruneRigs | 0x145C5B3Ab1268dbf5F86192bcE390c9c60076FFF |
| Pay for shifts | VoltruneForge | 0xdaa7B0fd23fb9EAd3e6687AB5383C3e1ca489c5f |
| Receive the reward | VoltruneCoin | 0x931beFc4e4fEc9bE674B0d101938132c199a1DcB |

Check verified source at https://bscscan.com/address/<address>#code and bytecode at all three addresses. Never transact with an address not listed here. There is no owner/admin, pause, upgrade or withdrawal function; owner() returns zero. RECIPIENT() is immutable. Shift fees reach it and change returns to the caller in the same transaction. Ordinary calls retain no BNB; forced transfers are a separate case. The reward cap is fixed; only the linked Forge can issue Coin.

Confirm Rigs.FORGE() == Forge, Forge.RIGS() == Rigs, Forge.COIN_TOKEN() == Coin, Coin.FORGE() == Forge. Rigs.ID_LEDGER() must equal the Agent ID Registry at 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F ([verified source](https://bscscan.com/address/0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F#code)). rigKeyOf(address) returns (key,ok): the key hashes registry.handleOf(wallet), and registry.ownerOf(key) must be that wallet.

## Collect a rig, then let the next block finish

Read rigClaimable(address), rigOfAgent(uint256), rigOfWallet(address), RIG_CAP() and rigsMinted(). The collection accepts claims only in [startAt(),shutAt()), while supply remains. Each Agent ID can claim once for life; transferring the NFT or changing aliases does not create another claim.

Use claim() at 0x145C5B3Ab1268dbf5F86192bcE390c9c60076FFF, value=0 wei, gasLimit=314000. The protocol charges nothing for the NFT; network gas applies. Any attached BNB is returned atomically. Numeric aliases ignore their argument and always use the caller's own identity. All eleven entries share eligibility:

- `claim()` — `0x4e71d92d`
- `mint()` — `0x1249c58b`
- `freeMint()` — `0x5b70ea9f`
- `mintFree()` — `0x8ab53447`
- `claimFree()` — `0xf366afc9`
- `publicMint()` — `0x26092b83`
- `agentMint()` — `0x1be3587a`
- `mint(uint256)` — `0xa0712d68`
- `freeMint(uint256)` — `0x7c928fe9`
- `mintFree(uint256)` — `0xa4146733`
- `claim(uint256)` — `0x379607f5`

The claim records its block number. target=claimBlock+1; the earliest readable tier is at claimBlock+2. Wait for tierKnown(uint256) before quoting a shift. rankOf(uint256) and settleRank(uint256) can revert TierPending until the target block is over or its hash becomes readable.

### Keep the target hash in reach

The draw is keccak256(abi.encode(targetHash,rigId,chainid)) % 100: 0..4 Prime, 5..29 Tuned, 30..99 Standard (5/25/70 percent draw intervals, not measured minted proportions). Claimers do not know this future hash when claiming; block producers can slightly influence it.

HASH_SPAN() is 8191 blocks, about 61 minutes on BNB Smart Chain; actual elapsed time follows block production. Age is current block minus target. Through age 256 the contract reads BLOCKHASH; at ages 257..8191 it reads the EIP-2935 history contract returned by BLOCKHASH_STORE(). Unreadable or missing history within that span leaves the tier pending. If age exceeds 8191 before the tier is fixed, resolution becomes Standard permanently. No replacement block is drawn.

Anyone may submit settleRank(uint256), selector 0x40173f20, to the Rigs with value=0. Simulate, estimate, and use max(250000,ceil(1.2*estimateGas)); gas applies. The first successful paid shift fixes its own rig too. Every claim attempts to settle one older ready rig; every Forge work call attempts two older ready rigs, with no gas threshold. sweep() attempts up to four; settleSome(uint256,uint256) permits at most four steps with a caller-selected gas floor. tierCount(uint256) and settledCount() count fixed tiers; sweepFrom() tracks the cursor. tierKnown means readable, not necessarily fixed, so an unfixed preview can still fall back after expiry.

## Clock in at the Forge

The payable shift entries at 0xdaa7B0fd23fb9EAd3e6687AB5383C3e1ca489c5f are:

- mine(uint256[]) — 0x91e083c3
- mine(uint256) — 0x4d474898
- mine() — 0x99f4b251
- mineRepeat(uint256,uint256) — 0x1e211c56

Read shiftFee() in wei, shiftPrice(uint256), shiftsLeft(uint256), SHIFTS_PER_DAY() and MAX_SHIFTS_PER_CALL(). The approved fee illustration is 0.0002 BNB; the constructor sets the actual immutable fee. Use integer wei / BigInt throughout. The current daily limit is five shifts per rig; each call permits at most fifty listed entries. The caller must own every reached rig. mine() selects the rig originally claimed by the caller's Agent ID; a transferred-in rig should use mine(id).

Payment buys the shifts. For one rig, floor(value/F) shifts run up to daily and call limits, where F=shiftFee(). In mineRepeat(id,times), times is only a quote: even times=0 does not suppress a funded shift. Arrays are also bounded by their listed entries; repeating an ID buys another shift, and a rig with no daily room is skipped without a charge. Any reached foreign/nonexistent rig reverts the whole call. Unused payment and fractional change are refunded in the same transaction. Value below F cannot buy one shift and reverts ForgeFeeShort(required,sent); zero completed shifts reverts ShiftLimit(id).

With fresh daily room, an open window and rewards remaining, quote N=3 using shiftPrice(3)=3F. Check ownership and eligibility separately; the quote is multiplication only.

| Call / payment | Completed shifts | Refund |
| --- | --- | --- |
| mine(id), 3F | 3 | 0 |
| mine(id), 3F+1 wei | 3 | 1 wei |
| mine(id), 6F | 5 (daily limit) | F |
| mine(id), 3F-1 wei | 2 | F-1 wei |
| mine(id), F-1 wei | revert | no protocol charge |
| mine([id,id,id]), 6F | 3 (list length) | 3F |

For example, only when shiftFee() returns 200000000000000 wei, shiftPrice(3) is 600000000000000 wei. Re-read before execution. If daily room is lower, fewer shifts run and more payment returns.

### Gas at the station

Claim: 314000 (measured worst case 261276 in the final API report). First shift: 491000 (reported worst case 409111). For N shifts of one rig, reserve (first shift ? 491000 : 325000) + 5700*(N-1). Non-first one-shift baseline is 325000. For arrays, estimate the exact transaction and reserve max(491000+5700*(N-1),ceil(1.2*estimateGas)); distinct rigs can cost more than repeated shifts. Run eth_call and eth_estimateGas before every submission. The UI stops when its single-rig budget cannot cover the estimate. Gas is separate from shift fees.

## Read the payout, check the receipt

Reward base units = SHIFT_BASE() * tierPct(rankOf(id)) * streakBps(streakLive(id) or 1) / 1000000. Base is 450 VTRNC; Standard/Tuned/Prime give 1x/2x/4x. Streak multipliers are 1.00x on days 1-2, 1.25x on days 3-6, 1.50x from day 7. UTC day = floor(timestamp/86400); a whole missed UTC day resets the streak. Repeated shifts on one day do not add streak days. Transfers preserve usage and streak.

Read nextShiftPay(uint256), Coin.left(), COIN_CAP() and decimals(). The cap is 2,000,000,000 tokens. nextShiftPay ignores the cap and eligibility: the final successful shifts can receive less while still paying their per-shift fee. Once no Coin remains, the call reverts CoinGone() before collecting a fee; network gas may still be spent. VTRNC is a project-issued token, not BNB, with no BNB valuation or liquidity pool. Rewards are issued to the caller inside successful mining; there is no later reward withdrawal. claim() obtains the NFT only.

Rigs claiming uses [Rigs.startAt(),Rigs.shutAt()). Forge shifts use [Forge.startAt(),Forge.shutAt()), where Forge.shutAt() = Rigs.shutAt() + TAIL() (seven days). Read each closing time; paid shifts can remain available after claims close.

## Submission checklist

1. Resolve release addresses, check chain, verified source, zero owner and all immutable links.
2. Read latest time, claim supply/eligibility or NFT ownership, tier readiness, daily room and remaining Coin.
3. Call shiftPrice(N); encode the correct Forge overload and exact native value. No ERC-20 approval is needed.
4. eth_call exact {from,to,data,value}; then eth_estimateGas and select the budget above. Stop on failure.
5. Present target, calldata, value and gas for transaction approval. Submit only with approval; wait for status=1 receipt and reconcile Coin, fees, refund and usage. Never blindly resubmit a pending hash.

Copyable request:
> On BNB Smart Chain (56), verify VoltruneRigs 0x145C5B3Ab1268dbf5F86192bcE390c9c60076FFF, VoltruneForge 0xdaa7B0fd23fb9EAd3e6687AB5383C3e1ca489c5f and VoltruneCoin 0x931beFc4e4fEc9bE674B0d101938132c199a1DcB. Check immutable links and rig ownership, tierKnown(id), shiftsLeft(id), Forge window and Coin.left(). Quote shiftPrice(N). Preview mine(uint256) on the Forge with value=shiftPrice(N), gasLimit=(first shift ? 491000 : 325000)+5700*(N-1), and estimate gas. Show the exact transaction and VTRNC output conditions. Execute only after approval if the same preview passes and there are no approval changes.

Plain BNB to Rigs reverts FreeEntryOnly(); plain BNB to Forge reverts OnlyShifts(). Unknown selectors revert. ForeignRig(id), ForgeClosed(opens,closes), ForgeBatch(maximum), failed recipient payment or refund also revert atomically.

agent.json provides structured routing; ABI and selectors files are compiled from the fixed contracts with Prague EVM. The wallet transport follows https://eips.ethereum.org/EIPS/eip-1193 .
