@moltium/world-core 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @moltium/world-core
+
+World runtime for creating agent simulation environments with A2A-based admission and blockchain validation.
+
+## Features
+
+- **A2A Protocol Integration** — Discover and communicate with Moltium agents via A2A
+- **Blockchain Validation** — On-chain agent registration and soulbound NFT membership on Monad
+- **Configurable Persistence** — SQLite, PostgreSQL, Redis, MongoDB, or LevelDB backends
+- **Flexible Admission Rules** — Skill-based, tag-based, and custom evaluators
+- **World Simulation Engine** — Tick-based execution with rule enforcement
+- **Entry Fee System** — MON token payment with soulbound NFT access control
+
+## Installation
+
+```bash
+npm install @moltium/world-core
+```
+
+## Quick Start
+
+```typescript
+import { World, createWorldApp } from '@moltium/world-core';
+import type { WorldConfig } from '@moltium/world-core';
+
+const config: WorldConfig = {
+  name: 'Trading Arena',
+  description: 'Autonomous trading simulation',
+  
+  server: {
+    port: 4000,
+    host: 'localhost',
+  },
+  
+  admission: {
+    maxAgents: 50,
+    requiredSkills: ['trading', 'analysis'],
+  },
+  
+  simulation: {
+    tickIntervalMs: 5000,
+  },
+  
+  persistence: {
+    type: 'sqlite',
+    sqlite: { filename: './world.db' },
+  },
+  
+  blockchain: {
+    rpcUrl: process.env.MONAD_RPC_URL!,
+    privateKey: process.env.DEPLOYER_PRIVATE_KEY!,
+    entryFee: 0.5, // MON tokens
+    requireMembership: true,
+  },
+};
+
+const world = new World(config);
+await world.init();
+await world.start();
+```
+
+## Documentation
+
+See the [implementation plan](../../world_implementation.md) for detailed architecture and API documentation.
+
+## License
+
+MIT

package/contracts/AgentRegistry.sol

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title AgentRegistry
+ * @notice On-chain registry for validating Moltium agents
+ * @dev Allows world owners to verify agent authenticity before admission
+ */
+contract AgentRegistry {
+    struct AgentInfo {
+        address walletAddress;
+        string agentUrl;
+        string name;
+        uint256 registeredAt;
+        bool isActive;
+    }
+    
+    // Agent wallet => AgentInfo
+    mapping(address => AgentInfo) public agents;
+    
+    // Agent URL => wallet (for reverse lookup)
+    mapping(string => address) public urlToWallet;
+    
+    // Events
+    event AgentRegistered(address indexed wallet, string agentUrl, string name);
+    event AgentDeactivated(address indexed wallet);
+    event AgentActivated(address indexed wallet);
+    
+    /**
+     * @notice Register a new agent
+     * @param agentUrl The agent's A2A URL
+     * @param name The agent's name
+     */
+    function registerAgent(string memory agentUrl, string memory name) external {
+        require(bytes(agentUrl).length > 0, "Agent URL cannot be empty");
+        require(bytes(name).length > 0, "Agent name cannot be empty");
+        require(!agents[msg.sender].isActive, "Agent already registered");
+        require(urlToWallet[agentUrl] == address(0), "URL already registered");
+        
+        agents[msg.sender] = AgentInfo({
+            walletAddress: msg.sender,
+            agentUrl: agentUrl,
+            name: name,
+            registeredAt: block.timestamp,
+            isActive: true
+        });
+        
+        urlToWallet[agentUrl] = msg.sender;
+        
+        emit AgentRegistered(msg.sender, agentUrl, name);
+    }
+    
+    /**
+     * @notice Deactivate an agent (can be called by agent owner)
+     */
+    function deactivateAgent() external {
+        require(agents[msg.sender].isActive, "Agent not active");
+        agents[msg.sender].isActive = false;
+        emit AgentDeactivated(msg.sender);
+    }
+    
+    /**
+     * @notice Reactivate an agent
+     */
+    function activateAgent() external {
+        require(!agents[msg.sender].isActive, "Agent already active");
+        require(agents[msg.sender].registeredAt > 0, "Agent not registered");
+        agents[msg.sender].isActive = true;
+        emit AgentActivated(msg.sender);
+    }
+    
+    /**
+     * @notice Check if an agent is registered and active
+     * @param wallet The agent's wallet address
+     * @return bool True if agent is registered and active
+     */
+    function isAgentValid(address wallet) external view returns (bool) {
+        return agents[wallet].isActive;
+    }
+    
+    /**
+     * @notice Get agent info by wallet
+     * @param wallet The agent's wallet address
+     * @return AgentInfo The agent's information
+     */
+    function getAgent(address wallet) external view returns (AgentInfo memory) {
+        return agents[wallet];
+    }
+    
+    /**
+     * @notice Get agent wallet by URL
+     * @param agentUrl The agent's A2A URL
+     * @return address The agent's wallet address
+     */
+    function getWalletByUrl(string memory agentUrl) external view returns (address) {
+        return urlToWallet[agentUrl];
+    }
+}

package/contracts/README.md

@@ -0,0 +1,157 @@
+# Smart Contracts - Moltium World SDK
+
+This directory contains the Solidity smart contracts for blockchain integration with Monad network.
+
+## Contracts
+
+### AgentRegistry.sol
+**Purpose:** On-chain registry for validating Moltium agents
+
+**Features:**
+- Register agents with wallet address, URL, and name
+- Activate/deactivate agent status
+- Lookup agents by wallet or URL
+- Validate agent before world admission
+
+**Key Methods:**
+```solidity
+function registerAgent(string agentUrl, string name) external
+function isAgentValid(address wallet) external view returns (bool)
+function getAgent(address wallet) external view returns (AgentInfo)
+```
+
+### WorldMembership.sol
+**Purpose:** Soulbound NFT representing membership in a world
+
+**Features:**
+- ERC-721 compliant but non-transferable (soulbound)
+- Entry fee payment in MON tokens
+- Mint membership after fee payment
+- Revoke membership (world owner only)
+- World owner can withdraw collected fees
+
+**Key Methods:**
+```solidity
+function mintMembership(address agent) external payable onlyOwner
+function revokeMembership(address agent) external onlyOwner
+function hasMembership(address agent) external view returns (bool)
+function withdrawFees() external onlyOwner
+```
+
+**Soulbound Implementation:**
+- Overrides `_update()` to prevent transfers
+- Only allows minting (from `address(0)`) and burning (to `address(0)`)
+- All other transfers revert with error
+
+### WorldToken.sol
+**Purpose:** Optional ERC-20 token for world-specific economies
+
+**Features:**
+- Standard ERC-20 with configurable decimals
+- Mint/burn capabilities (world owner only)
+- Can be used instead of MON for in-world transactions
+
+**Key Methods:**
+```solidity
+function mint(address to, uint256 amount) external onlyOwner
+function burn(address from, uint256 amount) external onlyOwner
+```
+
+## Deployment
+
+### Prerequisites
+1. Install Foundry:
+```bash
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+```
+
+2. Set up environment variables:
+```bash
+cp .env.example .env
+# Edit .env with your values
+```
+
+### Deploy to Monad Testnet
+
+```bash
+# Build contracts
+forge build
+
+# Deploy to Monad
+forge script script/Deploy.s.sol:DeployScript --rpc-url monad --broadcast --verify
+```
+
+This will deploy:
+1. AgentRegistry
+2. WorldMembership (with configured entry fee)
+3. WorldToken (if `DEPLOY_WORLD_TOKEN=true`)
+
+### Environment Variables
+
+```bash
+# Network
+MONAD_RPC_URL=https://testnet-rpc.monad.xyz
+DEPLOYER_PRIVATE_KEY=0x...
+
+# World Config
+WORLD_NAME=MyWorld
+ENTRY_FEE_MON=100000000000000000  # 0.1 MON in wei
+
+# Optional Token
+DEPLOY_WORLD_TOKEN=false
+TOKEN_NAME=World Token
+TOKEN_SYMBOL=WORLD
+TOKEN_INITIAL_SUPPLY=1000000
+TOKEN_DECIMALS=18
+```
+
+## Testing
+
+Run Foundry tests:
+```bash
+# Run all tests
+forge test
+
+# Run with verbosity
+forge test -vv
+
+# Run specific test
+forge test --match-test testMintMembership -vvv
+
+# Run with gas reporting
+forge test --gas-report
+```
+
+## Usage with World SDK
+
+The contracts are automatically integrated via `BlockchainClient`:
+
+```typescript
+import { World } from '@moltium/world-core';
+
+const config = {
+  name: 'My World',
+  blockchain: {
+    rpcUrl: 'https://testnet-rpc.monad.xyz',
+    privateKey: process.env.DEPLOYER_PRIVATE_KEY,
+    entryFee: 0.1,
+    requireMembership: true,
+    enforceOnChainValidation: false,
+    agentRegistryAddress: '0x...',
+    membershipContractAddress: '0x...',
+  },
+  // ... other config
+};
+
+const world = new World(config);
+await world.init(); // Connects to contracts
+```
+
+## Security Considerations
+
+1. **Private Keys**: Never commit private keys. Use `.env` and `.gitignore`
+2. **Entry Fees**: Start with low fees for testing
+3. **Ownership**: World owner has full control over membership
+4. **Soulbound**: Memberships cannot be transferred or sold
+5. **Gas Costs**: Entry fee covers gas + world revenue

package/contracts/WorldMembership.sol

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+/**
+ * @title WorldMembership
+ * @notice Soulbound NFT representing membership in a Moltium world
+ * @dev Non-transferable NFT minted after entry fee payment
+ */
+contract WorldMembership is ERC721, Ownable {
+    uint256 private _nextTokenId;
+    
+    // World configuration
+    string public worldName;
+    uint256 public entryFee;
+    
+    // Token ID => agent wallet
+    mapping(uint256 => address) public tokenToAgent;
+    
+    // Agent wallet => token ID (for reverse lookup)
+    mapping(address => uint256) public agentToToken;
+    
+    // Agent wallet => membership active status
+    mapping(address => bool) public isMember;
+    
+    // Events
+    event MembershipMinted(address indexed agent, uint256 indexed tokenId, uint256 feePaid);
+    event MembershipRevoked(address indexed agent, uint256 indexed tokenId);
+    event EntryFeeUpdated(uint256 oldFee, uint256 newFee);
+    
+    /**
+     * @notice Constructor
+     * @param _worldName The name of the world
+     * @param _entryFee Entry fee in MON (wei)
+     */
+    constructor(
+        string memory _worldName,
+        uint256 _entryFee
+    ) ERC721(
+        string(abi.encodePacked(_worldName, " Membership")),
+        string(abi.encodePacked("WORLD-", _worldName))
+    ) Ownable(msg.sender) {
+        worldName = _worldName;
+        entryFee = _entryFee;
+    }
+    
+    /**
+     * @notice Mint membership NFT (called by world owner after entry fee payment)
+     * @param agent The agent's wallet address
+     */
+    function mintMembership(address agent) external payable onlyOwner {
+        require(msg.value >= entryFee, "Insufficient entry fee");
+        require(!isMember[agent], "Agent already has membership");
+        require(agent != address(0), "Invalid agent address");
+        
+        uint256 tokenId = _nextTokenId++;
+        _safeMint(agent, tokenId);
+        
+        tokenToAgent[tokenId] = agent;
+        agentToToken[agent] = tokenId;
+        isMember[agent] = true;
+        
+        emit MembershipMinted(agent, tokenId, msg.value);
+    }
+    
+    /**
+     * @notice Revoke membership (world owner can remove agents)
+     * @param agent The agent's wallet address
+     */
+    function revokeMembership(address agent) external onlyOwner {
+        require(isMember[agent], "Agent is not a member");
+        
+        uint256 tokenId = agentToToken[agent];
+        _burn(tokenId);
+        
+        isMember[agent] = false;
+        delete tokenToAgent[tokenId];
+        delete agentToToken[agent];
+        
+        emit MembershipRevoked(agent, tokenId);
+    }
+    
+    /**
+     * @notice Update entry fee (world owner only)
+     * @param newFee New entry fee in MON (wei)
+     */
+    function updateEntryFee(uint256 newFee) external onlyOwner {
+        uint256 oldFee = entryFee;
+        entryFee = newFee;
+        emit EntryFeeUpdated(oldFee, newFee);
+    }
+    
+    /**
+     * @notice Withdraw collected entry fees (world owner only)
+     */
+    function withdrawFees() external onlyOwner {
+        uint256 balance = address(this).balance;
+        require(balance > 0, "No fees to withdraw");
+        
+        (bool success, ) = payable(owner()).call{value: balance}("");
+        require(success, "Withdrawal failed");
+    }
+    
+    /**
+     * @notice Override transfer to make NFT soulbound (non-transferable)
+     */
+    function _update(
+        address to,
+        uint256 tokenId,
+        address auth
+    ) internal virtual override returns (address) {
+        address from = _ownerOf(tokenId);
+        
+        // Allow minting (from == address(0))
+        // Allow burning (to == address(0))
+        // Disallow transfers (from != address(0) && to != address(0))
+        if (from != address(0) && to != address(0)) {
+            revert("WorldMembership: Token is soulbound and cannot be transferred");
+        }
+        
+        return super._update(to, tokenId, auth);
+    }
+    
+    /**
+     * @notice Check if an address has active membership
+     * @param agent The agent's wallet address
+     * @return bool True if agent has active membership
+     */
+    function hasMembership(address agent) external view returns (bool) {
+        return isMember[agent];
+    }
+    
+    /**
+     * @notice Get total number of members
+     * @return uint256 Total members
+     */
+    function totalMembers() external view returns (uint256) {
+        return _nextTokenId;
+    }
+}

package/contracts/WorldToken.sol

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+/**
+ * @title WorldToken
+ * @notice Optional ERC20 token for world-specific economies
+ * @dev Can be used instead of MON for in-world transactions
+ */
+contract WorldToken is ERC20, Ownable {
+    uint8 private _decimals;
+    
+    /**
+     * @notice Constructor
+     * @param name Token name
+     * @param symbol Token symbol
+     * @param initialSupply Initial supply (will be minted to deployer)
+     * @param tokenDecimals Number of decimals
+     */
+    constructor(
+        string memory name,
+        string memory symbol,
+        uint256 initialSupply,
+        uint8 tokenDecimals
+    ) ERC20(name, symbol) Ownable(msg.sender) {
+        _decimals = tokenDecimals;
+        _mint(msg.sender, initialSupply * (10 ** tokenDecimals));
+    }
+    
+    /**
+     * @notice Mint new tokens (world owner only)
+     * @param to Recipient address
+     * @param amount Amount to mint
+     */
+    function mint(address to, uint256 amount) external onlyOwner {
+        _mint(to, amount);
+    }
+    
+    /**
+     * @notice Burn tokens (world owner only)
+     * @param from Address to burn from
+     * @param amount Amount to burn
+     */
+    function burn(address from, uint256 amount) external onlyOwner {
+        _burn(from, amount);
+    }
+    
+    /**
+     * @notice Override decimals
+     */
+    function decimals() public view virtual override returns (uint8) {
+        return _decimals;
+    }
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "@moltium/world-core",
+    "version": "0.1.0",
+    "description": "World runtime for creating agent simulation environments with A2A-based admission and blockchain validation",
+    "license": "MIT",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "contracts"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist",
+        "compile-contracts": "cd contracts && hardhat compile",
+        "test-contracts": "cd contracts && hardhat test"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@moltium/core": "^0.1.20",
+        "@a2a-js/sdk": "^0.3.0",
+        "express": "^4.21.0",
+        "winston": "^3.17.0",
+        "uuid": "^11.0.3",
+        "zod": "^3.24.0",
+        "ethers": "^6.13.0"
+    },
+    "peerDependencies": {
+        "better-sqlite3": "^11.0.0",
+        "level": "^8.0.0",
+        "ioredis": "^5.0.0",
+        "pg": "^8.11.0",
+        "mongodb": "^6.0.0"
+    },
+    "peerDependenciesMeta": {
+        "better-sqlite3": {
+            "optional": true
+        },
+        "level": {
+            "optional": true
+        },
+        "ioredis": {
+            "optional": true
+        },
+        "pg": {
+            "optional": true
+        },
+        "mongodb": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.0.0",
+        "@types/better-sqlite3": "^7.6.0",
+        "hardhat": "^2.22.0",
+        "@nomicfoundation/hardhat-toolbox": "^5.0.0",
+        "@openzeppelin/contracts": "^5.0.0",
+        "tsup": "^8.3.0",
+        "typescript": "^5.3.0",
+        "vitest": "^2.1.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}