The Codex

How to Stake.

Every detail of the Necrowls staking mechanism, from the first stake to the last claim. No surprises. No fine print.

The Path

Three Rites.

I

Stake

One click
Lock & Earn
Pick your owls, hit Stake. Pay gas. Each chosen owl locks inside your wallet and starts drawing rewards immediately.
II

Earn

Continuous
Pro-rata
Every secondary sale pays 50% of its royalty into the pool. Your share is split across all staked owls.
III

Unstake

1-hour cooldown
Cancelable
Request unstake, wait one hour, finalize. Cancel anytime during cooldown to keep earning without restarting.
The Mechanism

Step by Step.

Step 1

Staking

Connect your wallet on the Stake page. Your unstaked owls appear in the left grid. Tap any owl to select it. The selection counter at the bottom shows how many you've picked. Tap Stake Selected (or Stake All) and confirm the transaction in your wallet.

When the transaction confirms, the staking contract calls setLocked on each owl in the NFT contract. From that moment the owl is locked inside your wallet:

  • You still own it. balanceOf still counts it. It still shows up in your wallet's NFT list.
  • It cannot be transferred or sold while staked. The lock is enforced at the contract level in _update.
  • It begins earning a share of every royalty as soon as the staking tx is mined.

You can stake more owls at any time. Each new stake takes effect for the very next royalty deposit.

Step 2

Earning

Royalty income arrives whenever a Necrowl sells on a marketplace that respects royalties (OpenSea, Magic Eden, anywhere that honors ERC-721C). Half of the royalty automatically flows to the staking contract; the other half goes to the creator wallet.

Your unclaimed earnings are tracked by a Synthetix-style pull model: rewards accumulate against your address as new royalties enter the pool. Nothing rebases. Nothing decays. Nothing is spent on gas on your behalf until you choose to claim.

Your share at any moment is calculated as:

(your active stake) ÷ (total active stake) × royalty deposit

Owls in cooldown do not earn. Other owls you have staked keep earning normally.

Step 3

Claiming Rewards

On the Stake page, your accumulated rewards display in real time under Earned. Tap Claim to pull them to your wallet. There is no minimum, no cap, and no time gate. Claim whenever the gas math makes sense for you.

Claiming does not unstake. It just sweeps your accrued ETH and zeros the counter.

Step 4

Unstaking

To unstake, select the staked owls you want to retrieve and hit Unstake Selected. This is the request unstake step. No owl leaves staking yet. Instead:

  • Each selected owl moves from Staked to Cooling.
  • A 1-hour cooldown timer starts. All owls in the same request share one timer.
  • Owls in cooldown stop earning. Your other staked owls continue.
  • Owls remain locked. They cannot be transferred during cooldown.

When the timer hits zero, the Finalize button activates. Confirm the transaction and the staking contract calls setLocked(id, false) on each owl. The lock lifts. Owl is fully yours again, free to transfer, list, or re-stake.

Step 5

Canceling a Cooldown

Changed your mind? Anytime during the cooldown, hit Cancel on the cooldown card. You can cancel individual owls (tap each chip to select, then Cancel selected) or all at once.

Canceled owls go straight back to Staked and immediately resume earning. No cost beyond gas. No penalty. No restart of any timer.

Step 6

Marketplace Listings

This trips up a lot of people, so read it carefully.

The rule

Always unlist before you stake. Always unstake before you list.

Listings live off-chain on the marketplace. The staking lock lives on-chain in the NFT contract. They don't know about each other. Mixing them creates the problems below, none of which are theoretical.

What goes wrong if you list while staked

OpenSea (and Blur, Magic Eden, every aggregator) keeps your listing visible because the signed order is still cryptographically valid. The marketplace has no idea the token is locked. Three concrete consequences:

  • Buyers waste gas on failed transactions. Anyone who clicks Buy will have their transaction revert in _update. They pay gas for nothing and get nothing in return. Repeat enough times and marketplace algorithms flag the collection.
  • Your listing can anchor the floor below the real market. If your listed price was the lowest when you staked, and the market moves up afterwards, your dead listing keeps showing as the floor, but it can't be filled. The collection floor reads artificially low to anyone scanning, and real buyers waste gas trying to take it.
  • You can lose money on the unstake. The instant you finalize unstake, the lock lifts. Your old listing, possibly priced from days or weeks ago, below today's market, is suddenly fillable. The first bot watching for newly-unlocked tokens can snipe it. You sell at yesterday's price even though today's price is higher.

What goes wrong if you stake while listed

Same outcome as above, in reverse. Your existing listing keeps drawing failed buy attempts and keeps anchoring the floor until you either cancel it on the marketplace or unstake. Cancellation costs gas. Unstaking takes an hour.

Selling a staked owl

A staked owl cannot be sold, period. To actually sell:

  • Request unstake on the owl.
  • Wait for the 1-hour cooldown.
  • Finalize. The lock lifts.
  • List on the marketplace at the price you want today.

In that order. Don't list before finalizing, don't relist a stale order, don't leave an old order live "just in case." Cancel anything stale first, then list fresh.

Common Questions

Edge Cases.

The staking contract has no recovery function. Your staked owls are tied to your wallet address. Protect your keys.

No. The contract uses msg.sender for every action. Only the wallet that staked an owl can request, cancel, or finalize unstaking. Nobody, including the deployer, can override this.

Royalties depend on secondary sales. If no Necrowl sells in a given week, no new rewards accumulate that week. Your stake doesn't lose value, you just don't earn until the next sale.

Yes, as long as the wallet holds the NFTs. A Gnosis Safe (or any contract wallet) can call stake, requestUnstake, claim, and the others.

No. Claim transfers exactly what's accrued at the moment of the transaction. Future royalty deposits keep accruing to you as long as your owls stay staked.

To prevent a wallet from sandwiching a large royalty deposit: stake right before, unstake right after, capture the deposit unfairly. The cooldown means anyone trying that trick stops earning during the wait, which neutralizes the attack while keeping the wait short for honest users.

Base mainnet keeps gas extremely low. A typical stake of 5 owls is a few cents. Claim is similar. Finalize is similar. Cancel is similar.

Each Necrowl sale on a royalty-respecting marketplace splits the royalty: 50% to the creator wallet, 50% to the staking contract. The staking contract distributes its half to stakers pro-rata.

Open The Roost Open The Mint