CRUMBS (ERC‑20)

Utility token for Upvotes/Tips, Flags, Bonds, Vault flows, and Node Rewards

Status: Concept for v0 / v0.1 Last updated: YYYY‑MM‑DD

---

1) Purpose & Scope

CRUMBS is the protocol’s utility token used to:

• pay for Upvotes (counted weight + tips),

• pay fixed Dislike/DownVote amounts,

• post Flags and Publish Bonds (escrow & slashing),

• fund the Vault, which allocates a share to Node Rewards.

Design goals: simple, predictable, cypherpunk‑friendly. No transfer taxes, no rebasing, no hidden hooks. Support permit to minimize approvals friction in the UI.

---

2) High‑Level Spec

• Standard: ERC‑20

• Symbol / Name: CRUMBS / Crumpet CRUMBS

• Decimals: 18

• Total Supply: 1,000,000,000 CRUMBS (fixed cap)

• Minting: one‑time mint at deployment; no further mint

• Burning: optional burn() (user‑initiated only); no protocol auto‑burns

• Fees / Rebasing: none

• Permit: EIP‑2612 (ERC20Permit) for gas‑efficient approvals

• Meta‑tx: optional Permit2 supported at the dApp layer (no token change needed)

• Governance: token itself is not governance‑bound; DAO uses a timelock controller in Config. (If token voting is desired later, see §10 “Optional: Votes Extension”.)

• Upgradability: non‑upgradeable bytecode; changes require a new deployment (intentionally simple)

---

3) Responsibilities & Non‑Goals

Responsibilities

• Hold balances accurately and predictably.

• Provide permit for UX (approve‑less interactions).

• Expose standard ERC‑20 events for analytics.

Non‑Goals

• Enforce protocol rules (Actions/Disputes/Vault handle that).

• Transfer taxes, blocklists, freeze mechanics (intentionally omitted).

---

4) Supply & Initial Distribution

• Fixed cap: 1_000_000_000 * 10^18 at deployment.

• Constructor mints to a set of genesis recipients (addresses and amounts provided at deployment).

• The deployer renounces any mint authority immediately (there is none after constructor).

Constructor arguments (recommended):

solidityCopyEditconstructor(
  address[] memory recipients,
  uint256[] memory amounts
) ERC20("Crumpet CRUMBS", "CRUMBS") ERC20Permit("Crumpet CRUMBS") {
  // sum(amounts) must equal 1_000_000_000e18
  for (uint256 i=0; i<recipients.length; i++) {
    _mint(recipients[i], amounts[i]);
  }
}

Allocation is a deployment‑time decision (e.g., DAO treasury, node‑incentives multisig, ecosystem fund, contributors). This doc does not prescribe percentages; the deployment script enforces exact total‑supply sum.

---

5) Interfaces

Core (ERC‑20 + Permit)

solidityCopyEditfunction name() public view returns (string)
function symbol() public view returns (string)
function decimals() public pure returns (uint8) // 18
function totalSupply() public view returns (uint256)
function balanceOf(address) public view returns (uint256)
function transfer(address to, uint256 amount) public returns (bool)
function allowance(address owner, address spender) public view returns (uint256)
function approve(address spender, uint256 amount) public returns (bool)
function transferFrom(address from, address to, uint256 amount) public returns (bool)

// EIP-2612
function permit(
  address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s
) external
function nonces(address owner) public view returns (uint256)
function DOMAIN_SEPARATOR() public view returns (bytes32)

Optional burn:

solidityCopyEditfunction burn(uint256 amount) public
function burnFrom(address account, uint256 amount) public

---

6) Integrations (how other modules use CRUMBS)

• Actions: pulls CRUMBS from the caller via transferFrom (or permit + transferFrom) for:

  • Upvotes (user → Vault & Author),

  • Dislike/DownVote (user → Vault),

  • Flags (user → Disputes escrow).

• ArticlesRegistry: pulls Publish Bond from author into Disputes escrow on publish.

• Disputes: refunds flaggers (escrow → flagger) and slashes/returns Publish Bonds.

• Vault: holds protocol funds; NodeRewards pulls allocations for epoch payouts.

All integrations use SafeERC20 and never assume transfer hooks.

---

7) Security Posture

• No owner‑only mint, no pausable transfers, no blacklists — avoids governance capture of balances.

• Permit conforms to EIP‑2612; domain separator includes chainid.

• Reentrancy: ERC‑20 itself has no external calls; protocol modules that transfer tokens are guarded.

• No callbacks (not ERC‑1363) to minimize attack surface.

---

8) Gas & UX Considerations

• Permit path reduces the “approve + call” two‑tx pattern to a single tx for first‑time users.

• Frontends should prefer Permit2 (off‑token) if wallets support it; token doesn’t need to change.

• No Votes extension by default keeps storage small and transfers cheap.

---

9) Reference Implementation (Solidity, OZ‑based)

solidityCopyEdit// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {ERC20} from "solmate/tokens/ERC20.sol";            // or OZ ERC20
import {ERC20Permit} from "solmate/tokens/ERC20Permit.sol"; // or OZ ERC20Permit
import {Ownable} from "solady/auth/Ownable.sol";            // optional for rescue

contract CRUMBS is ERC20, ERC20Permit, Ownable {
    uint256 public constant MAX_SUPPLY = 1_000_000_000e18;

    constructor(address[] memory recipients, uint256[] memory amounts)
        ERC20("Crumpet CRUMBS", "CRUMBS", 18)
        ERC20Permit("Crumpet CRUMBS")
    {
        require(recipients.length == amounts.length, "LEN_MISMATCH");
        uint256 sum;
        for (uint256 i; i < recipients.length; i++) {
            _mint(recipients[i], amounts[i]);
            sum += amounts[i];
        }
        require(sum == MAX_SUPPLY, "SUPPLY_MISMATCH");
        _initializeOwner(msg.sender); // optional: for rescue only; no mint rights
    }

    // OPTIONAL: Rescue tokens accidentally sent to this contract (not CRUMBS),
    // guarded by DAO timelock if you wire ownership to the timelock.
    function rescue(address token, address to, uint256 amount) external onlyOwner {
        require(token != address(this), "NO_SELF");
        (bool ok, bytes memory data) = token.call(abi.encodeWithSignature("transfer(address,uint256)", to, amount));
        require(ok && (data.length == 0 || abi.decode(data, (bool))), "RESCUE_FAIL");
    }
}

You can swap Solmate for OpenZeppelin equivalents. Keep MAX_SUPPLY enforced and no mint functions after constructor.

---

10) Optional: Votes Extension (if governance wants token voting)

If the DAO later decides CRUMBS should also support on‑chain token voting:

• Use OZ ERC20Votes (checkpointing) instead of base ERC‑20.

• Trade‑off: extra storage writes on transfer (vote checkpoints) → higher gas.

• This is not required for v0/v0.1 (Config + timelock governs parameters).

• Migration path: deploy CRUMBS‑V2 (Votes) and a one‑time swap contract if community consents.

---

11) Deployment & Wiring

1. Prepare genesis allocation file:

   jsonCopyEdit{
     "recipients": ["0xDAO...", "0xTreasury...", "0xEcosystem...", "0xContributors..."],
     "amounts":    ["400000000000000000000000000", "...", "...", "..."] // sum=1e9e18
   }

2. Deploy CRUMBS with those arrays.

3. Wire Config with the CRUMBS address; set module addresses (Vault, Actions, Disputes, Registry).

4. Transfer any ownership (if kept) to DAO Timelock; or renounce if you don’t need rescue().

---

12) Testing Checklist

Unit

• Total supply equals 1e9e18; cannot mint again.

• transfer, approve, transferFrom semantics and events.

• permit (EIP‑2612) domain separator, nonces, replay protection.

• burn (if enabled): balance and totalSupply decrease; events emitted.

• rescue (if enabled): cannot rescue CRUMBS itself; ERC‑20 return‑value patterns handled.

Integration

• Actions upvote/dislike/downvote: transferFrom with/without permit; balances reconcile to Author/Vault.

• Registry publish: bond pulled to Disputes escrow.

• Disputes: refunds and slashes move funds correctly; no stuck balances.

Property/Fuzz

• Invariants: sum of balances == totalSupply (± burned).

• Random sequence of actions/refunds maintains conservation.

---

13) Operational Guidance

• Bridging: if Kasplex is an L2, deploy a canonical bridge/minter on L1 only if needed later. For v0/v0.1, keep supply purely on L2 to reduce complexity.

• Exchanges: token has no transfer taxes and no blacklists, simplifying listings (if ever desired).

• Custody: DAO treasury should be a multisig (or timelock) separate from module addresses.

---

14) Acceptance Criteria

• Fixed supply (1B) minted at genesis; no further mint.

• ERC‑20 and EIP‑2612 pass conformance tests.

• Works seamlessly with Actions/Disputes/Registry/Vault flows via SafeERC20.

• Frontend can use permit to avoid first‑time approvals.

---

15) Changelog

• v1: Initial CRUMBS ERC‑20 with fixed supply, permit, optional burn/rescue; no taxes, no hooks.