Token and Fee Contracts

Token & Fee Contracts

**Referenced Files in This Document** - [SVRToken.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SVRToken.sol) - [SigvaraEpochFees.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraEpochFees.sol) - [SVR.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/archive/token-launch/src/SVR.sol) - [token.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/token.md) - [tokenomics.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/archive/token-launch/docs/tokenomics.md) - [SigvaraPublicSale.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/archive/token-launch/src/SigvaraPublicSale.sol) - [TeamVesting.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/archive/token-launch/src/TeamVesting.sol) - [TreasuryVesting.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/archive/token-launch/src/TreasuryVesting.sol) - [FeeOnTransfer.t.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/test/FeeOnTransfer.t.sol) - [SigvaraEpochFees.t.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/test/SigvaraEpochFees.t.sol) - [DeployEpochFees.s.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/script/DeployEpochFees.s.sol) - [0005-governance-and-emergency-powers.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0005-governance-and-emergency-powers.md)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document explains the tokenomics and fee management design centered on the SVR token and the SigvaraEpochFees registry. It covers:

• The role of SVR as a bond and fee asset for agent activation, oracle participation, and epoch coverage.
• How epoch fees are collected, routed, and distributed across protocol stages.
• The relationship between token holdings and protocol participation rights.
• Special token behaviors such as fee-on-transfer handling and rebasing restrictions.
• Legacy launch contracts and migration considerations.
• Economic modeling of supply dynamics, inflation/deflation pressures, and governance-tunable parameters.

SigvaraEpochFees has never been deployed. It is left out of the Arc mainnet launch and of the first audit, script/DeployEpochFees.s.sol refuses to run on chain 5042, and its fee would be zero at launch. The fee flow below describes the contract in the repository, not a live deployment.

Project Structure

The relevant code is split between current protocol contracts and legacy token-launch artifacts:

• Current protocol:
  • src/SVRToken.sol: testnet mintable stake token with faucet controls.
  • src/SigvaraEpochFees.sol: upgradeable fee registry that gates oracle scoring epochs and distributes collected fees.
• Archived token launch (never deployed):
  • archive/token-launch/src/SVR.sol: the archived fixed-supply token design. The mainnet token is Tolly's TollyToken (docs/token.md).
  • archive/token-launch/src/SigvaraPublicSale.sol, TeamVesting.sol, TreasuryVesting.sol: public sale and vesting infrastructure.
• Documentation:
  • docs/token.md: canonical token description, mainnet parameters, and utility rules.
  • archive/token-launch/docs/tokenomics.md: v0.3 token economics specification.

graph TB
subgraph "Current Protocol"
SVRToken["SVRToken.sol<br/>Testnet stake token"]
EpochFees["SigvaraEpochFees.sol<br/>Fee registry + distribution"]
end
subgraph "Shelved Launch Design"
SVRMain["SVR.sol<br/>Archived fixed-supply design, never deployed"]
PublicSale["SigvaraPublicSale.sol<br/>Fixed-price sale"]
TeamVest["TeamVesting.sol<br/>20% team vest"]
TreasuryVest["TreasuryVesting.sol<br/>40% treasury vest"]
end
Docs["docs/token.md<br/>Canonical token page"]
Econ["archive/token-launch/docs/tokenomics.md<br/>v0.3 tokenomics"]
EpochFees --> SVRToken
EpochFees --> SVRMain
PublicSale --> SVRMain
TeamVest --> SVRMain
TreasuryVest --> SVRMain
Econ --> SVRMain

Loading

Diagram sources

• SVRToken.sol:1-43
• SigvaraEpochFees.sol
• SVR.sol:1-75
• SigvaraPublicSale.sol:1-193
• TeamVesting.sol:1-31
• TreasuryVesting.sol:1-27
• token.md
• tokenomics.md:1-166

Section sources

• SVRToken.sol:1-43
• SigvaraEpochFees.sol
• SVR.sol:1-75
• token.md
• tokenomics.md:1-166

Core Components

• SVRToken (testnet):
  • Mintable by owner; includes a permissionless faucet with per-call cap and cooldown to prevent unbounded inflation during testing.
• SigvaraEpochFees (fee registry):
  • Stores prepaid balances per agent identity hash.
  • Oracle charges one epoch fee per agent included in scoring runs, at most once per agent per epoch.
  • Distributes collected fees according to a three-stage model: Bootstrap (100% reward pool), Transition (80% reward pool, 20% burn), Mature (50% reward pool, 50% burn).
  • Governance can set epoch fee, stage, reward pool address, epoch length and the operator registry.
• SVR.sol (archived, never deployed):
  • Fixed total supply of 1 billion tokens.
  • No mint, no owner, no upgrade path.
  • Allocations at TGE in this design: treasury, team, ecosystem, public sale, liquidity. The current plan has none of these: SVR launches as Tolly's TollyToken with no team or treasury allocation, vesting or sale (docs/token.md).
• Shelved launch contracts (never deployed):
  • Public sale: fixed-price purchase with hard/soft caps, claim/refund flows, unsold tokens burned.
  • Vesting: team (4-year linear, 1-year cliff) and treasury (5-year linear) release schedules.

Section sources

• SVRToken.sol:1-43
• SigvaraEpochFees.sol
• SVR.sol:1-75
• SigvaraPublicSale.sol:1-193
• TeamVesting.sol:1-31
• TreasuryVesting.sol:1-27

Architecture Overview

The fee flow connects operators, agents, the oracle, and the fee registry. Operators or applications prepay SVR for an agent’s epoch coverage. The oracle charges per inclusion; collected fees are swept into either the reward pool or burned based on the active stage.

sequenceDiagram
participant Operator as "Operator/App"
participant Fees as "SigvaraEpochFees"
participant Oracle as "Oracle"
participant RewardPool as "Reward Pool"
participant Burn as "Burn Address"
Operator->>Fees : "depositFor(didHash, amount)"
Note over Fees : "Credit balance[didHash] with tokens received"
Oracle->>Fees : "chargeEpoch(didHash)"
alt Agent covered
Fees-->>Oracle : "charged = true"
Fees->>Fees : "collected += epochFee"
else Agent uncovered
Fees-->>Oracle : "revert InsufficientBalance"
else Already charged this epoch
Fees-->>Oracle : "revert AlreadyCharged"
end
Fees->>Fees : "distributeFees()"
alt Stage Bootstrap
Fees->>RewardPool : "transfer(pool share)"
else Stage Transition
Fees->>RewardPool : "transfer(80%)"
Fees->>Burn : "transfer(20%)"
else Stage Mature
Fees->>RewardPool : "transfer(50%)"
Fees->>Burn : "transfer(50%)"
end

Loading

Diagram sources

• SigvaraEpochFees.sol:214-334

Section sources

• SigvaraEpochFees.sol

Detailed Component Analysis

SVRToken (Testnet Stake Token)

Responsibilities:

• Provide a mintable ERC-20 for testnet operations.
• Enforce a per-call cap and cooldown on the faucet to avoid inflation abuse.
• Allow owner-only minting for operator onboarding and faucet funding.

Key behaviors:

• Faucet enforces maximum amount per call and time-based cooldown per caller.
• Owner can mint arbitrary amounts for testnet needs.

flowchart TD
Start(["faucet(amount)"]) --> CheckCap["Check amount <= FAUCET_CAP"]
CheckCap --> |No| RevertCap["Revert max per call"]
CheckCap --> |Yes| CheckCooldown["Check lastFaucetUse + COOLDOWN"]
CheckCooldown --> |Active| RevertCooldown["Revert cooldown active"]
CheckCooldown --> |OK| UpdateTime["Update lastFaucetUse"]
UpdateTime --> Mint["mint(msg.sender, amount)"]
Mint --> End(["Done"])

Loading

Diagram sources

• SVRToken.sol:22-42

Section sources

• SVRToken.sol:1-43

SigvaraEpochFees (Fee Registry and Distribution)

Responsibilities:

• Maintain prepaid balances per agent identity hash.
• Gate oracle scoring inclusion via charge checks.
• Distribute collected fees according to governance-controlled stage.

Key behaviors:

• Funding: anyone can deposit for any registered agent; balances reflect actual tokens received (supports fee-on-transfer tokens).
• Withdrawals: only the agent’s operator can withdraw unspent prepaid fees.
• Charging: oracle-only; reverts if insufficient balance; returns true when charged. A second charge for the same agent in the same epoch reverts AlreadyCharged, and a caller treats that as paid. An epoch is block.timestamp / epochLength, with epochLength at least one hour; until it is set, charging refuses once a fee is set. When an operator registry is configured the caller must also be an active operator in it, or its signer. With a fee of 0 the call is a no-op that returns true.
• Distribution: sweep collected fees to reward pool and/or burn address based on stage.

classDiagram
class SigvaraEpochFees {
+IERC20 svr
+SigvaraIdentity identityRegistry
+address rewardPool
+uint256 epochFee
+Stage stage
+uint256 collected
+mapping(bytes32 => uint256) balance
+depositFor(didHash, amount) void
+withdraw(didHash, amount) void
+isCovered(didHash) bool
+chargeEpoch(didHash) bool
+distributeFees() void
+setEpochFee(newFee) void
+setStage(newStage) void
+setRewardPool(newRewardPool) void
}
class Stage {
<<enum>>
Bootstrap
Transition
Mature
}
SigvaraEpochFees --> Stage : "uses"

Loading

Diagram sources

• SigvaraEpochFees.sol

Section sources

• SigvaraEpochFees.sol

SVR.sol (Archived Launch Contract, Never Deployed)

Shelved and never deployed. SVR launches as Tolly's TollyToken with no team or treasury allocation, vesting or sale; see docs/token.md. What follows describes the archived design.

Responsibilities:

• Define fixed total supply and immutable allocation constants.
• Mint allocations to treasury, team, ecosystem, public sale, and liquidity at deployment.
• Ensure no post-deploy mint or admin privileges exist.

Key behaviors:

• Constructor mints predefined allocations and asserts total supply equals constant.
• Burns occur externally by transferring to burn address from other contracts.

flowchart TD
Deploy["Deploy SVR(treasury, team, ecosystem, publicSale, liquidity)"] --> MintAllocs["Mint allocations"]
MintAllocs --> AssertSupply["Assert totalSupply == TOTAL_SUPPLY"]
AssertSupply --> Live["Live: no mint/admin/upgrade"]

Loading

Diagram sources

• SVR.sol:30-74

Section sources

• SVR.sol:1-75

Archived Launch Contracts (Never Deployed)

• SigvaraPublicSale:
  • Fixed-price purchase with hard/soft caps and per-wallet limits.
  • Finalization routes proceeds to treasury and burns unsold SVR on success; refunds buyers on failure.
• TeamVesting:
  • 4-year linear vest with 1-year cliff; beneficiary receives vested tokens.
• TreasuryVesting:
  • 5-year linear vest; releases go to governance timelock.

sequenceDiagram
participant Buyer as "Buyer"
participant Sale as "SigvaraPublicSale"
participant Treasury as "Treasury"
participant Burn as "Burn Address"
Buyer->>Sale : "buy(tokenAmount)"
Sale->>Sale : "record purchased/paid"
Sale->>Sale : "transfer paymentToken"
Sale->>Sale : "finalize()"
alt Success (>= softCap)
Sale->>Treasury : "transfer raised stablecoins"
Sale->>Burn : "burn unsold SVR"
Buyer->>Sale : "claim()"
Sale->>Buyer : "transfer purchased SVR"
else Failure (< softCap)
Sale->>Buyer : "refund()"
Sale->>Treasury : "return SVR allocation"
end

Loading

Diagram sources

• SigvaraPublicSale.sol:121-192

Section sources

• SigvaraPublicSale.sol:1-193
• TeamVesting.sol:1-31
• TreasuryVesting.sol:1-27

Dependency Analysis

• SigvaraEpochFees depends on:
  • IERC20 (SVR token address provided at initialization).
  • SigvaraIdentity (to validate agent registration and ownership).
  • AccessControlUpgradeable/UUPSUpgradeable for role-based admin and upgradeability. UPGRADER_ROLE administers itself here too, so the admin cannot grant it.
  • The operator bond registry (through IOperatorSet), when one is configured.
• SVRToken and SVR are both ERC-20 implementations but serve different environments:
  • SVRToken: testnet, mintable, faucet-enabled.
  • SVR: the mainnet token, launched through Tolly with a fixed supply and no privileges (the archived SVR.sol is not what ships).

graph LR
EpochFees["SigvaraEpochFees"] --> IERC20["IERC20 (SVR)"]
EpochFees --> Identity["SigvaraIdentity"]
EpochFees --> AC["AccessControlUpgradeable"]
EpochFees --> UUPS["UUPSUpgradeable"]
SVRToken["SVRToken (testnet)"] --> ERC20["ERC20"]
SVRMain["SVR (mainnet)"] --> ERC20

Loading

Diagram sources

• SigvaraEpochFees.sol:1-54
• SVRToken.sol:1-12
• SVR.sol:1-30

Section sources

• SigvaraEpochFees.sol
• SVRToken.sol:1-43
• SVR.sol:1-75

Performance Considerations

• Fee-on-transfer compatibility:
  • Both staking and fee registry paths measure actual balance deltas rather than trusting requested amounts. This prevents over-crediting and ensures solvency even with transfer taxes.
• Rebasing tokens:
  • Not supported; stake/balance accounting assumes fixed token balances.
• Upgrade safety:
  • SigvaraEpochFees uses UUPS and pinned storage layout to maintain mapping slot stability across upgrades.

Section sources

• FeeOnTransfer.t.sol:1-306
• token.md:203-230
• SigvaraEpochFees.sol:72-84

Troubleshooting Guide

Common issues and resolutions:

• Faucet cooldown errors:
  • Occur when requesting too frequently; wait until cooldown expires.
• Insufficient balance for epoch charging:
  • Prepay more SVR for the agent or adjust epoch fee via governance.
• Unauthorized oracle charge attempts:
  • Only addresses with ORACLE_ROLE can call chargeEpoch, and with an operator registry configured only an active operator or its signer (OracleNotBonded otherwise).
• Charging reverts with AlreadyCharged or EpochLengthNotSet:
  • The agent was already charged in this epoch, which counts as paid; or the epoch length has not been set with initializeV2 or setEpochLength.
• Zero-amount deposits/withdrawals:
  • Revert with specific error; ensure non-zero amounts.
• Unregistered agent funding:
  • Cannot fund an identity not yet registered; register first.

Operational tips:

• Always approve the fee registry before depositing.
• Monitor collected fees and distribute periodically to keep reward pool funded.
• Use tests to verify fee-on-transfer behavior and storage layout integrity.

Section sources

• SVRToken.sol:28-42
• SigvaraEpochFees.sol:219-334
• SigvaraEpochFees.t.sol:94-284

Conclusion

SVR serves as the core bond and fee asset enabling agent activation, oracle participation, and epoch coverage. The fee registry provides a robust mechanism to collect, route, and distribute fees across evolving protocol stages while remaining compatible with fee-on-transfer tokens and upgrade-safe. The archived launch contracts describe an earlier fixed-supply, vesting and sale design that was never deployed; the current token plan is in docs/token.md.

Appendices

Token Utility and Participation Rights

• Bonding:
  • Operators must stake SVR to activate agents (registration itself costs only gas) and to participate in the protocol.
• Fees:
  • Epoch fees gate inclusion in the oracle’s scoring run once the fee module is deployed; reads remain free.
• Governance:
  • Parameters like minimum stake and epoch fee are tunable by governance; burn activation follows staged thresholds.

Section sources

• token.md:6-14
• token.md:140-172
• tokenomics.md:49-67

Examples of Interactions

• Fee payments:
  • Deposit prepaid fees for an agent; oracle charges per epoch; collected fees are distributed by stage.
• Token transfers:
  • Testnet faucet minting; mainnet token transfers are exact and without tax.
• Reward distributions:
  • Bootstrap: 100% to reward pool; Transition: 80% pool/20% burn; Mature: 50% pool/50% burn.

Section sources

• SigvaraEpochFees.t.sol:153-249
• SVRToken.sol:22-42

Economic Modeling Notes

• Supply dynamics:
  • Fixed total supply; deflationary pressure from fee burns and slashing burns.
• Inflation/deflation:
  • No mint function on mainnet; testnet has controlled minting via faucet and owner.
• Parameter sensitivity:
  • Minimum stake and epoch fee denominated in SVR scale with network value; governance reviews thresholds based on usage and price volatility.
  • At launch the registries are initialized with a minimum stake of 10,000 SVR and an operator bond of 2,500,000 SVR (docs/token.md), and the mainnet deploy scripts refuse less than either figure. The epoch fee is not part of the launch.

Section sources

• SVR.sol:30-74
• tokenomics.md:16-28
• token.md:166-201