{"_id":"@code3-team/aptos-chain-mcp","_rev":"2-d55f71f2e0b3988d79a251af9746ab11","name":"@code3-team/aptos-chain-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@code3-team/aptos-chain-mcp","version":"0.1.0","keywords":["aptos","blockchain","mcp","code3","bounty"],"author":{"name":"Code3 Team"},"license":"MIT","_id":"@code3-team/aptos-chain-mcp@0.1.0","maintainers":[{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"}],"bin":{"aptos-chain-mcp":"dist/index.js"},"dist":{"shasum":"10ea249e26ab708a19e838a8af335e0ae35d2e72","tarball":"https://registry.npmjs.org/@code3-team/aptos-chain-mcp/-/aptos-chain-mcp-0.1.0.tgz","fileCount":78,"integrity":"sha512-rilkdalJtJVf4JEy3DKNokZhCVMMbG7eLKGXr97Uc512C73fwGYoePWQ/zpU0LDLWhlWhYFqoPvClzXhbEb0gQ==","signatures":[{"sig":"MEQCHwHoT9rvrUZQrecL7qlYOyzznxa4l1To8s0tFynOWKUCIQCBzFGCJLDvMSl7m/r8eiK6P9qjsUe2HPKlU92qXRri/A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":146990},"main":"dist/index.js","type":"module","_from":"file:code3-team-aptos-chain-mcp-0.1.0.tgz","types":"dist/index.d.ts","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","clean":"rm -rf dist","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"},"_resolved":"/private/var/folders/97/6ydtlhlx7750tcl9pk4kfx100000gn/T/49061e2c58b99976caffb3b5ac895ae1/code3-team-aptos-chain-mcp-0.1.0.tgz","_integrity":"sha512-rilkdalJtJVf4JEy3DKNokZhCVMMbG7eLKGXr97Uc512C73fwGYoePWQ/zpU0LDLWhlWhYFqoPvClzXhbEb0gQ==","_npmVersion":"10.9.0","description":"Aptos chain integration MCP tools for Code3","directories":{},"_nodeVersion":"23.0.0","dependencies":{"@aptos-labs/ts-sdk":"^1.30.0","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","vitest":"^2.0.0","typescript":"^5.7.0","@types/node":"^20.0.0","@vitest/coverage-v8":"^2.0.0","@typescript-eslint/parser":"^6.19.0","@typescript-eslint/eslint-plugin":"^6.19.0"},"_npmOperationalInternal":{"tmp":"tmp/aptos-chain-mcp_0.1.0_1759489688993_0.992082440899281","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@code3-team/aptos-chain-mcp","version":"0.1.1","description":"Aptos chain integration MCP tools for Code3","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"aptos-chain-mcp":"dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","@aptos-labs/ts-sdk":"^1.30.0"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.19.0","@typescript-eslint/parser":"^6.19.0","eslint":"^8.56.0","typescript":"^5.7.0","vitest":"^2.0.0","@vitest/coverage-v8":"^2.0.0"},"keywords":["aptos","blockchain","mcp","code3","bounty"],"author":{"name":"Code3 Team"},"license":"MIT","scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src/**/*.ts","clean":"rm -rf dist"},"_id":"@code3-team/aptos-chain-mcp@0.1.1","_integrity":"sha512-w5G5I9Z1L1vZ1CgMPBR6vfpyTGea4zP9aOFitRRdTZ4UPI7RjtMnhQP60VnqhXODVIzgbeb/fKs4pMBspGUaig==","_resolved":"/private/var/folders/97/6ydtlhlx7750tcl9pk4kfx100000gn/T/413c5db19d301c18d10db386598cbf75/code3-team-aptos-chain-mcp-0.1.1.tgz","_from":"file:code3-team-aptos-chain-mcp-0.1.1.tgz","_nodeVersion":"23.0.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-w5G5I9Z1L1vZ1CgMPBR6vfpyTGea4zP9aOFitRRdTZ4UPI7RjtMnhQP60VnqhXODVIzgbeb/fKs4pMBspGUaig==","shasum":"8d67fe05b4048a0c7d31d719c26e37aa158c9d2f","tarball":"https://registry.npmjs.org/@code3-team/aptos-chain-mcp/-/aptos-chain-mcp-0.1.1.tgz","fileCount":78,"unpackedSize":146990,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQClfrnonpeVOap5py+8BoqCzl+4OOsXL3j55UumbYL2XgIhAIlYjMyAEaKZpjBHUZXRPC3U9RQBhlj0/HHcy7MUaeM3"}]},"_npmUser":{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"},"directories":{},"maintainers":[{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aptos-chain-mcp_0.1.1_1759491888351_0.5081310098991978"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-03T11:08:08.898Z","modified":"2025-10-03T11:44:48.777Z","0.1.0":"2025-10-03T11:08:09.175Z","0.1.1":"2025-10-03T11:44:48.558Z"},"author":{"name":"Code3 Team"},"license":"MIT","keywords":["aptos","blockchain","mcp","code3","bounty"],"description":"Aptos chain integration MCP tools for Code3","maintainers":[{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"}],"readme":"# @code3-team/aptos-chain-mcp\n\n> Aptos Chain MCP Server - Blockchain interaction tools for Code3 bounty management\n>\n> **Status**: MVP Implementation\n> **Network**: Aptos Testnet (mainnet-ready)\n> **Contract**: [Code3 Bounty Contract](../../task3/aptos/sources/bounty.move)\n\n---\n\n## Installation & Setup\n\n### Quick Start (npx)\n\nAdd to your Claude Code `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@code3-team/aptos-chain-mcp\"],\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"YOUR_CONTRACT_ADDRESS\",\n        \"APTOS_PRIVATE_KEY\": \"YOUR_PRIVATE_KEY\",\n        \"APTOS_NETWORK\": \"testnet\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```bash\nAPTOS_CONTRACT_ADDRESS=0xafd0c08dbf36230f9b96eb1d23ff7ee223ad40be47917a0aba310ed90ac422a1\nAPTOS_PRIVATE_KEY=0x...\nAPTOS_NETWORK=testnet\n```\n\n**Important**: This MCP server requires the Code3 bounty contract to be deployed on Aptos. The contract source code is located at:\n- **Contract Source**: [Code3-Workspace/task3/aptos/sources/bounty.move](https://github.com/cyl19970726/Code3-Workspace/tree/main/task3/aptos)\n- **Deployment Guide**: See [task3/aptos/README.md](https://github.com/cyl19970726/Code3-Workspace/blob/main/task3/aptos/README.md)\n\n**No ABI file needed**: This MCP server calls contract functions directly using the Aptos TypeScript SDK (`@aptos-labs/ts-sdk`). Function signatures are defined in the TypeScript code.\n\n### Local Development\n\n```bash\n# Clone and build\ngit clone https://github.com/cyl19970726/Code3-Workspace.git\ncd Code3-Workspace/spec-mcp/aptos-chain-mcp\nnpm install\nnpm run build\n\n# Link locally\nnpm link\n\n# Add to .mcp.json\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"aptos-chain-mcp\",\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"${APTOS_CONTRACT_ADDRESS}\",\n        \"APTOS_PRIVATE_KEY\": \"${APTOS_PRIVATE_KEY}\",\n        \"APTOS_NETWORK\": \"${APTOS_NETWORK:-testnet}\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [MCP Tools](#mcp-tools)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Development](#development)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [Security](#security)\n- [Reference](#reference)\n\n---\n\n## Overview\n\n`@code3-team/aptos-chain-mcp` is a Model Context Protocol (MCP) server that provides AI-friendly tools for interacting with the Code3 bounty smart contract on Aptos blockchain.\n\n**Key Features**:\n- 6 MCP tools covering the complete bounty lifecycle\n- Automatic retry logic with exponential backoff\n- Comprehensive input validation\n- Contract error mapping (Move → TypeScript)\n- TypeScript SDK integration (@aptos-labs/ts-sdk ^1.30.0)\n\n**Use Cases**:\n- AI agents managing bounties on behalf of sponsors\n- Automated PR submission and verification\n- Cross-chain bounty dashboards\n- Workflow automation (e.g., Claude Desktop + MCP)\n\n---\n\n## Architecture\n\n```\n@code3-team/aptos-chain-mcp\n├── src/\n│   ├── aptos/\n│   │   └── client.ts          # Aptos SDK wrapper\n│   ├── tools/\n│   │   ├── create-bounty.ts   # Tool 1: Create bounty\n│   │   ├── accept-bounty.ts   # Tool 2: Accept bounty\n│   │   ├── submit-pr.ts       # Tool 3: Submit PR\n│   │   ├── mark-merged.ts     # Tool 4: Mark PR as merged\n│   │   ├── claim-payout.ts    # Tool 5: Claim payout\n│   │   └── cancel-bounty.ts   # Tool 6: Cancel bounty\n│   ├── utils/\n│   │   ├── errors.ts          # Error handling & contract error mapping\n│   │   ├── retry.ts           # Retry logic with backoff\n│   │   └── validation.ts      # Input validation\n│   ├── types.ts               # TypeScript type definitions\n│   ├── config.ts              # Environment variable loading\n│   ├── server.ts              # MCP server implementation\n│   └── index.ts               # Entry point\n└── dist/                      # Compiled JavaScript (ESM)\n```\n\n---\n\n## MCP Tools\n\n### 1. `create_bounty`\n\nCreate a new bounty for a GitHub issue.\n\n**Input**:\n```typescript\n{\n  repo_url: string;     // e.g., \"https://github.com/owner/repo\"\n  issue_hash: string;   // SHA-256 hash (64 hex chars)\n  asset: string;        // Aptos asset address (e.g., USDT)\n  amount: string;       // Amount in base units (e.g., \"1000000\" for 1 USDT)\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  repo_url: string;\n  issue_hash: string;\n  amount: string;\n  status: \"Open\";\n}\n```\n\n**Example**:\n```bash\n# Via Claude Desktop\nUser: Create a bounty for issue #42 in github.com/code3/core\n      - Asset: 0x1::aptos_coin::AptosCoin\n      - Amount: 10 APT\n\nAI: [calls create_bounty tool with proper parameters]\n```\n\n---\n\n### 2. `accept_bounty`\n\nAccept a bounty (marks it as \"Started\").\n\n**Input**:\n```typescript\n{\n  bounty_id: string;  // e.g., \"1\"\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  winner: string;     // Developer's address\n  status: \"Started\";\n}\n```\n\n**Preconditions**:\n- Bounty must be in `Open` status\n- Any developer can accept (first-come-first-serve)\n\n---\n\n### 3. `submit_pr`\n\nSubmit a pull request URL for a bounty.\n\n**Input**:\n```typescript\n{\n  bounty_id: string;\n  pr_url: string;       // e.g., \"https://github.com/owner/repo/pull/123\"\n  pr_digest: string;    // SHA-256 hash of PR metadata\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  pr_url: string;\n  status: \"PRSubmitted\";\n}\n```\n\n**Preconditions**:\n- Bounty must be in `Started` status\n- Caller must be the winner\n\n---\n\n### 4. `mark_merged`\n\nMark a PR as merged (sponsor only) and start 7-day cooling period.\n\n**Input**:\n```typescript\n{\n  bounty_id: string;\n  pr_url: string;       // Must match submitted PR URL\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  merged_at: number;       // Unix timestamp\n  cooling_until: number;   // merged_at + 7 days\n  status: \"CoolingDown\";\n}\n```\n\n**Preconditions**:\n- Bounty must be in `PRSubmitted` status\n- Caller must be the sponsor\n- PR URL must match\n\n---\n\n### 5. `claim_payout`\n\nClaim payout after cooling period ends (winner only).\n\n**Input**:\n```typescript\n{\n  bounty_id: string;\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  amount: string;\n  winner: string;\n  status: \"Paid\";\n}\n```\n\n**Preconditions**:\n- Bounty must be in `CoolingDown` status\n- Caller must be the winner\n- Cooling period must have ended\n\n---\n\n### 6. `cancel_bounty`\n\nCancel a bounty (sponsor only, before PR submission).\n\n**Input**:\n```typescript\n{\n  bounty_id: string;\n}\n```\n\n**Output**:\n```typescript\n{\n  bounty_id: string;\n  tx_hash: string;\n  refund_amount: string;\n  sponsor: string;\n  status: \"Cancelled\";\n}\n```\n\n**Preconditions**:\n- Bounty must be in `Open` or `Started` status\n- Caller must be the sponsor\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+ (ESM support)\n- Aptos CLI (for deployment)\n- Aptos account with private key\n\n### Install from source\n\n```bash\ncd Code3/spec-mcp/aptos-mcp\nnpm install\nnpm run build\n```\n\n### Verify installation\n\n```bash\nnpm run start --help\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\nCreate `.env` file in the MCP server directory:\n\n```bash\n# Required\nAPTOS_CONTRACT_ADDRESS=0x<contract_address>\n\n# Optional\nAPTOS_NETWORK=testnet                    # testnet | mainnet | devnet\nAPTOS_NODE_URL=https://...               # Custom node URL (optional)\nAPTOS_PRIVATE_KEY=0x<your_private_key>   # For write operations\n```\n\n**Security**:\n- ⚠️ **NEVER commit `.env` to git**\n- Use environment-specific files (`.env.testnet`, `.env.mainnet`)\n- For production, use system keychain or secret management service\n\n### Contract Deployment\n\n**Before using this MCP server**, you must deploy the Code3 bounty contract to Aptos:\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/cyl19970726/Code3-Workspace.git\n   cd Code3-Workspace/task3/aptos\n   ```\n\n2. **Deploy the contract** (see [task3/aptos/README.md](https://github.com/cyl19970726/Code3-Workspace/blob/main/task3/aptos/README.md)):\n   ```bash\n   # Deploy to testnet\n   aptos move publish --network testnet --named-addresses code3=<your_address>\n\n   # Or use the deployment script\n   ./scripts/deploy_testnet.sh\n   ```\n\n3. **Copy the contract address** to your `.env` file as `APTOS_CONTRACT_ADDRESS`.\n\n**Architecture Note**: This MCP server does **not** use ABI files. It calls contract functions directly using the Aptos TypeScript SDK (`@aptos-labs/ts-sdk`). Function signatures are hardcoded in the TypeScript source code (see `src/tools/*.ts`).\n\n### Read-Only Mode\n\nIf `APTOS_PRIVATE_KEY` is not set, the MCP server runs in **read-only mode**:\n- Only view functions work (e.g., get_bounty)\n- Write operations will fail with `PRIVATE_KEY_MISSING` error\n\n---\n\n## Usage\n\n### 1. Start MCP Server (Standalone)\n\n```bash\nnpm run start\n```\n\n**Output**:\n```\n[MCP Server] Aptos Chain MCP Server started\n[MCP Server] Network: testnet\n[MCP Server] Contract: 0x1234...\n[MCP Server] Account: 0x5678... (or \"Read-only mode\")\n```\n\n### 2. Integrate with Claude Code\n\n**Quick Setup** (Recommended):\n\n```bash\n# 1. Deploy contract and generate .env files\ncd Code3/task3/aptos\n./scripts/deploy_testnet.sh\n./scripts/setup_env.sh testnet\n\n# 2. Create .mcp.json in Code3 directory\ncd Code3\ncat > .mcp.json <<'EOF'\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"${workspaceFolder}/spec-mcp/aptos-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"${APTOS_CONTRACT_ADDRESS}\",\n        \"APTOS_PRIVATE_KEY\": \"${APTOS_PRIVATE_KEY}\",\n        \"APTOS_NETWORK\": \"${APTOS_NETWORK:-testnet}\"\n      }\n    }\n  }\n}\nEOF\n\n# 3. Export environment variables from Code3/.env\nexport $(cat Code3/.env | xargs)\n\n# 4. Restart Claude Code\n# MCP server will auto-load\n```\n\n**Manual Configuration** (`.mcp.json` in project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/Code3/spec-mcp/aptos-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"0xafd0c08dbf36230f9b96eb1d23ff7ee223ad40be47917a0aba310ed90ac422a1\",\n        \"APTOS_PRIVATE_KEY\": \"0xd38396d0b2c37d930de3eba9d45af4e209f6c3e05eb46c44dc68eaaba3236b34\",\n        \"APTOS_NETWORK\": \"testnet\"\n      }\n    }\n  }\n}\n```\n\n**Using environment variable expansion** (`.mcp.json` in Code3/):\n\n```json\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"${workspaceFolder}/spec-mcp/aptos-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"${APTOS_CONTRACT_ADDRESS}\",\n        \"APTOS_PRIVATE_KEY\": \"${APTOS_PRIVATE_KEY:-}\",\n        \"APTOS_NETWORK\": \"${APTOS_NETWORK:-testnet}\"\n      }\n    }\n  }\n}\n```\n\n**Verify MCP server is loaded**:\n\n```\nUser: List available Aptos Chain MCP tools\n\nAI: Available tools:\n    - create_bounty\n    - accept_bounty\n    - submit_pr\n    - mark_merged\n    - claim_payout\n    - cancel_bounty\n```\n\n**Usage example**:\n\n```\nUser: Create a bounty for github.com/cyl19970726/Code3 issue #1 with 1 APT\n\nAI: [automatically calls create_bounty tool]\n    ✅ Bounty created!\n    - Bounty ID: 1\n    - Transaction: 0xabc...\n    - Status: Open\n    - View on explorer: https://explorer.aptoslabs.com/txn/0xabc...?network=testnet\n```\n\n**Reference**: [Claude Code MCP Documentation](https://docs.claude.com/en/docs/claude-code/mcp)\n\n---\n\n### 3. Integrate with Claude Desktop\n\nAdd to `claude_desktop_config.json` (usually at `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"aptos-chain\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/Code3/spec-mcp/aptos-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"APTOS_CONTRACT_ADDRESS\": \"0x...\",\n        \"APTOS_PRIVATE_KEY\": \"0x...\",\n        \"APTOS_NETWORK\": \"testnet\"\n      }\n    }\n  }\n}\n```\n\n**Restart Claude Desktop**, then:\n\n```\nUser: Create a bounty for github.com/code3/core issue #1 with 10 APT\n\nAI: [automatically calls create_bounty tool]\n    ✅ Bounty created! ID: 1, TX: 0xabc...\n```\n\n### 4. Programmatic Usage\n\n```typescript\nimport { AptosClient } from \"@code3-team/aptos-chain-mcp\";\n\nconst client = new AptosClient({\n  network: \"testnet\",\n  contractAddress: \"0x...\",\n  privateKey: \"0x...\",\n});\n\n// Create bounty\nconst txResult = await client.createBounty(\n  \"https://github.com/code3/core\",\n  \"a\".repeat(64), // issue_hash\n  \"0x1::aptos_coin::AptosCoin\",\n  \"10000000\" // 10 APT\n);\n\nconsole.log(\"Bounty created:\", txResult.hash);\n\n// Get bounty info\nconst bounty = await client.getBounty(\"1\");\nconsole.log(\"Bounty status:\", bounty?.status);\n```\n\n---\n\n## Development\n\n### Project Structure\n\n```\naptos-mcp/\n├── src/                    # TypeScript source\n│   ├── aptos/\n│   ├── tools/\n│   ├── utils/\n│   ├── types.ts\n│   ├── config.ts\n│   ├── server.ts\n│   └── index.ts\n├── dist/                   # Compiled JavaScript (ESM)\n├── package.json\n├── tsconfig.json\n├── .env                    # Environment variables (gitignored)\n└── README.md\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Run in Development\n\n```bash\nnpm run dev\n```\n\n### Linting\n\n```bash\nnpm run lint\n```\n\n---\n\n## Testing\n\n### Unit Tests (Planned)\n\n```bash\nnpm run test\n```\n\n### Manual Testing with Testnet\n\n1. **Deploy contract** (see [task3/aptos/README.md](../../task3/aptos/README.md)):\n   ```bash\n   cd ../../task3/aptos\n   ./scripts/deploy_testnet.sh\n   ```\n\n2. **Set environment variables**:\n   ```bash\n   export APTOS_CONTRACT_ADDRESS=$(cat ../../.env.testnet | grep APTOS_CONTRACT_ADDRESS_TESTNET | cut -d'=' -f2)\n   export APTOS_PRIVATE_KEY=0x<your_key>\n   ```\n\n3. **Run MCP server**:\n   ```bash\n   npm run start\n   ```\n\n4. **Test with Claude Desktop** or programmatic client.\n\n---\n\n## Deployment\n\n### To Production (Mainnet)\n\n1. **Deploy contract to mainnet**:\n   ```bash\n   cd ../../task3/aptos\n   # Edit scripts/deploy_testnet.sh to use mainnet\n   # Or create scripts/deploy_mainnet.sh\n   aptos move publish --network mainnet --named-addresses code3=$YOUR_ACCOUNT\n   ```\n\n2. **Update environment**:\n   ```bash\n   APTOS_NETWORK=mainnet\n   APTOS_CONTRACT_ADDRESS=0x<mainnet_address>\n   APTOS_NODE_URL=https://fullnode.mainnet.aptoslabs.com/v1\n   APTOS_PRIVATE_KEY=0x<production_key>\n   ```\n\n3. **Security hardening**:\n   - Use system keychain for private key\n   - Enable rate limiting\n   - Add transaction monitoring\n\n---\n\n## Security\n\n### Best Practices\n\n1. **Private Key Management**:\n   - ✅ Use environment variables (`.env`)\n   - ✅ Use system keychain in production\n   - ❌ **NEVER** hardcode private keys\n\n2. **Input Validation**:\n   - All MCP tools validate inputs before submission\n   - URL format checking (HTTPS required)\n   - Amount bounds checking (u64 max)\n   - Address format validation\n\n3. **Error Handling**:\n   - Contract errors are mapped to TypeScript error codes\n   - Sensitive data is **NOT** logged\n   - Retry logic prevents network failures\n\n4. **Network Security**:\n   - HTTPS required for GitHub URLs\n   - Custom node URLs must be validated\n   - Transaction signing happens locally (never sends private key)\n\n### Vulnerability Disclosure\n\nIf you discover a security issue, please email: **security@code3.com** (placeholder)\n\n---\n\n## Reference\n\n### Related Documentation\n\n- [Code3 Architecture](../../Code3/docs/02-architecture.md)\n- [Data Model](../../Code3/docs/05-data-model.md)\n- [Aptos Smart Contract](../../task3/aptos/sources/bounty.move)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n\n### Dependencies\n\n- `@aptos-labs/ts-sdk` ^1.30.0 - Aptos TypeScript SDK\n- `@modelcontextprotocol/sdk` ^1.0.4 - MCP SDK\n\n### Error Codes\n\nSee [src/utils/errors.ts](./src/utils/errors.ts) for complete list:\n\n| Code | Description |\n|------|-------------|\n| `BOUNTY_NOT_FOUND` | Bounty ID does not exist |\n| `INVALID_STATUS` | Bounty not in required status |\n| `NOT_SPONSOR` | Caller is not the sponsor |\n| `NOT_WINNER` | Caller is not the winner |\n| `COOLING_PERIOD_NOT_ENDED` | Cannot claim yet (< 7 days) |\n| `TRANSACTION_FAILED` | Transaction submission failed |\n| `NETWORK_ERROR` | Network connectivity issue |\n| ... | (9 total error codes) |\n\n### State Machine\n\n```\nOpen (0) → Started (1) → PRSubmitted (2) → Merged (3) → CoolingDown (4) → Paid (5)\n   ↓\nCancelled (6)\n```\n\n**Transitions**:\n- `create_bounty`: → Open\n- `accept_bounty`: Open → Started\n- `submit_pr`: Started → PRSubmitted\n- `mark_merged`: PRSubmitted → CoolingDown\n- `claim_payout`: CoolingDown → Paid\n- `cancel_bounty`: Open/Started → Cancelled\n\n---\n\n## License\n\nMIT (placeholder)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) (placeholder)\n\n---\n\n**Built with ❤️ for Code3**\n","readmeFilename":"README.md"}