> 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/overview.md).

# Overview

Mine Glyph is three layers: an off-chain **indexer**, an off-chain **signer**, and on-chain **contracts**. The split exists because an EVM contract cannot read wallet history — it must be computed off-chain and proven on-chain.

```
┌─────────────┐   reads history    ┌──────────────┐   EIP-712 sign    ┌──────────────┐
│  Indexer    │ ─────────────────► │   Signer     │ ────────────────► │   Frontend   │
│ (off-chain) │  age/tx/vol/hold   │  (off-chain) │  (wallet,hr,...)  │  (Next.js)   │
└─────────────┘                    └──────────────┘                   └──────┬───────┘
                                                                             │ submits sig
                                                                             ▼
                                                                     ┌──────────────┐
                                                                     │ GlyphMining  │
                                                                     │  (contract)  │
                                                                     │ verify + mint│
                                                                     └──────────────┘
```

## The four components

| Component     | Role                                                         | Stack                  |
| ------------- | ------------------------------------------------------------ | ---------------------- |
| **Indexer**   | reads a wallet's history, computes hashrate                  | TypeScript · ethers    |
| **Signer**    | signs `(wallet, hashrate, epoch, nonce, expiry)` via EIP-712 | TypeScript             |
| **Contracts** | verify the signature, enforce the cap, stream rewards        | Solidity · Foundry     |
| **Frontend**  | connect wallet, request attestation, submit transactions     | Next.js · wagmi · viem |

There is also a **Telegram bot** that welcomes community members and posts $GLYPH buy alerts — independent of the mining path.

## Why off-chain compute, on-chain trust

Solidity can only see current state, the last 256 block hashes, the block number, and the timestamp. It **cannot** read how old a wallet is, how many transactions it has made, or how much volume it has moved. So:

* The **indexer** does the reading and the math.
* The **signer** vouches for the result with a cryptographic signature.
* The **contract** verifies that signature and refuses anything else.

This keeps the expensive, data-heavy work off-chain while keeping the **trust anchored on-chain**: the reward accounting, the hard cap, replay protection, and expiry are all enforced by the contract, not by the servers.

## Data flow for one mining session

1. You connect your wallet (free).
2. The frontend asks the indexer for your hashrate — shown as a live breakdown.
3. You click Start mining; the frontend requests a signed attestation from the signer.
4. You submit that attestation to `GlyphMining.updateHashrate()` with the registration fee.
5. The contract verifies and records your hashrate; rewards accrue every second.
6. Later, you call `claim()` and the contract mints your GLYPH.

## Deployment

* **Indexer + signer** run as a single Node service (deployable to Railway or any Node host). The signer's private key lives only in the host's secret store.
* **Frontend** and the **Telegram bot** deploy as separate Next.js apps.
* **Contracts** deploy to Robinhood Chain via Foundry.

See [Indexer & signer](/architecture/indexer-signer.md) and [Smart contracts](/architecture/smart-contracts.md) for details.


---

# 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/overview.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.