> For the complete documentation index, see [llms.txt](https://docs.mineglyph.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mineglyph.xyz/architecture/smart-contracts.md).

# Smart contracts

Two contracts, built with Foundry and OpenZeppelin: **GlyphToken** (the capped ERC-20) and **GlyphMining** (the mining engine).

## GlyphToken

A standard ERC-20 (18 decimals, "Mine Glyph" / GLYPH) with a hard cap.

* `MAX_SUPPLY = 21,000,000e18` — enforced on every mint.
* `LP_PREMINE = 2,100,000e18` (10%) is minted **once** in the constructor to the LP treasury.
* Minting is gated by `MINTER_ROLE`, held **only** by the `GlyphMining` contract. There is **no owner mint** and **no public mint**.
* After deploy, the token admin role can be renounced to make the minter set permanent — at which point no one can ever grant minting rights again.

```solidity
uint256 public constant MAX_SUPPLY = 21_000_000e18;

function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) {
    if (totalSupply() + amount > MAX_SUPPLY) revert CapExceeded();
    _mint(to, amount);
}
```

## GlyphMining

Holds the emission schedule, reward accounting, and signature verification.

### Reward accounting (MasterChef pattern)

Rewards use a global "reward per hashrate" accumulator, so claims are **O(1)** — the contract never loops over miners:

* `accRewardPerHashrate` — accumulator, scaled for precision.
* `totalHashrate` — sum of all active miners' hashrate.
* On any state change, elapsed emission is added to the accumulator; a miner's pending reward is `hashrate × accumulator − rewardDebt`.

### Register / update (signature-gated, payable)

`updateHashrate(hashrate, epoch, nonce, expiry, sig)` verifies the EIP-712 signature, enforces expiry / anti-replay / anti-stale-epoch / the hashrate floor, charges the one-time registration fee on first registration, then updates the miner's share. Pending rewards are settled to an internal balance (not minted) so the claim cooldown can't be bypassed.

### Claim

`claim()` mints accrued GLYPH to the caller, gated by the 1-hour cooldown, and follows checks-effects-interactions under a reentrancy guard.

### Key parameters

| Parameter          | Value (launch default)           |
| ------------------ | -------------------------------- |
| `EMISSION_CAP`     | 18,900,000e18                    |
| `HALVING_INTERVAL` | 180 days                         |
| `registrationFee`  | \~0.00056 ETH (owner-adjustable) |
| `claimCooldown`    | 1 hour                           |
| `minHashrate`      | 100                              |

### Owner powers (deliberately narrow)

The `GlyphMining` owner can only:

* `setSigner` — rotate the attestation key,
* `setFeeReceiver` / `setRegistrationFee` — manage the ETH fee.

The owner **cannot** mint, change the cap, alter emission, or take user funds.

## Testing

The suite runs with zero failures before any deploy:

* **Invariant / fuzz tests** — total supply never exceeds the cap; emission never exceeds the pool; claimed never exceeds emitted; supply always equals premine plus mined. Each runs across tens of thousands of randomized action sequences.
* **Unit tests** — signature forgery, replay, expiry, cross-chain and cross-contract signatures, stale epoch, the hashrate floor, the registration fee, the claim cooldown, reentrancy, proportional rewards, difficulty rising, halving boundaries, and the exact 10% premine.

There is also a one-command end-to-end test that spins up a local chain, deploys, runs the real signer, registers, and claims — proving the TypeScript signature is accepted by the Solidity `ecrecover`.

## Addresses

See [Contract addresses](/resources/contract-addresses.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mineglyph.xyz/architecture/smart-contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.