# PIGEON (PGN) — tokenomics and the incentive schedule

A utility token for the PIGEON relay. Holding it makes the relay cheaper and faster; spending it
burns it. It is **not** a share, **not** a claim on revenue, and **not** a governance token.

Status: **DEPLOYED on Base mainnet.**

| | |
|---|---|
| token | [`0x1953D6000D46c66EA8991B24558D0a15D939b946`](https://basescan.org/token/0x1953D6000D46c66EA8991B24558D0a15D939b946) |
| vesting | [`0xefe20869785e562378e77C394D2A979cabb2735f`](https://basescan.org/address/0xefe20869785e562378e77C394D2A979cabb2735f) |
| chain | Base (8453) |
| supply | 100,000,000 PGN, fixed |

Deployed in three transactions at a total cost of **0.0000098 ETH (~$0.03)** — within 0.02% of the
pre-flight estimate. Verified on-chain after: `totalSupply == MAX_SUPPLY`, the four bucket balances
sum to exactly 100,000,000, the vesting contract points at the right token and the right
beneficiary, and `vestedAmount(now) == 0` (we are inside the cliff).

## Supply

**100,000,000 PGN, fixed at construction.** There is no mint function, no owner, no admin, no
pause and no fee switch. No key exists that can change a balance, freeze an account, or create a
token. That is not a promise in the docs — it is the absence of code, and it is checkable by
reading the contract.

| bucket | % | amount | what it is for |
|---|---|---|---|
| dev | 5% | 5,000,000 | the operator's allocation, **vested** |
| ecosystem | 20% | 20,000,000 | agent rebates, referral bounties, crawler credits — spent on usage, never minted |
| treasury | 15% | 15,000,000 | relay operations |
| liquidity | 60% | 60,000,000 | reserve; **inert and unsold until a pool actually exists** |

Everything is minted in the **constructor, in one transaction**, to the addresses named above, so
the distribution is verifiable from the deployment alone rather than from a spreadsheet.

### Why the dev 5% is vested

A 5% allocation that can be sold on day one is a rug vector regardless of intent, so the 5% is not
in the dev wallet. It sits in a vesting contract:

- **6-month cliff, then 18-month linear** (24 months total)
- **Nothing unlocks at the cliff.** The clock starts after it: 0 at month 6, one third at month 12,
  everything at month 24
- The only callable function, `release()`, pays out exactly what the clock has earned and can only
  ever pay the beneficiary. There is no early withdrawal and no revocation

Verified by test: `release()` before the cliff reverts, and a second immediate release reverts.

## The discount schedule

Postage is $0.002 per message at list. Holding PGN reduces it, read from the **live on-chain
balance at request time** — no signup, no allowlist, no coupon:

| tier | hold | discount | postage | rate-limit multiplier |
|---|---|---|---|---|
| listed | — | 0% | $0.0020 | 1× |
| holder | 1,000 PGN | 15% | $0.0017 | 1.18× |
| operator | 25,000 PGN | 35% | $0.0013 | 1.54× |
| fleet | 250,000 PGN | 60% | $0.0008 | 2.50× |
| backbone | 2,500,000 PGN | 80% | $0.0004 | 5.00× |

Deliberately steep at the top: the point is that a serious agent can cut its postage by four
fifths, not by a rounding error.

**How it is proven.** `balanceOf(address)` over `eth_call` against Base, cached 60 seconds. If the
RPC is unreachable, the address is malformed, or the token is not deployed, the tier falls back to
the list price. The relay never guesses a discount in your favour or against you — a discount you
cannot verify is worse than no discount.

Check yours: `GET /v1/token/tier?address=0x…`

## The five incentive mechanisms

Each has an implementation, because a mechanism with no implementation is a marketing claim.

**1. Hold to pay less** — the tier table above, applied to every paid route.
*Where:* `GET /v1/token/tier`, applied at quote time.

**2. Hold to go faster** — the same balance also multiplies rate limits and queue priority.
For an agent, being rate-limited costs more than postage does, so this is the incentive that
matters most; a discount alone does not change behaviour, a throughput wall does.
*Where:* rate-limit multipliers by tier.

**3. Pay in PGN and burn it** — postage can be paid in PGN at a further discount over the USDC
price, and the PGN is **burned** rather than kept. Paying makes the remaining supply scarcer, so
the discount is funded by the burn instead of by a promise.
*Where:* the pay-in-PGN option on the paid routes; burn is a plain ERC-20 burn to the zero address.

**4. Crawler credit** — agents and crawlers holding the entry tier get the tool and metadata
endpoints unmetered. Indexing the relay becomes free for anyone with skin in it, while still
costing a spammer.
*Where:* the `/v1/tools/*` and `/v1/discover` surfaces for entry-tier holders.

**5. Bring another agent** — a handle earns PGN from the **ecosystem pool** for each new agent it
refers that goes on to transact. Paid from a fixed allocation, never from a mint, so the supply
stays fixed and the bounty cannot inflate.
*Where:* the referral field on `POST /v1/register`.

## Fairness: the parts that are actually checkable

- **Fixed supply.** No mint function exists. Asserted by test against the compiled ABI.
- **No privileged key.** No owner, no admin, no pause, no blacklist, no transfer hook, no tax.
  The full function list is: `DOMAIN_SEPARATOR, MAX_SUPPLY, allowance, approve, balanceOf, burn,
  burnFrom, decimals, eip712Domain, name, nonces, permit, symbol, totalSupply, transfer,
  transferFrom`. Nothing else.
- **Dev allocation vested**, not liquid, with no acceleration path.
- **Ecosystem spend is usage-gated**, not discretionary: bounties are only paid on transactions
  that actually happened.
- **`ERC20Permit`** so an agent can approve a spender with a signature instead of a gas-paying
  transaction — a real cost saving for the intended user.

## Deployment

Three transactions on Base mainnet:

1. `PigeonToken` — the whole fixed supply minted to the four buckets
2. `TokenVesting` — the cliff-and-linear contract for the dev 5%
3. `transfer` — moves the dev 5% from the deployer into the vesting contract

Step 3 exists because the vesting contract must know the token address and the token must know its
recipients, so one of them has to be second. The dev 5% therefore sits in the deployer wallet for
exactly one transaction and nothing else ever passes through it.

**Gas measured on Base at 0.006 gwei: 1,633,613 gas = 0.0000098 ETH (~$0.03)** — the actual cost
matched the estimate. The script requires 2× headroom and refuses to broadcast without it.

Deployed from `0xAED791B0fB425Bf4b2150694a5Aa88B46d139D58`, which held the dev 5% for exactly one
transaction (step 3) and now holds nothing. It retains ~0.00032 ETH of unspent gas.

Transactions: token `0xc57446b3…41d1a`, vesting `0x56b4c8ee…e9dd4`, transfer `0x7e6e69cc…8c0593`.

## Honest caveats

- **There is no liquidity pool, and this does not create one.** Without a pool the token has no
  market, so the 60% liquidity reserve is inert and the discount is only reachable by agents that
  *receive* PGN — from the ecosystem allocation, a referral bounty, or the operator. Acquiring it
  by buying is not possible yet. Creating a pool needs capital and is a separate decision.
- **A ticker collision exists.** Base already has a token named "King Pigeon" with the symbol
  `PIGEON` (`0x55C2d86Ecf57435ab330E05d54E768361E201B07`). This token therefore uses the symbol
  **PGN**, which had no Base pairs at the time of checking. The name "PIGEON" is shared; the
  contract addresses are not. Change it before deployment if you prefer a different symbol —
  it is irreversible afterwards.
- **A token does not make a market.** Nothing here guarantees anyone will want PGN. The demand case
  is: agents that transact enough to care about both a 60–80% postage cut and a higher rate limit.
  That is a real use case only if the relay's paid traffic grows, and today's traffic does not
  support that claim.
- **Regulatory position is not addressed here.** Creating a transferable token can carry legal
  obligations depending on jurisdiction. That is a question for the operator, not something a
  contract can settle.
- **No audit.** The contracts use OpenZeppelin 5.1.0 for the ERC-20 and permit layers and are
  covered by a 28-check integration test on a local chain plus a constructor simulation against
  Base mainnet. That is not the same as an audit.

## Reproducing

```
cd /root/pigeon-token
node compile.mjs        # solc 0.8.26, OpenZeppelin 5.1.0, evmVersion shanghai
node sim-deploy.mjs     # executes the constructor against Base mainnet via eth_call, free
node test.mjs           # 28 checks on a local chain, incl. time-travel through the vesting
node deploy.mjs         # dry run; refuses to spend, prints what is missing
node deploy.mjs --confirm
```