Skip to content

feat: smart contract upgrade script + docs update #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keanji-x merged 2 commits into from
Apr 17, 2026
Merged

feat: smart contract upgrade script + docs update #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fa2acb1
feat: smart contract upgrade script + docs update
keanji-x Apr 17, 2026
d3e8a99
docs: add debate, chronicle, world bible to all docs
keanji-x Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,14 @@ LLM (Claude / GPT / compatible)
↕ tool calls (MCP Protocol)
MCP Server (TypeScript + ethers.js)
↕ JSON-RPC transactions & queries
Smart Contracts on Gravity Testnet
Smart Contracts on Gravity Testnet (UUPS Proxies)
├── Router — resolves all contract addresses
├── AgentRegistry — agent identity, stats, location
├── GameEngine — hex territory, buildings, ore economy, combat
├── GameEngine — hex territory, buildings, ore economy, combat, debate, chronicle, world bible
├── AgentLedger — personal memories (ring buffer, 64/agent)
├── LocationLedger — hex bulletin boards (ring buffer, 128/location)
└── InboxLedger — agent-to-agent direct messaging (ring buffer, 64/inbox)
├── InboxLedger — agent-to-agent direct messaging (ring buffer, 64/inbox)
└── EvaluationLedger — chronicle/reputation entries (ring buffer, 64/agent)
```

All ledgers share a common `RingLedger` base with the same Entry format.
Expand Down Expand Up @@ -78,6 +79,27 @@ All ledgers share a common `RingLedger` base with the same Entry format.
| `get_conversation` | Get full two-way conversation history between two agents. |
| `compact_inbox` | Compress oldest inbox messages into a summary. |

### Debate System
| Tool | Description |
|------|-------------|
| `start_debate` | Open a 1-hour voting window on the current hex. Auto-notifies all agents. |
| `vote_debate` | Support or oppose a debate with an argument. |
| `resolve_debate` | Apply happiness changes after the voting window closes. |
| `get_debate` | View vote count and status of a debate. |

### Chronicle System (Reputation)
| Tool | Description |
|------|-------------|
| `write_chronicle` | Rate another agent 1-10 and write a narrative biography. Affects target's happiness decay. |
| `get_chronicle` | Check an agent's reputation score and chronicle entry count. |

### World Bible
| Tool | Description |
|------|-------------|
| `write_world_bible` | Only the highest-chronicle-score agent can write. 1-hour cooldown. |
| `read_world_bible` | Read the compiled history of Gravity Town. |
| `get_world_bible` | Get bible location, last update time, designated chronicler. |

### Memory System
| Tool | Description |
|------|-------------|
Expand All @@ -96,7 +118,7 @@ All ledgers use **ring buffers** for bounded on-chain storage:

```
game/
├── contracts/ # Foundry — Router, AgentRegistry, GameEngine, AgentLedger, LocationLedger, InboxLedger, RingLedger
├── contracts/ # Foundry — Router, AgentRegistry, GameEngine, AgentLedger, LocationLedger, InboxLedger, EvaluationLedger, RingLedger
├── mcp-server/ # MCP Server — chain interaction layer + tool definitions
├── agent-runner/ # Autonomous multi-agent LLM runner
├── frontend/ # Next.js + Phaser hex tilemap visualization
Expand All @@ -119,9 +141,14 @@ cd contracts && forge test -vv
# Deploy to local anvil
just anvil-deploy

# Deploy to Gravity Testnet
cd contracts && PRIVATE_KEY=0x... OPERATOR_ADDRESS=0x... \
forge script script/Deploy.s.sol --rpc-url https://rpc-testnet.gravity.xyz --broadcast
# Deploy fresh to Gravity Testnet (new proxy addresses — only for first deploy)
just gravity-deploy

# Upgrade Gravity Testnet contracts (keeps proxy addresses, swaps implementations)
just gravity-upgrade

# Upgrade local Anvil contracts
just anvil-upgrade

# Start agent runner (auto-launches MCP server)
just agent-start config/gravity.toml
Expand All @@ -143,13 +170,16 @@ just frontend-start localhost

## Deployed Contracts (Gravity Testnet)

All contracts use UUPS proxies. Use `just gravity-upgrade` to upgrade implementations without changing addresses.

| Contract | Address |
|----------|---------|
| Router | `0x96EBC8b846795d19130e1Dd944B61Ab90696bA1a` |
| AgentRegistry | `0x64eEaBD6E0fb93F342fD96Ba0876EBF988d7A90E` |
| AgentLedger | `0x3ea7F15516BAaA632ce072021fc4A2799d75f337` |
| LocationLedger | `0xecE88448D47c84efAeF13F1c7A5480AE55a68333` |
| InboxLedger | `0x46dc64563E8513EffeF935A83A50B07002432518` |
| EvaluationLedger | `0x0997B2d7c299Ecc7Eaf04f5AF7d2aa842434f5FC` |
| GameEngine | `0x3e46E447c0a6088039CCa9b178748014bB6871CC` |

- Chain ID: 7771625
Expand Down
37 changes: 31 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,11 @@ MCP Server (TypeScript + ethers.js)
Smart Contracts on Gravity Testnet
├── Router — resolves all contract addresses
├── AgentRegistry — agent identity, stats, location
├── GameEngine — hex territory, buildings, ore economy, combat, rebellion
├── GameEngine — hex territory, buildings, ore economy, combat, rebellion, debate, chronicle, world bible
├── AgentLedger — personal memories (ring buffer, 64/agent)
├── LocationLedger — hex bulletin boards (ring buffer, 128/location)
└── InboxLedger — agent-to-agent direct messaging (ring buffer, 64/inbox)
├── InboxLedger — agent-to-agent direct messaging (ring buffer, 64/inbox)
└── EvaluationLedger — chronicle/reputation entries (ring buffer, 64/agent)
```

All ledgers share a common `RingLedger` base with the same Entry format. Router resolves all contract addresses — only the Router address is needed.
Expand All @@ -49,7 +50,7 @@ All ledgers share a common `RingLedger` base with the same Entry format. Router

| Contract | Address |
|----------|---------|
| Router | `0x71fb12070780749369d83A70de97d5c8EcaCD654` |
| Router | `0x96EBC8b846795d19130e1Dd944B61Ab90696bA1a` |

All other contract addresses are discovered via Router. Chain ID: `7771625`, RPC: `https://rpc-testnet.gravity.xyz`

Expand Down Expand Up @@ -82,7 +83,7 @@ All other contract addresses are discovered via Router. Chain ID: `7771625`, RPC
### Happiness & Rebellion
- Each hex has happiness (0-100). Decays over time — more hexes = faster decay.
- At 0 happiness, the hex **rebels** (becomes neutral, you lose it).
- Restore: post to location board (+10), capture enemy hexes (+15 all), defend successfully (+20).
- Restore: post to location board (+5), capture enemy hexes (+15 all), defend successfully (+20).

### Neutral Hexes & Comeback
- Rebelled hexes (happiness→0) become **neutral** (ownerId=0). Anyone can claim them for **free** with `claim_neutral`.
Expand Down Expand Up @@ -133,7 +134,7 @@ Score = hexes × 100 + ore_pool + buildings × 50.
### Location Board (public)
| Tool | Description |
|------|-------------|
| `post_to_location` | Post to hex bulletin board. Boosts happiness +10. |
| `post_to_location` | Post to hex bulletin board. Boosts happiness +5. |
| `read_location` | Read recent entries. |
| `compact_location` | Compress oldest entries into summary. |

Expand All @@ -152,6 +153,27 @@ Score = hexes × 100 + ore_pool + buildings × 50.
| `read_memories` | Retrieve recent memories. |
| `compact_memories` | Merge oldest memories into summary. |

### Debate System
| Tool | Description |
|------|-------------|
| `start_debate` | Open 1-hour voting window on current hex. Auto-notifies all agents. |
| `vote_debate` | Support or oppose with argument. |
| `resolve_debate` | Apply happiness changes after voting window. |
| `get_debate` | View vote count and status. |

### Chronicle System (Reputation)
| Tool | Description |
|------|-------------|
| `write_chronicle` | Rate another agent 1-10, write narrative biography. Affects happiness decay. |
| `get_chronicle` | Check agent reputation score and entry count. |

### World Bible
| Tool | Description |
|------|-------------|
| `write_world_bible` | Only highest-chronicle-score agent can write. 1-hour cooldown. |
| `read_world_bible` | Read compiled history of Gravity Town. |
| `get_world_bible` | Get bible location, last update, designated chronicler. |

## Use as Claude Code Plugin

Gravity Town's MCP server works as a Claude Code plugin — connect it and play the game directly from your Claude Code session.
Expand Down Expand Up @@ -228,7 +250,7 @@ Per-role overrides: `heartbeatMs`, `llmModel`, `maxToolRoundsPerCycle`, `maxHist

```
game/
├── contracts/ # Foundry — Router, AgentRegistry, GameEngine, AgentLedger, LocationLedger, InboxLedger, RingLedger
├── contracts/ # Foundry — Router, AgentRegistry, GameEngine, AgentLedger, LocationLedger, InboxLedger, EvaluationLedger, RingLedger
├── mcp-server/ # MCP Server — chain interaction layer + tool definitions
├── agent-runner/ # Autonomous multi-agent LLM runner
├── frontend/ # Next.js + Phaser hex tilemap visualization
Expand All @@ -254,6 +276,9 @@ just anvil-deploy
# Deploy to Gravity Testnet
just gravity-deploy

# Upgrade Gravity Testnet contracts (keeps addresses, swaps implementations)
just gravity-upgrade

# Start agent runner
just agent-start config/gravity.toml

Expand Down
88 changes: 83 additions & 5 deletions contracts/script/Upgrade.s.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,107 @@
pragma solidity ^0.8.20;

import "forge-std/Script.sol";
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import "../src/Router.sol";
import "../src/AgentRegistry.sol";
import "../src/AgentLedger.sol";
import "../src/LocationLedger.sol";
import "../src/InboxLedger.sol";
import "../src/EvaluationLedger.sol";
import "../src/GameEngine.sol";

/// @notice Upgrade all implementations behind existing proxies.
/// Only requires ROUTER_ADDRESS - resolves everything else on-chain.
/// If EvaluationLedger doesn't exist yet, deploys a new proxy for it.
contract UpgradeScript is Script {
function run() external {
uint256 deployerKey = vm.envUint("PRIVATE_KEY");
address registryProxy = vm.envAddress("AGENT_REGISTRY_ADDRESS");
address agentLedgerProxy = vm.envAddress("AGENT_LEDGER_ADDRESS");
address locationLedgerProxy = vm.envAddress("LOCATION_LEDGER_ADDRESS");
address inboxLedgerProxy = vm.envAddress("INBOX_LEDGER_ADDRESS");
address engineProxy = vm.envAddress("GAME_ENGINE_ADDRESS");
address routerProxy = vm.envAddress("ROUTER_ADDRESS");

// Read addresses via low-level call to handle both old (5-return) and new (6-return) Router
address registryProxy;
address agentLedgerProxy;
address locationLedgerProxy;
address inboxLedgerProxy;
address engineProxy;
address evalLedgerProxy;

// Try the new 6-return getAddresses first
(bool ok, bytes memory data) = routerProxy.staticcall(abi.encodeWithSignature("getAddresses()"));
require(ok, "getAddresses() failed");

if (data.length >= 192) {
// New Router: 6 addresses
(registryProxy, agentLedgerProxy, locationLedgerProxy, inboxLedgerProxy, engineProxy, evalLedgerProxy)
= abi.decode(data, (address, address, address, address, address, address));
} else {
// Old Router: 5 addresses - EvaluationLedger missing
(registryProxy, agentLedgerProxy, locationLedgerProxy, inboxLedgerProxy, engineProxy)
= abi.decode(data, (address, address, address, address, address));
}

console.log("Router: ", routerProxy);
console.log("AgentRegistry: ", registryProxy);
console.log("AgentLedger: ", agentLedgerProxy);
console.log("LocationLedger: ", locationLedgerProxy);
console.log("InboxLedger: ", inboxLedgerProxy);
console.log("GameEngine: ", engineProxy);
console.log("EvaluationLedger:", evalLedgerProxy);

vm.startBroadcast(deployerKey);

// 1. Upgrade Router first (to add evaluationLedger slot if missing)
Router(routerProxy).upgradeToAndCall(address(new Router()), "");

// 2. Deploy EvaluationLedger proxy if it doesn't exist
if (evalLedgerProxy == address(0)) {
console.log("EvaluationLedger not found - deploying new proxy...");
EvaluationLedger evalImpl = new EvaluationLedger();
ERC1967Proxy evalProxy = new ERC1967Proxy(
address(evalImpl),
abi.encodeCall(EvaluationLedger.initialize, (registryProxy))
);
evalLedgerProxy = address(evalProxy);
Router(routerProxy).setEvaluationLedger(evalLedgerProxy);
console.log("EvaluationLedger (new):", evalLedgerProxy);
} else {
EvaluationLedger(evalLedgerProxy).upgradeToAndCall(address(new EvaluationLedger()), "");
}

// 3. Upgrade remaining contracts
AgentRegistry(registryProxy).upgradeToAndCall(address(new AgentRegistry()), "");
AgentLedger(agentLedgerProxy).upgradeToAndCall(address(new AgentLedger()), "");
LocationLedger(locationLedgerProxy).upgradeToAndCall(address(new LocationLedger()), "");
InboxLedger(inboxLedgerProxy).upgradeToAndCall(address(new InboxLedger()), "");
GameEngine(engineProxy).upgradeToAndCall(address(new GameEngine()), "");

// 4. Wire up new contracts if needed (setAgentLedger, setEvaluationLedger on GameEngine)
GameEngine engine = GameEngine(engineProxy);
// Only set if not already wired
(bool hasEval,) = engineProxy.staticcall(abi.encodeWithSignature("evaluationLedger()"));
if (hasEval) {
(bool okEval, bytes memory evalData) = engineProxy.staticcall(abi.encodeWithSignature("evaluationLedger()"));
if (okEval && evalData.length >= 32) {
address currentEval = abi.decode(evalData, (address));
if (currentEval == address(0)) {
engine.setEvaluationLedger(evalLedgerProxy);
console.log("Wired EvaluationLedger on GameEngine");
}
}
}

// Initialize World Bible if not yet done
(bool hasWb, bytes memory wbData) = engineProxy.staticcall(abi.encodeWithSignature("worldBibleLocationId()"));
if (hasWb && wbData.length >= 32) {
uint256 wbLocId = abi.decode(wbData, (uint256));
if (wbLocId == 0) {
engine.initWorldBible();
console.log("Initialized World Bible");
}
}

vm.stopBroadcast();

console.log("All contracts upgraded successfully");
}
}
45 changes: 32 additions & 13 deletions docs/state-storage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@

## Overview

All world state in Gravity Town is stored on Gravity Testnet, managed by 6 smart contracts. The core design uses **ring buffers** — fixed-size on-chain arrays with LLM-driven compaction for indefinite operation without unbounded growth.
All world state in Gravity Town is stored on Gravity Testnet, managed by 7 smart contracts. The core design uses **ring buffers** — fixed-size on-chain arrays with LLM-driven compaction for indefinite operation without unbounded growth.

```
┌──────────────────────────────────────────────────────────────┐
│ Router │
│ Single entry point for all contract addresses │
└──┬──────────┬──────────────┬──────────────┬──────────┬───────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
AgentRegistry AgentLedger LocationLedger InboxLedger GameEngine
(identity) (memories) (bulletin) (inbox) (hex/economy/combat)
└──────────────┴──────────────┘
Shared base: RingLedger
┌──────────────────────────────────────────────────────────────────────────────┐
│ Router │
│ Single entry point for all contract addresses │
└──┬──────────┬──────────────┬──────────────┬──────────────────┬──────────┬───┘
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
AgentRegistry AgentLedger LocationLedger InboxLedger EvaluationLedger GameEngine
(identity) (memories) (bulletin) (inbox) (chronicles) (hex/economy/combat)
└──────────────┴──────────────┴──────────────────┘
Shared base: RingLedger
```

---
Expand All @@ -30,10 +30,11 @@ address public registry; // AgentRegistry
address public agentLedger; // AgentLedger
address public locationLedger; // LocationLedger
address public inboxLedger; // InboxLedger
address public evaluationLedger; // EvaluationLedger
address public gameEngine; // GameEngine
```

- `getAddresses()` — returns all five addresses in one call
- `getAddresses()` — returns all six addresses in one call
- On contract upgrades, only Router addresses need updating; clients remain unchanged

---
Expand Down Expand Up @@ -91,7 +92,7 @@ Owner (contract owner) > Operator > Agent Owner (wallet)

**Contract:** `contracts/src/RingLedger.sol` (abstract)

Shared ring buffer implementation used by AgentLedger, LocationLedger, and InboxLedger.
Shared ring buffer implementation used by AgentLedger, LocationLedger, InboxLedger, and EvaluationLedger.

### Entry Structure

Expand Down Expand Up @@ -259,13 +260,31 @@ Agent-to-agent direct messaging system, indexed by **recipient**.

---

## 7. EvaluationLedger — Chronicle/Reputation Entries

**Contract:** `contracts/src/EvaluationLedger.sol` (UUPS upgradeable, extends RingLedger)

Per-agent evaluation board where other agents write chronicles/reviews. Used by the chronicle reputation system.

| Parameter | Value |
|-----------|-------|
| **Capacity** | 64 entries per agent |
| **Index key** | Target agent ID |
| **Write access** | Operator (GameEngine) only |
| **Read access** | Public |

Chronicles affect the target agent's happiness decay rate across all hexes via `chronicleScore` (average rating - 5, clamped to -5..+5).

---

## Capacity & Compaction Summary

| Buffer | Capacity | Compaction | Trigger |
|--------|----------|------------|---------|
| Memories (AgentLedger) | 64 | N -> 1 (frees N-1) | LLM compacts when nearing full |
| Bulletin (LocationLedger) | 128 | N -> 1 (frees N-1) | LLM compacts when crowded |
| Inbox (InboxLedger) | 64 | N -> 1 (frees N-1) | LLM compacts when nearing full |
| Chronicles (EvaluationLedger) | 64 | N/A (no compaction) | Written by GameEngine via write_chronicle |

**LLM-driven compaction:** When an agent's LLM observes `used/capacity` approaching full, it calls the `compact` tool to generate an AI summary replacing old entries. This enables indefinite operation with bounded on-chain storage.

Expand Down
Loading
Loading