https://github.com/thecodedaniel/aiden
Aiden — autonomous NPC agents on Somnia. Game characters with onchain identity and persistent memory that react to player actions and remember them across sessions. Engine-agnostic onchain agents.
https://github.com/thecodedaniel/aiden
agent blockchain contracts somnia
Last synced: 8 days ago
JSON representation
Aiden — autonomous NPC agents on Somnia. Game characters with onchain identity and persistent memory that react to player actions and remember them across sessions. Engine-agnostic onchain agents.
- Host: GitHub
- URL: https://github.com/thecodedaniel/aiden
- Owner: TheCodeDaniel
- Created: 2026-05-27T13:57:56.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-05-27T22:51:18.000Z (24 days ago)
- Last Synced: 2026-05-27T23:20:50.180Z (24 days ago)
- Topics: agent, blockchain, contracts, somnia
- Language: JavaScript
- Homepage: https://thecodedaniel.github.io/aiden/
- Size: 53.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Aiden — Onchain NPC Agents
Aiden gives game NPCs a permanent memory stored on the **Somnia blockchain**. When a player trades with, helps, or betrays an NPC, that interaction is written onchain. The NPC remembers — across sessions, across game engines, forever.
Beyond memory, Aiden uses **Somnia Reactivity** to make NPCs autonomous. Betray Aiden enough and the NPC retaliates on its own — the blockchain calls the handler contract automatically, with no human triggering the second step.
The contract is the product. The web client in this repo is a visual proof-of-concept. A Flutter app, a Unity game, or any EVM-capable engine can call the same contracts and share the same NPC memory and reactions.
---
## Repository structure
```
aiden/
├── contract/ Solidity smart contracts (Foundry)
│ ├── src/ AidenAgent.sol + AidenReactiveHandler.sol
│ ├── test/ 15 Foundry unit tests
│ └── script/ Deploy scripts + RegisterReactivity.ts
└── web/ 3D web client (Three.js + viem + Vite)
└── src/ chain.js · scene.js · main.js · abi.js
```
---
## Network
| | |
|---|---|
| Network | Somnia Shannon Testnet |
| Chain ID | `50312` |
| RPC | `https://dream-rpc.somnia.network` |
| Explorer | https://shannon-explorer.somnia.network |
| Native token | STT |
**Faucets** (`faucet.somnia.network` is no longer active):
- https://testnet.somnia.network — 0.5 STT / 24h
- https://cloud.google.com/application/web3/faucet/somnia/shannon — Google login
---
## Quick start
### 1 — Deploy the contracts → see [contract/README.md](contract/README.md)
### 2 — Run the web client → see [web/README.md](web/README.md)
---
## How it works
### Core memory flow
```
Player clicks "Help"
↓
web/src/chain.js calls interact(0, Help) via MetaMask
↓
AidenAgent.sol adds +10 to standing[0][playerAddress]
emits Interacted(npcId, player, action, newStanding)
↓
web/src/chain.js receives the event
↓
NPC turns green, label shows +10
↓
Reload the page → same standing, read fresh from chain
```
### Autonomous retaliation (Somnia L1 agent)
```
Player clicks "Betray" — standing drops to −15
↓
AidenAgent emits Interacted(npcId, player, Betray, −15)
↓
Somnia reactivity precompile detects event matches subscription
↓
Precompile calls AidenReactiveHandler.onEvent() — no human involved
↓
Handler: Betray + standing −15 < −10 threshold → retaliate
↓
AidenAgent.applyReactivePenalty() → standing −10 more → emits NpcReacted(−25)
↓
Web client shows "⚡ Aiden retaliates autonomously!", NPC turns deep red
```
The memory is in the contract, not the app. Any client that can talk to Somnia sees the same state.
---
## Architecture
`chain.js` and `scene.js` are completely isolated. The chain module knows nothing about Three.js; the scene module knows nothing about wallets. This mirrors how Aiden is meant to work at scale — swap the web client for Flutter or Unity and the contract API is unchanged.
`AidenReactiveHandler` is a Somnia L1 agent. It inherits from `SomniaEventHandler` and is triggered by the Somnia reactivity precompile at `0x0100`. When the live subscription is registered, the NPC reacts to betrayals with zero human involvement.