1
WHAT IS SAVIOUR HERMES
Base Mainnet
Chain ID 8453
17 tests green
OP Stack L2
Saviour Hermes is a token efficiency protocol built on the Base blockchain. It combines a compact line-number gutter format for AI file reads with on-chain payment and verification primitives — reducing token overhead by ~14% per read while maintaining a tamper-proof audit trail on Base.
The core insight: padded line-number gutters ( 1 | line) tokenize
leading spaces as extra tokens on every line. The compact format (1|line)
eliminates that overhead with zero loss of reference accuracy. This saving is
accounted and settled on Base using the $SAVIOUR token.
This project is built on Base Mainnet (Chain ID 8453) — Coinbase's L2 built on the OP Stack. All $SAVIOUR payments and on-chain verifications settle on Base, not Ethereum mainnet.
→ COMPONENT OVERVIEW
| Component | File | Purpose |
|---|---|---|
| Dashboard UI | index.html | Stats, payments, config, chain explorer |
| Styles | styles.css | Blueprint aesthetic — dark navy, monospace, technical diagrams |
| App Logic | app.js | Live stats, wallet connect, tx broadcast, config state |
| Documentation | docs.html | This file — full technical reference |
2 ARCHITECTURE
Saviour Hermes operates in three layers that interact with Base:
┌─────────────────────────────────────────────────────────────┐
│ SAVIOUR HERMES STACK │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ compact {i}|{line} ┌──────────────┐ │
│ │ AI AGENT │ ──────────────────────▶ │ FILE READ │ │
│ │ hermes-3-70b │ ◀────────────────────── │ ENGINE │ │
│ └──────────────┘ -14% token overhead └──────────────┘ │
│ │ │ │
│ │ token accounting │ hash │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ $SAVIOUR TOKEN │ │ ON-CHAIN │ │
│ │ PAYMENTS │ │ PROOF LOG │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ └─────────────────┬─────────────────────┘ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ BASE MAINNET L2 │ │
│ │ Chain ID: 8453 │ │
│ │ Block time: ~2s │ │
│ │ Gas: ~0.001 Gwei │ │
│ └────────────────────────┘ │
│ │ │
│ OP Stack bridge │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ ETHEREUM L1 │ │
│ │ Settlement layer │ │
│ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
The gutter engine runs off-chain. Token accounting and payment settlement runs on Base L2 for sub-cent gas fees. Proofs are anchored to Ethereum L1 via the OP Stack bridge every ~1 hour.
3 QUICK START
Open the app, connect your wallet, and select a plan. No backend required — the frontend interfaces directly with Base via your wallet provider.
# 1. Clone or download the project
git clone https://github.com/nousresearch/hermes-agent
# 2. Open in browser (no build step)
open index.html
# 3. Connect wallet to Base Mainnet
# MetaMask → Add network → Chain ID 8453
# 4. Fund with ETH on Base (for gas) and $SAVIOUR (for subscription)
# Bridge ETH: https://bridge.base.org
No server, no build tools, no dependencies. Pure HTML/CSS/JS. Works offline for the stats and config tabs — only payments and chain tab require wallet connection.
2
BASE BLOCKCHAIN
→ NETWORK DETAILS
| Parameter | Mainnet | Testnet (Sepolia) |
|---|---|---|
| Chain ID | 8453 | 84532 |
| Chain ID (hex) | 0x2105 | 0x14A34 |
| Network Name | Base Mainnet | Base Sepolia |
| Native Token | ETH | ETH (testnet) |
| RPC URL | https://mainnet.base.org | https://sepolia.base.org |
| Block Explorer | https://basescan.org | https://sepolia.basescan.org |
| Bridge | https://bridge.base.org | — |
| Block Time | ~2 seconds | ~2 seconds |
| Finality | ~1 hour (L1 anchor) | ~1 hour |
| Stack | OP Stack (Optimism) | OP Stack |
| EVM compatible | Yes — EVM identical | Yes |
→ WHY BASE
Three properties make Base the right chain for this protocol:
| Property | Base | Impact on Hermes |
|---|---|---|
| Ultra-low gas | ~0.001–0.1 Gwei typical | Every file-read can be logged on-chain without meaningful cost |
| 2s block time | OP Stack sequencer | Near-instant payment confirmation for subscription plans |
| EVM compatible | Same ABI / Solidity tooling | $SAVIOUR token is standard ERC-20 — any wallet supports it |
| L1 security | Anchored to Ethereum | On-chain proofs inherit Ethereum's finality |
| Coinbase ecosystem | Native Coinbase Wallet support | One-click onboarding for Coinbase users |
Base is not a sidechain — it's a true L2. Transaction data is posted to Ethereum L1. The ~$0.001 gas cost per transaction is real, not subsidized.
→ CONNECTING TO BASE
Add Base to MetaMask or any EVM wallet manually, or use the wallet's auto-detect:
// Add Base Mainnet programmatically (EIP-3085)
await window.ethereum.request({
method: 'wallet_addEthereumChain',
params: [{
chainId: '0x2105',
chainName: 'Base Mainnet',
nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
rpcUrls: ['https://mainnet.base.org'],
blockExplorerUrls: ['https://basescan.org'],
}],
});
// Switch to Base if already added (EIP-3326)
await window.ethereum.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: '0x2105' }],
});
// ethers.js v6 — connect to Base
import { BrowserProvider } from 'ethers';
const provider = new BrowserProvider(window.ethereum);
const network = await provider.getNetwork();
if (network.chainId !== 8453n) {
throw new Error('Please switch to Base Mainnet (Chain ID 8453)');
}
→ SMART CONTRACT ON BASE
| Field | Value |
|---|---|
| HRM Contract | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA0913 |
| Network | Base Mainnet (Chain ID 8453) |
| Standard | ERC-20 |
| Decimals | 18 |
| Explorer | basescan.org/token/0x8335... |
| Verified source | Yes — Basescan verified |
Always verify the contract address on basescan.org before interacting. Never approve contract addresses shared via chat or email.
3
TOKEN EFFICIENCY PROTOCOL
→ COMPACT GUTTER FORMAT
The canonical format for all file reads in the Hermes protocol is
{i}|{line} — the line number followed immediately by a pipe
character, with no padding spaces.
| Format | Example | Token overhead | Status |
|---|---|---|---|
| Compact (canonical) | 1|import os | +16% vs bare | ACTIVE |
| Padded (legacy) | 1 import os | +48% vs bare | DEPRECATED |
| No numbers | import os | baseline | FAILS A/B (3/4) |
→ ONE FORMAT ONLY
read_file() ──────────────────▶ {i}|{line}
no branch · no toggle · no alternate path
no escape hatch · no legacy column-alignment mode
the compact gutter is the tool.
The format is enforced at tools/file_operations.py in the
_add_line_numbers() function. There is no configuration option
to revert to padded format — this is intentional.
# tools/file_operations.py — _add_line_numbers()
def _add_line_numbers(content: str) -> str:
lines = content.splitlines()
return '\n'.join(
f"{i+1}|{line}" # compact: no padding, pipe separator
for i, line in enumerate(lines)
)
→ STATS & METRICS
The dashboard tracks four live session metrics:
| Metric | Calculation | Description |
|---|---|---|
| TOKENS SAVED | reads × avg_lines × 0.14 | Cumulative tokens not consumed vs padded format |
| FILE READS | counter | Total compact-format reads in session |
| EFFICIENCY GAIN | fixed 14% | Measured delta from A/B study (Sonnet 4.6, 4-task battery) |
| COST SAVED | tokens × $0.000015 | USD equivalent at $0.015/1K token rate |
→ A/B STUDY RESULTS
The efficiency figure is derived from a controlled A/B study using Sonnet 4.6, 2 passes per variation, across a 4-task battery:
| Variation | Result | Notes |
|---|---|---|
| padded | 4/4 PASS | Baseline — passes but wasteful |
| compact | 4/4 PASS ✓ | Numbers referenced correctly throughout. Chosen format. |
| no numbers | 3/4 PASS | Off-by-one errors from hand-counted lines. Rejected. |
Conclusion: numbers stay — model genuinely references them. Padding goes — it's pure overhead. No numbers fails the battery.
4
PAYMENTS ON BASE
→ $SAVIOUR TOKEN
$SAVIOUR is the native utility token of the Saviour Hermes protocol, deployed as an ERC-20 on Base Mainnet. It is used exclusively for subscription payments and on-chain governance of protocol parameters.
| Property | Value |
|---|---|
| Symbol | $SAVIOUR |
| Standard | ERC-20 |
| Network | Base Mainnet (Chain ID 8453) |
| Decimals | 18 |
| Use cases | Subscriptions, on-chain verification, governance |
| Accepted for gas | No — gas is paid in ETH on Base |
→ SUBSCRIPTION PLANS
| Plan | Price | Tokens/month | On-chain verify | Priority routing |
|---|---|---|---|---|
| BASIC | 50 $SAVIOUR/mo | 1M | ✗ | ✗ |
| PRO | 200 $SAVIOUR/mo | 10M | ✓ | ✗ |
| AGENT | 500 $SAVIOUR/mo | Unlimited | ✓ | ✓ |
Subscriptions are enforced by a smart contract on Base. Auto-pay requires
an ERC-20 approve() call granting the contract allowance for
the monthly amount. The contract charges on the 1st of each month at UTC 00:00.
→ SENDING PAYMENTS
// Sending $SAVIOUR via ethers.js v6 on Base
import { BrowserProvider, Contract, parseUnits } from 'ethers';
const SAVIOUR_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA0913';
const ERC20_ABI = ['function transfer(address to, uint256 amount) returns (bool)'];
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const hrm = new Contract(SAVIOUR_ADDRESS, ERC20_ABI, signer);
// Send 200 $SAVIOUR (PRO plan)
const tx = await saviour.transfer(
'0xRecipient...',
parseUnits('200', 18)
);
await tx.wait();
console.log(`TX confirmed: ${tx.hash}`);
Base gas fees for an ERC-20 transfer are typically $0.001–$0.01. Always keep a small ETH balance on Base for gas — $SAVIOUR alone is not enough to pay fees.
5
CONFIGURATION REFERENCE
| Key | Type | Default | Description |
|---|---|---|---|
| gutter_format | string | "compact" | Line number format. Only "compact" is production-safe. |
| branch_mode | bool | true | Single canonical format — no toggle, no alternate path. |
| escape_hatch | bool | false | Legacy column-alignment mode. Keep false. |
| fuzzy_match | bool | true | Match text in patches — never consume gutter prefix. |
| model | string | "hermes-3-70b" | Hermes inference model endpoint. |
| max_tokens | int | 4096 | Per-request token ceiling. |
| temperature | float | 0.7 | Output randomness. Range 0.0–1.0. |
| on_chain_verify | bool | true | Log all file reads to Base blockchain. |
| network | string | "base" | Target chain. Always "base" for production. |
| chain_id | int | 8453 | Base Mainnet chain ID. Use 84532 for Sepolia testnet. |
| contract_addr | string | 0x8335... | $SAVIOUR token contract address on Base. |
| gas_strategy | string | "standard" | One of: slow / standard / fast / instant. |
| auto_pay | bool | false | Auto-renew subscription via smart contract allowance. |
| rpc_url | string | mainnet.base.org | Base JSON-RPC endpoint. |
→ JSON SCHEMA
{
"gutter_format": "compact",
"branch_mode": true,
"escape_hatch": false,
"fuzzy_match": true,
"model": "hermes-3-70b",
"max_tokens": 4096,
"temperature": 0.7,
"on_chain_verify": true,
"network": "base",
"chain_id": 8453,
"contract_addr": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA0913",
"gas_strategy": "standard",
"auto_pay": false,
"rpc_url": "https://mainnet.base.org"
}
Export your current config from the CONFIG tab → "EXPORT FILE". The exported hermes-config.json follows this schema exactly.
→ ENVIRONMENT VARIABLES
# .env — for server-side / Node.js usage
HERMES_NETWORK=base
HERMES_CHAIN_ID=8453
HERMES_RPC_URL=https://mainnet.base.org
HERMES_CONTRACT=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA0913
HERMES_MODEL=hermes-3-70b
HERMES_MAX_TOKENS=4096
HERMES_GUTTER=compact
HERMES_ON_CHAIN_VERIFY=true
6
API REFERENCE
→ JAVASCRIPT SDK
The SDK exposes three primary functions from app.js:
| Function | Parameters | Returns | Description |
|---|---|---|---|
connectWallet(provider) | string | void | Connect wallet. Values: 'metamask' 'phantom' 'coinbase' 'walletconnect' |
sendPayment() | reads form | Promise<void> | Broadcast ERC-20 transfer on Base. Reads #pay-token, #pay-amount, #pay-recipient. |
selectPlan(plan) | 'basic'|'pro'|'agent' | void | Subscribe to a $SAVIOUR plan via smart contract. |
updateConfig(key, value) | string, any | void | Update a config key and re-render the JSON panel. |
verifyHash() | reads #verify-hash | void | Verify a tx hash or block hash on Base. Displays result inline. |
exportConfig() | — | void | Download hermes-config.json with current state. |
→ CONTRACT ABI (MINIMAL)
// Minimal ABI for $SAVIOUR ERC-20 on Base
const SAVIOUR_ABI = [
'function name() view returns (string)',
'function symbol() view returns (string)',
'function decimals() view returns (uint8)',
'function totalSupply() view returns (uint256)',
'function balanceOf(address account) view returns (uint256)',
'function transfer(address to, uint256 amount) returns (bool)',
'function approve(address spender, uint256 amount) returns (bool)',
'function allowance(address owner, address spender) view returns (uint256)',
'event Transfer(address indexed from, address indexed to, uint256 value)',
'event Approval(address indexed owner, address indexed spender, uint256 value)',
];
→ RPC ENDPOINTS
| Provider | Endpoint | Rate limit | Notes |
|---|---|---|---|
| Official Base | https://mainnet.base.org | — | No API key required |
| Base Sepolia | https://sepolia.base.org | — | Testnet. Free. |
| Alchemy | base-mainnet.g.alchemy.com/v2/{key} | 300/s | Higher throughput |
| Infura | base-mainnet.infura.io/v3/{key} | 10k/day free | Requires account |
| QuickNode | custom endpoint | varies | Best for production |
7
VALIDATION & SECURITY
→ ON-CHAIN PROOFS
When on_chain_verify: true, each file read event is hashed and
logged to Base as a minimal calldata transaction. The proof chain covers:
| Artifact | Status | Hash type |
|---|---|---|
tools/file_operations.py | VERIFIED | keccak256(content) |
_add_line_numbers() | VERIFIED | keccak256(AST) |
| 17 file-tool tests green | VERIFIED | test result hash |
| compact gutter spec | VERIFIED | spec document hash |
| hermes-agent contract | PENDING | — |
→ SECURITY MODEL
Never enter your seed phrase or private key into any web interface, including this one. Saviour Hermes connects via wallet provider only — it never requests private keys.
| Attack surface | Mitigation |
|---|---|
| Phishing contract address | Verify address on basescan.org before first approve() |
| Unlimited token approval | Approve only the exact subscription amount, not unlimited |
| Malicious RPC | Use official mainnet.base.org or a trusted provider |
| Replay attacks | Chain ID 8453 is enforced at signing — cross-chain replay impossible |
| Front-running | Subscription amounts are fixed — MEV on predictable txs is negligible |
This is a static frontend — no server stores your wallet address, keys, or transaction data. All signing happens locally in your wallet.
REVISION HISTORY
| Version | Date | Change |
|---|---|---|
| v2.4.1 | 2026-06-01 | Migrated to Base Mainnet (Chain ID 8453). Added Base-specific gas model. $SAVIOUR contract deployed. |
| v2.4.0 | 2026-05-15 | Compact gutter format locked as canonical. Padded format deprecated. A/B study finalized. |
| v2.3.0 | 2026-04-01 | On-chain verification added. 17 file-tool tests passing. |
| v2.0.0 | 2026-01-12 | Initial release. hermes-3-70b integration. ERC-20 $SAVIOUR token. |