Config (DAO‑Timelocked Parameters & Safety Rails)

Status: Finalized for v0 / v0.1 Owners: Governance Ops · Contracts Team · Node Operators WG Last updated: YYYY‑MM‑DD

---

1) Purpose & Scope

The Config module is the single on‑chain source of parameters that govern economics, dispute timing, reward splits, and operational limits. It is owned by a timelocked governance executor so changes are transparent and predictable.

ELI5: Config is the settings page for the whole system. The DAO turns the knobs, and after a short waiting period the new settings take effect, so everyone can see changes coming.

Used by: ArticlesRegistry, Actions, Disputes, Vault, NodeRewards, CIN nodes (read‑only), and UIs.

---

2) Responsibilities & Non‑Goals

Responsibilities

• Store all tunable parameters with sane bounds and change‑rate limits.

• Emit ConfigChanged events with old/new values.

• Provide a canonical hash of all active parameters so nodes can tag snapshots.

• Own addresses for core modules (CRUMBS, Vault, NodeRewards, Disputes, ArticlesRegistry).

Non‑Goals

• Implement timelock logic itself (use OZ TimelockController, or equivalent).

• Hold funds or perform economic calculations.

---

3) Parameter Inventory (v0 / v0.1)

All values are DAO‑timelocked. Defaults shown; update via governance if needed.

3.1 Actions (voting amounts & splits)

• MIN_UP (CRUMBS) — 10

• MAX_UP_WEIGHT (CRUMBS) — 100 (cap per upvote for counted weight)

• DISLIKE (CRUMBS) — 25

• DOWNVOTE (CRUMBS) — 50

• VAULT_BPS_ON_COUNTED (bps) — 2000 (20% of counted upvote to Vault; tip goes 100% to author)

3.2 Disputes & Bonds

• FLAG_FEE (CRUMBS) — 25

• FLAGS_TO_OPEN — 3

• GRACE_SECONDS — 10 days (time‑based, not blocks)

• PUBLISH_BOND (CRUMBS) — 100

Fairness rule: Disputes records graceSecondsAtPublish when onPublish is called. Later changes to GRACE_SECONDS do not retroactively affect existing publications.

3.3 Vault & Node Rewards

• REWARDS_BPS_MAX (bps) — 4000 (≤40% of net inflow per epoch to node rewards)

• Splits (bps of rewards allocation):

  • REWARDS_SPLIT_UPTIME_BPS — 4000 (40%)

  • REWARDS_SPLIT_BUILD_BPS — 4000 (40%)

  • REWARDS_SPLIT_SERVE_BPS — 2000 (20%) (set to 0 if serve receipts are disabled)

• Epoch cadence: EPOCH_SECONDS — 7 days

• Attestation policy:

  • ATTEST_MIN_BUILDERS — 2 (≥2 builders must match the same root)

  • ATTEST_MIN_PEERS — 3 (2‑of‑3 agreement target)

  • SERVE_MAX_RECEIPTS_PER_NODE — cap (anti‑gaming)

• Language weights (optional): LANG_WEIGHTS[code] (e.g., en:3, es:2, …), MIN_LANG_WEIGHT:1

3.4 Addresses (immutable after wiring unless DAO migrates)

• CRUMBS (ERC‑20)

• VAULT

• NODEREWARDS

• DISPUTES

• ARTICLESREGISTRY

• DAO_EXECUTOR (TimelockController or multisig executor)

3.5 Operational toggles (safety rails)

• PAUSE_ACTIONS (bool) — false by default (emergency‑only; see §7)

• PAUSE_FLAGS (bool) — false by default

• (No pause for ArticlesRegistry to preserve publish availability.)

---

4) Events & Views

solidityCopyEditevent ConfigChanged(bytes32 indexed key, bytes oldVal, bytes newVal);
event AddressesWired(address crumbs, address vault, address nodeRewards, address disputes, address articlesRegistry);
event Paused(bytes32 indexed what, bool value);

// Snapshot parameter hash for nodes/UIs
function paramsHash() external view returns (bytes32);

// Convenience getters
function getActionsParams() external view returns (
  uint256 MIN_UP,
  uint256 MAX_UP_WEIGHT,
  uint256 DISLIKE,
  uint256 DOWNVOTE,
  uint256 VAULT_BPS_ON_COUNTED
);

function getDisputesParams() external view returns (
  uint256 FLAG_FEE,
  uint256 FLAGS_TO_OPEN,
  uint256 GRACE_SECONDS,
  uint256 PUBLISH_BOND
);

function getRewardsParams() external view returns (
  uint256 REWARDS_BPS_MAX,
  uint256 REWARDS_SPLIT_UPTIME_BPS,
  uint256 REWARDS_SPLIT_BUILD_BPS,
  uint256 REWARDS_SPLIT_SERVE_BPS,
  uint256 EPOCH_SECONDS,
  uint256 ATTEST_MIN_BUILDERS,
  uint256 ATTEST_MIN_PEERS,
  uint256 SERVE_MAX_RECEIPTS_PER_NODE
);

paramsHash() is the keccak256 of a canonical abi‑encoding of all active parameters. CIN nodes store this in snapshot metadata for auditability.

---

5) Governance & Timelock Model

• Use OpenZeppelin TimelockController (or equivalent).

• Flow: propose → queue (min delay) → execute, emitting ConfigChanged on success.

• Recommended delay: 48–72 hours (DAO to decide).

• For operational toggles (pauses), require the same timelock unless DAO creates a separate emergency role (see §7).

Change‑rate safety rails (recommended)

• Per update, cap deltas to avoid shocks:

  • MIN_UP/MAX_UP_WEIGHT/DISLIKE/DOWNVOTE — max ±50%

  • FLAG_FEE/PUBLISH_BOND — max ±50%

  • GRACE_SECONDS — max ±2x / ÷2

  • Rewards BPS & splits — must still sum to ≤10,000 BPS and each split ≤10,000 BPS

• Hard bounds:

  • MIN_UP ≥ 1 CRUMBS, MAX_UP_WEIGHT ≥ MIN_UP

  • DISLIKE > 0, DOWNVOTE > DISLIKE

  • REWARDS_BPS_MAX ≤ 5000 (≤50%)

  • EPOCH_SECONDS ≥ 1 day, ≤ 30 days

If a proposed value violates bounds, the setter reverts and must be re‑proposed.

---

6) Solidity Sketch

solidityCopyEditcontract Config is ReentrancyGuard {
  // ---- addresses ----
  address public CRUMBS;
  address public VAULT;
  address public NODEREWARDS;
  address public DISPUTES;
  address public ARTICLESREGISTRY;
  address public immutable DAO_EXECUTOR; // TimelockController

  modifier onlyDAO() { require(msg.sender == DAO_EXECUTOR, "DAO_ONLY"); _; }

  // ---- actions ----
  uint256 public MIN_UP           = 10e18;
  uint256 public MAX_UP_WEIGHT    = 100e18;
  uint256 public DISLIKE          = 25e18;
  uint256 public DOWNVOTE         = 50e18;
  uint256 public VAULT_BPS_ON_COUNTED = 2000; // 20%

  // ---- disputes ----
  uint256 public FLAG_FEE         = 25e18;
  uint256 public FLAGS_TO_OPEN    = 3;
  uint256 public GRACE_SECONDS    = 10 days;
  uint256 public PUBLISH_BOND     = 100e18;

  // ---- rewards ----
  uint256 public REWARDS_BPS_MAX  = 4000;
  uint256 public REWARDS_SPLIT_UPTIME_BPS = 4000;
  uint256 public REWARDS_SPLIT_BUILD_BPS  = 4000;
  uint256 public REWARDS_SPLIT_SERVE_BPS  = 2000;
  uint256 public EPOCH_SECONDS    = 7 days;
  uint256 public ATTEST_MIN_BUILDERS = 2;
  uint256 public ATTEST_MIN_PEERS    = 3;
  uint256 public SERVE_MAX_RECEIPTS_PER_NODE = 10000;

  // ---- language weights ----
  mapping(bytes32 => uint256) public LANG_WEIGHTS;
  uint256 public MIN_LANG_WEIGHT = 1;

  // ---- toggles ----
  bool public PAUSE_ACTIONS = false;
  bool public PAUSE_FLAGS   = false;

  constructor(address timelock) { DAO_EXECUTOR = timelock; }

  // address wiring
  function wireAddresses(address crumbs, address vault, address nodeRewards, address disputes, address reg) external onlyDAO {
    CRUMBS = crumbs; VAULT = vault; NODEREWARDS = nodeRewards; DISPUTES = disputes; ARTICLESREGISTRY = reg;
    emit AddressesWired(crumbs, vault, nodeRewards, disputes, reg);
  }

  // setters (sample)
  function setMinUp(uint256 v) external onlyDAO { _bound(v >= 1e18, "MIN_UP_LOW"); _emitChange("MIN_UP", abi.encode(MIN_UP), abi.encode(v)); MIN_UP = v; }
  function setMaxUpWeight(uint256 v) external onlyDAO { _bound(v >= MIN_UP, "MAX<MIN"); _emitChange("MAX_UP_WEIGHT", abi.encode(MAX_UP_WEIGHT), abi.encode(v)); MAX_UP_WEIGHT = v; }
  function setVaultBpsOnCounted(uint256 v) external onlyDAO { _bound(v <= 5000, "BPS_HIGH"); _emitChange("VAULT_BPS_ON_COUNTED", abi.encode(VAULT_BPS_ON_COUNTED), abi.encode(v)); VAULT_BPS_ON_COUNTED = v; }
  // ... analogous setters for all others ...

  function setPauseActions(bool v) external onlyDAO { PAUSE_ACTIONS = v; emit Paused("ACTIONS", v); }
  function setPauseFlags(bool v)   external onlyDAO { PAUSE_FLAGS = v; emit Paused("FLAGS", v); }

  // param hash for nodes
  function paramsHash() external view returns (bytes32) {
    return keccak256(abi.encode(
      MIN_UP, MAX_UP_WEIGHT, DISLIKE, DOWNVOTE, VAULT_BPS_ON_COUNTED,
      FLAG_FEE, FLAGS_TO_OPEN, GRACE_SECONDS, PUBLISH_BOND,
      REWARDS_BPS_MAX, REWARDS_SPLIT_UPTIME_BPS, REWARDS_SPLIT_BUILD_BPS, REWARDS_SPLIT_SERVE_BPS,
      EPOCH_SECONDS, ATTEST_MIN_BUILDERS, ATTEST_MIN_PEERS, SERVE_MAX_RECEIPTS_PER_NODE,
      MIN_LANG_WEIGHT, PAUSE_ACTIONS, PAUSE_FLAGS
      // Note: LANG_WEIGHTS mapping omitted from hash for gas; instead include in node snapshot metadata by enumerating non-defaults off-chain.
    ));
  }

  function _emitChange(string memory key, bytes memory oldv, bytes memory newv) internal {
    emit ConfigChanged(keccak256(bytes(key)), oldv, newv);
  }

  function _bound(bool ok, string memory err) internal pure { require(ok, err); }
}

Note: Modules should read toggles (e.g., PAUSE_ACTIONS, PAUSE_FLAGS) and revert with a clear error (Paused()) when set. Defaults are false.

---

7) Safety Rails & Emergency Behavior

• Pauses (optional):

  • PAUSE_ACTIONS: blocks upvote/dislike/downvote entrypoints.

  • PAUSE_FLAGS: blocks flag in Actions (Disputes refunds & bond functions remain available).

  • Registry is never paused (publishing should remain permissionless).

• Timelock applies to enabling/disabling pauses (no “instant kill switch” by default). If the DAO wants an emergency guard, deploy a separate, limited‑scope guardian that can toggle only these two booleans with a shorter delay (e.g., 6–12h), and require a regular timelock to re‑enable actions.

• Backwards compatibility:

  • Changes to economics take effect immediately after execution for new actions.

  • GRACE_SECONDS changes apply prospectively; Disputes stores the value at publish time for each CID.

---

8) CIN Nodes & paramsHash

• Nodes should include paramsHash() in snapshot metadata and expose it via /v1/snapshot/{lang}/latest.

• UIs can show “Index built under Config hash 0x…” to increase transparency.

• When ConfigChanged fires, nodes tag the next snapshot with the new hash.

---

9) Testing Checklist

• Bounds & guards: each setter enforces min/max and rejects out‑of‑range values.

• Timelock: only DAO_EXECUTOR can call setters; direct calls revert.

• Events: ConfigChanged emits accurate old/new values; Paused fires on toggles.

• Hash stability: identical parameter sets produce the same paramsHash.

• Module reactions:

  • Actions respects PAUSE_ACTIONS/PAUSE_FLAGS.

  • Disputes reads GRACE_SECONDS only at onPublish and persists it per CID.

  • NodeRewards splits always sum to ≤ allocation.

---

10) Operational Playbooks

• Adjusting Economics: propose updated MIN/ MAX/ splits → timelock executes → frontends auto‑read & display new values.

• Dispute Window Change: propose new GRACE_SECONDS → affects future publishes; existing CIDs keep their stored grace.

• Turning Off Serve Rewards: set REWARDS_SPLIT_SERVE_BPS = 0; redistribute to other buckets by raising their BPS values (ensure total ≤10,000).

• Language Weights: submit a batch transaction updating LANG_WEIGHTS[code] for selected languages.

---

11) Acceptance Criteria

• All dependent modules compile against Config interface and read parameters on use.

• Timelocked updates change behavior without redeploys and with clear event traces.

• Pauses, if toggled, halt only intended entrypoints and leave publishing & refunds unimpaired.

• Nodes expose and roll forward paramsHash in snapshots.

---

12) Changelog

• v1: Initial Config with DAO‑timelocked parameters, evented updates, parameter hash, and optional pause toggles.