# hypr

**A layer-1 with fixed micro-fees, a protocol-native AMM, and a liquidity pool the chain cannot touch.**

Version 1.4.0 · mainnet chain id 4977 (`0x1371`) · testnet 4978 (`0x1372`) · native symbol `HYPR` · 18-decimal wallet surface over a 6-decimal ledger

---

## Abstract

hypr is a single-purpose layer-1. It does three things and refuses to do a fourth:
it moves a native asset between accounts, it holds issuable second-party assets,
and it runs constant-product liquidity pools. It has no virtual machine, no
smart contracts, no governance token, no staking, and no inflation curve beyond a
capped, halving block subsidy.

Two properties drove every design decision.

**Fees are small in absolute terms.** Not "competitive with other chains" —
small. A native operation has a published, fixed cost in base units, and the only
thing that can move that cost is a chain-wide multiplier that is hard-capped at
eight. The worst-case transfer therefore costs 80 base units: `0.00008 HYPR`.
There is no auction, no tip, no priority lane, and no path by which a single busy
block multiplies the price of a transaction by more than two.

**The chain never spends the pool.** Liquidity is the one thing a trading chain
must not be able to eat. In hypr the block producer is paid from sender fees plus
a capped subsidy whose issuance is minted, not drawn from reserves. Swaps credit
their fee to the reserves rather than extracting it. Every integer division in
the AMM floors toward the pool. The consequence is structural rather than
promissory: there is no code path from block production to a pool balance.

A third property, added because a chain nobody can reach is a diagram: **hypr is
recognised by ordinary crypto wallets.** It speaks `eth_*` JSON-RPC, publishes
EIP-3085 network descriptors, and accepts EIP-155 and EIP-1559 signed
transactions inside its own transaction format. MetaMask, Rabby, Frame, and any
EIP-1193 provider can hold a hypr balance and sign a transfer with no plugin, no
custom build, and no fork of the wallet.

---

## 1. The three constraints

| constraint | mechanism | where |
|---|---|---|
| fees are bounded and tiny | fixed unit schedule × hard-capped multiplier | `fees.rs` |
| pools are untouchable by the chain | fees and subsidy are credited from outside the pool; AMM rounds toward the pool | `exec.rs`, `amm.rs` |
| wallets accept the chain | `eth_*` RPC, EIP-3085 descriptors, EIP-155/1559 envelopes | `jsonrpc.rs`, `wallet.rs`, `evm.rs` |

Everything else in this document is the consequence of those three.

---

## 2. Units and addresses

One HYPR is **1,000,000 base units** — six decimals, the scale USDC and most
stablecoins use. That is the ledger representation: consensus, native RPC and
the explorer all use it.

Six rather than eighteen is deliberate:

- every AMM intermediate product (`amount_in × 10,000 × reserve`) stays inside
  `u128` with roughly 3×10⁴ of headroom, so the AMM needs no bignum library;
- the whole 21,000,000 HYPR supply fits in `u64`;
- consensus arithmetic stays exact with no bignum dependency in the state
  transition.

Wallets are a **presentation boundary**, not a consensus boundary. MetaMask
rejects a custom network unless `nativeCurrency.decimals` is exactly `18`, so
the EVM JSON-RPC surface presents **18-decimal wallet units**:

```text
1 HYPR          = 1,000,000 base units
1 HYPR          = 1,000,000,000,000,000,000 wallet units
1 base unit     = 1,000,000,000,000 wallet units
```

`WALLET_UNITS_PER_BASE = 10^12` is exact and lossless in both directions for
every amount the ledger can represent. An EVM envelope carries `value` in wallet
units; the node verifies the signature over the exact raw field, then converts to
base units. Amounts finer than one base unit are rejected rather than rounded.
Native `hypr_*` RPC, the explorer and the faucet remain six-decimal, and
`/chain.json` publishes both representations explicitly.

`0.20 HYPR` — twenty cents of a HYPR, the figure the genesis economy is built
around — is `200,000` base units, or `200,000,000,000,000,000` wallet units.

Addresses are **20 bytes**, displayed as `0x` followed by 40 lowercase hex
characters. `hypr1<hex>` is accepted anywhere an address is accepted as a
branded alias, and is what `pretty_addr` renders, but the canonical form on the
wire and in wallets is `0x`.

Two keys can own the same 20-byte address space, distinguished by the signature
scheme recorded in the transaction:

- **Ed25519** (native) — address is the first 20 bytes of `SHA-256(domain ‖ pubkey)`;
- **secp256k1** (wallet path) — address is the last 20 bytes of
  `Keccak-256(uncompressed pubkey)`, i.e. byte-for-byte the address MetaMask
  derives from the same private key.

---

## 3. Transactions

A transaction is a small fixed-layout structure: type, scheme, chain id, nonce,
sender, recipient, amount, maximum fee, payload, public key, signature.

There are eight native types — `transfer`, `issue_asset`, `create_pool`,
`add_liquidity`, `remove_liquidity`, `swap`, `transfer_asset`, and
`donate_to_pool` — and each carries a payload of at most 256 bytes with an
exact-length decoder. A payload that is one byte short or one byte long is
rejected; there is no trailing-data tolerance.

The signature covers the type, the scheme byte, the chain id, the nonce, the
sender, the recipient, the amount, the fee ceiling, and the payload. The scheme
byte being inside the signed message is what makes a signature produced for one
curve impossible to reinterpret under the other.

A second scheme, `typed_data`, carries the same authenticated fields for the
five actions a browser wallet signs: asset transfer, swap, add liquidity, remove
liquidity, and donate to pool. It is an EIP-712 signature over base units with
`from` inside the struct, described in §4.4. Plain HYPR transfers stay Ed25519
or EIP-155/1559.

**Transaction identity.** For a native transaction the id is
`SHA-256("hypr/tx/v2" ‖ signing_bytes ‖ pubkey ‖ sig)`. For a wallet
transaction it is `Keccak-256(raw_envelope)` — which is exactly the hash
MetaMask displays, so `eth_getTransactionHash` needs no mapping table and an
explorer shows the same string the wallet does.

---

## 4. The wallet path

### 4.1 Why an envelope instead of a translation layer

A naive compatibility story is "accept an Ethereum transaction and translate its
fields into a native transaction." That is a lying surface: the signature covers
RLP bytes, and the translation produces a *different* object that has to be
trusted to match. A block producer could pair a valid signature with mutated
fields and every signature check would still pass.

hypr stores the **raw signed envelope as the transaction payload**. Validation
re-derives the sender, recipient, amount, nonce, and chain id from those exact
bytes and refuses the transaction if any field disagrees with the object
carrying it. The binding check runs before anything touches state — in
`Tx::verify_sig()` and again, first thing, in `exec::apply_tx`.

Because the envelope *is* the payload, the signature covers what was signed, by
construction rather than by convention.

### 4.2 What is supported

- **EIP-155 legacy** — `[nonce, gasPrice, gasLimit, to, value, data, v, r, s]`
  with `v = chain_id * 2 + 35 + recovery_id`.
- **EIP-1559 type-2** — `0x02 ‖ rlp([chain_id, nonce, maxPriorityFeePerGas,
  maxFeePerGas, gasLimit, to, value, data, accessList, yParity, r, s])`.
- `value` is carried in **18-decimal wallet units** (`1 HYPR = 10^18`). The
  signature prehash covers the exact raw value; conversion to the ledger's
  six-decimal base units happens after authentication. A value that is not a
  multiple of `10^12` wallet units is refused rather than rounded.
- `data` **must be empty** and `to` **must be exactly 20 bytes**. hypr has no VM,
  so a contract call or a deployment is refused with an explicit error rather
  than silently treated as a transfer.

### 4.3 Gas semantics

`gasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`, and `accessList` are parsed,
validated for shape, and then **ignored for pricing** — they exist because
wallets require them. The chain charges its protocol constant.

They are not ignored entirely: a transaction's `maxFee` is `gasLimit × gasPrice`
and must be at least the protocol fee for the block. A wallet that offers zero
therefore gets `FeeTooLow` — which is the correct answer, not a bug.

The node quotes **4 gwei** in 18-decimal wallet units and a 21,000-gas estimate:

```text
21,000 × 4,000,000,000 / 10^12 = 84 base units
```

That clears the worst-case 80-base-unit transfer fee. Wallets reserve that much
when they check whether a send is affordable, and hypr debits only its own
constant. `eth_getTransactionCount(address, "pending")` includes queued mempool
transactions so a wallet can send a follow-up without reusing a nonce; `latest`
continues to report committed state.

### 4.4 Native actions as typed data

Swaps, liquidity, donations, and second-party asset transfers are native
transactions, not EVM calls. A browser wallet signs them with
`eth_signTypedData_v4` over this domain and struct:

```text
EIP712Domain(string name, string version, uint256 chainId)
HyprTx(uint8 txType, uint256 nonce, address from, address to,
       uint256 amountBaseUnits, uint256 maxFeeBaseUnits, bytes32 payloadHash)
```

The domain name is the protocol name `hypr` and the version is `1`, so mainnet
and testnet differ only by chain id. Amounts are **base units**, not the
18-decimal wallet facade and not floating-point display values. `from` is inside
the struct because a secp256k1 signature recovers two candidate keys; binding
the chosen address stops the other candidate from validating the same
signature. The node accepts the 64-byte `r ‖ s` signature, reconstructs the
message from the submitted transaction, and refuses any field mismatch.

The node publishes the exact domain from `signing_domain`, so a client never
hard-codes a separator. The CLI path is `hyprd typed --action ...`; the wallet
page uses the same message in the browser.

---

## 5. JSON-RPC

The node serves JSON-RPC 2.0 over HTTP at `/`. Two families:

**Ethereum surface** — `eth_chainId`, `eth_blockNumber`, `eth_getBalance`,
`eth_getTransactionCount`, `eth_gasPrice`, `eth_estimateGas`, `eth_getBlockBy*`,
`eth_getTransactionByHash`, `eth_getTransactionReceipt`, `eth_sendRawTransaction`,
`eth_feeHistory`, `net_version`, `net_peerCount`, `web3_clientVersion`,
`web3_sha3`.

Where the concept does not exist, the call **fails loudly** with `-32601` rather
than returning a plausible zero: `eth_call`, `eth_getCode` (returns `0x`),
`eth_sendTransaction`, `eth_sign`, `personal_sign`, `eth_subscribe`.

`eth_sendTransaction` is refused on principle: a node never holds user keys. Every
real wallet signs locally and submits `eth_sendRawTransaction` itself, so the
refusal is invisible to users and blocks the one path that would turn a node into
a custody risk.

**Native surface** — `status`, `chain`, `account`, `block`, `blocks`, `tx`,
`fee`, `pools`, `pool`, `assets`, `prices`, `signing_domain`, `mempool`,
`submit`, `simulate`, `validators`, `metrics`, `bridge_info`, `airdrop`,
`recent_txs`. Each is also reachable with a `hypr_` prefix so tooling can
namespace.

Every quantity is a JSON-RPC quantity (`0x`-prefixed minimal hex); every address
is `0x` + 40 hex. EVM quantities are denominated in 18-decimal wallet units;
native `hypr_*` quantities are six-decimal base units.

The HTTP layer carries CORS on every response including errors and preflight,
keep-alive with a 64-request cap and a 30-second idle timeout, a 16 KiB header
ceiling, a 2 MiB body ceiling, chunked encoding refused with `411`, a per-IP
token bucket at 200 req/s with a burst of 400, and a 512-connection cap.

---

## 6. Consensus

Proof of authority over a fixed validator set declared in genesis. No stake, no
delegation, no unbonding, no slashing.

- **Proposer selection** is a pure function of `(height, round)`: every node
  computes the same proposer with no communication and no randomness beacon. A
  round timeout rotates to the next validator.
- **Finality is immediate.** A block carrying approvals from more than two
  thirds of the validator weight is final. There is no fork choice, no reorg, no
  confirmation count, and no probabilistic tail.
- **Approvals travel with the block.** A proposal arrives carrying the
  proposer's signature, and every validator folds those signatures into its
  pending tally the moment the block checks out. The committed block is then
  stored with the full approval set, so finality is re-verifiable from the local
  log alone and a restarting node needs no peers to trust its own history.
- **Validation is independent.** A validator approves a block only after checking
  the previous hash, the height, the chain id, the timestamp skew, the fee
  multiplier, the transaction root, and the post-state root against its own
  execution of the block.
- **The block log is the chain.** Blocks are written to disk as they commit and
  replayed and re-verified on restart; a tampered byte on disk is a refusal to
  start, not a silent divergence.

Consensus overhead is a 64-byte signature per validator per block. That is what
keeps blockspace cheap enough to price in micro-units.

---

## 7. State

Accounts, issued assets, and pools live in `BTreeMap`s. That single choice is
what lets the state root be computed with no sorting pass and no dependence on
insertion order: two nodes that applied the same transactions always produce
byte-identical roots, and a block's `state_root` is a real commitment rather
than a fingerprint of how the map happened to be built.

The state root is a binary Merkle root over the sorted leaf set
(`SHA-256("hypr/leaf/v2" ‖ key ‖ value)`), with odd levels duplicating the last
node. Pools, accounts, asset metadata, and pool shares are all leaves.

---

## 8. Fees

A fixed schedule, in base units, at multiplier 1:

| operation | units | HYPR |
|---|---:|---:|
| transfer | 10 | 0.000010 |
| transfer asset | 10 | 0.000010 |
| donate to pool | 40 | 0.000040 |
| swap | 60 | 0.000060 |
| add liquidity | 80 | 0.000080 |
| remove liquidity | 80 | 0.000080 |
| issue asset | 200 | 0.000200 |
| create pool | 300 | 0.000300 |

The multiplier is a function of the parent block's utilisation against a target
of 60,000 units and a ceiling of 120,000 units, moving in integer steps within
`[1, 8]`. At the default parameters a transfer costs at most 80 base units —
`0.00008 HYPR`.

Fees are debited from the sender and credited to the proposer. They are never
routed through a pool, never burned into a reserve, and never used to pay for
issuance.

**Issuance** is a block subsidy of 1,000 base units per block, halving every
1,000,000 blocks, against a hard supply cap of 21,000,000 HYPR. It is newly
minted; it does not come from anywhere.

---

## 9. The AMM

Constant product, `x · y = k`, with a 0.30% swap fee.

Three properties matter:

1. **The fee accrues to the reserves.** On every swap, `k` grows. The pool only
   ever gets fatter as long as people trade against it. No treasury, no
   protocol-owned cut, no extraction path.
2. **Every rounding step floors toward the pool.** Integer division truncates in
   the pool's favour, so a sequence of arbitrarily many swaps can never grind a
   reserve down. The test suite hammers this.
3. **Initial liquidity is partly burned.** On pool creation, `min_liquidity`
   shares are minted to the zero address and never redeemable, which closes the
   first-LP donation attack.

`donate_to_pool` is a fourth, deliberately one-way operation: it debits the
sender's asset and credits the matching reserve without minting shares. It
raises `k` for every existing LP, and it mints nothing for the donor, so it
cannot dilute other LPs or buy a share of the pool.

Pool ids are `SHA-256("hypr/pool/v2" ‖ sorted_pair)`, so `(A,B)` and `(B,A)`
collapse to one pool.

---

## 10. Why the chain cannot eat the pool

This is the claim the design is built around, so it is worth stating as a
mechanism rather than a promise.

- **Block production** is paid from `sender fees + minted subsidy`. Neither
  term reads a pool. There is no code path from `settle_block` to a pool
  balance; `settle_block` credits the proposer's *account* and increments
  `total_supply`.
- **Swaps** move value between a reserve and a trader's account, and add the fee
  to the reserve. The protocol's share of a swap is zero by construction.
- **Liquidity operations** are the only other way a reserve changes, and they
  require the sender to hold pool shares.
- **Genesis** seeds the pool through the same `build_state` path that a live
  `CreatePool` uses, including the burned minimum liquidity.

The invariant is checked in the test suite directly: run the chain for dozens of
blocks with a live mempool and assert that `reserve_a` and `reserve_b` are
byte-identical to genesis.

---

## 11. The genesis economy

`hyprd init` writes a demo genesis that mints **0.60 HYPR** in total:

| allocation | amount | purpose |
|---|---:|---|
| pool | 0.20 HYPR | seeded against 0.20 USDX at 1:1 |
| native account | 0.20 HYPR | funds the pool, pays fees, can swap |
| wallet account | 0.20 HYPR | a secp256k1 key that can be imported into MetaMask |

The pool's 0.20 HYPR is the "twenty cents" the design is named around. A
production deployment replaces `Genesis::demo` with an explicit allocation file
through the same builder; nothing else changes.

A second asset, `USDX`, is issued at genesis with a supply of 1,000,000 base
units so the pool has a counter-asset and swaps are exercisable immediately.

The pool is the swap venue, not the wallet's price source. Testnet valuation
uses the fixed bridge rate — **1 ETH = 2,500,000 HYPR**, so 1 HYPR is
0.0000004 ETH — multiplied by a node-configured ETH/USD reference defaulting to
`$3,000`. That makes 1 HYPR **$0.0012**; at the default a 2,510 HYPR bridge
deposit is worth about **$3.01**. Swap quotes remain reserve-based.

---

## 12. Networking and storage

**Wire protocol.** `[type: u8][len: u32 BE][payload]`, with an 8 MiB frame
ceiling checked before a single byte is allocated. Peers exchange `HELLO`,
`GET_BLOCKS`, `BLOCKS`, `BLOCK`, `APPROVAL`, and `TX`.

**Transport model.** One reader thread per peer funnels into a single channel
consumed by the consensus loop; one writer thread per peer drains a bounded
queue. Sends are `try_send` and drop on a full queue, so a slow peer can never
back-pressure consensus. Consensus state is locked for the duration of a single
message or tick, never across I/O.

`HELLO` carries the sender's validator address. That is what lets a node count
*peers* rather than sockets: when two nodes dial each other, each holds two
links to the other and the tally still reads one peer, which is what an operator
and a monitoring system expect.

**Storage.** `blocks/` holds one canonical file per block, written as it commits.
Startup replays and re-verifies the whole log. The chain directory also holds
`genesis.json`, `node.key`, `wallet.json`, and `wallet-evm.json`.

---

## 13. Wallet integration

`GET /chain.json` publishes everything a wallet needs, generated from the live
chain parameters so it cannot drift:

```json
{
  "chainId": "0x1371",
  "chainName": "hypr",
  "nativeCurrency": { "name": "hypr", "symbol": "HYPR", "decimals": 18 },
  "rpcUrls": ["http://127.0.0.1:8545"],
  "blockExplorerUrls": ["http://127.0.0.1:8545"],
  "iconUrls": ["http://127.0.0.1:8545/logo-256.png"]
}
```

`18` is not a choice: MetaMask refuses `wallet_addEthereumChain` for any other
value. The descriptor therefore carries the wallet-facing view, while
`/chain.json` also states `native_decimals: 6` and
`wallet_units_per_base: 1000000000000` so an integrator can move between the
two without guessing.

Three ways in:

1. **The wallet page** at `/wallet` — a connect button, a `wallet_addEthereumChain`
   request built from the descriptor, live HYPR/USDX/LP balances, a testnet USD
   valuation at the bridge rate, and forms for send, swap, liquidity, donation
   and asset transfer.
2. **Chainlist** — `GET /chainlist.json` is a chainlist.org entry ready to submit.
3. **Manual** — every field is on `/chain.json` for copy-paste.

MetaMask displays only native HYPR. USDX and LP shares are native-chain objects,
so the wallet page reads them through `account`, `pools` and `prices`; the
18-decimal facade remains exactly the native-currency view. The typed actions
described in §4.4 are signed in the browser, which is what lets the page offer
swaps, liquidity and donations without ever holding a key.

`/bridge` is the testnet-only Sepolia page: it publishes the fixed rate, caps,
reserves, both chain heights, recent transfers, and the contribution summary
from the node's `bridge_info`. A deposit above a cap is accepted as a one-way
contribution: it mints no HYPR, stays in the reserve, and earns weight for a
future testnet airdrop. It is a status and calculator page, not a custody
surface, and the bridge itself is a separate operator service described in
`deploy/testnet/README.md`.

The explorer is search-first. One field resolves addresses, transaction hashes,
decimal block heights, and `hypr1…` aliases. The same page serves
`/address/<address>`, `/tx/<hash>`, `/block/<height>`, and `/airdrop` through the
History API. The airdrop view ranks contributions and shows one address's
weight, share, and eligibility.

The page also renders the network's icon from `/logo-256.png`, a stylised
lowercase `h` produced deterministically from a distance field
(`assets/render_logo.py`).

---

## 14. Security properties and known limits

**Properties.**

- Cross-chain replay is blocked: the chain id is inside every signed message and
  inside every envelope.
- Cross-scheme replay is blocked: the scheme byte is inside the Ed25519 message.
- Field substitution on the wallet path is blocked: fields are re-derived from
  the signed bytes before any state change.
- Signature malleability is not exploitable, because transaction identity is the
  envelope hash or a hash over the full signing bytes plus the signature, not a
  recoverable-key lookup.
- Adversarial input is bounded at every decoder: exact-length payloads, a
  depth-capped RLP reader, a frame ceiling checked before allocation, and HTTP
  body/header ceilings.

**Limits, stated plainly.**

- There is no VM. No contracts, no tokens beyond issued native assets, no
  composability. This is a deliberate scope decision, not an omission.
- Validator membership is fixed in genesis. Changing it is a coordinated genesis
  change, and there is no on-chain mechanism for it.
- Chain id 4977 was unoccupied in `ethereum-lists/chains` on 2026-11-15; 7701,
  the id used during initial development, belongs to Canto's testnet. The public
  testnet uses 4978, also verified free the same day. A collision makes
  signatures replayable on the other chain, so both ids are re-checked before a
  registry submission or mainnet launch.
- The chain is not yet registered on chainid.network. Until `eip155-4977.json`
  is merged there, wallets display "unknown network" on first connect and must
  be pointed at the descriptor served at `/chain.json`.
- The demo genesis is a demo. A production launch must supply an explicit
  allocation and should not use the seeded key files `init` writes.
- The testnet faucet is deliberately hot and deliberately blocked on chain 4977.
  Its keys and its 10,000,000 HYPR supply have no mainnet value.
- The Sepolia bridge is a trusted operator service, not a light client. One hot
  key pays Sepolia gas and hypr fees, caps apply per transfer and per day, there
  are no automatic refunds, and after downtime only the last 2,000 hypr blocks
  are reconciled. It is testnet-only and is not a mainnet design.
- A Cloudflare quick tunnel is a testnet convenience. It changes hostname on
  restart, so it is not a stable wallet endpoint and not a mainnet deployment.
- Browsers block `http://` RPC endpoints from `https://` pages. A production
  deployment serves the RPC behind TLS.

---

## 15. Parameters

| parameter | value |
|---|---|
| chain id | 4977 (`0x1371`) |
| testnet chain id | 4978 (`0x1372`) |
| native symbol | HYPR |
| native decimals (ledger, native RPC) | 6 |
| wallet decimals (EIP-3085, chainlist, `eth_*`) | 18 |
| wallet units per base unit | 1,000,000,000,000 (`10^12`) |
| gas quote (wallet units) | 4 gwei, 21,000 gas |
| block time (mainnet / testnet) | 5 s / 2 s |
| max transactions per block | 2 000 |
| fee target / cap (units) | 60 000 / 120 000 |
| fee multiplier range | 1 – 8 |
| swap fee | 30 bps |
| locked minimum liquidity | 1 000 shares |
| block subsidy | 1 000 base units, halving every 1 000 000 blocks |
| max supply | 21 000 000 HYPR |
| max clock skew | 2 s |
| transaction payload cap | 256 bytes |
| block format version | 2 |

---

## 16. What hypr is not

It is not an Ethereum sidechain, an L2, or an EVM clone. It does not try to run
contracts, host tokens, or absorb Ethereum's state. It borrows exactly one thing
from Ethereum — the signed-transaction envelope and the RPC vocabulary — because
that is the interface that turns "a chain" into "a chain your wallet already
knows how to use." The rest of the design is the opposite bet: fewer moving
parts, fixed costs, and a pool the machinery structurally cannot reach.
