Penumbra MCP Endpoint

This server instance delivers specialized tooling conforming to the Model Context Protocol (MCP) specification, designed specifically for communicating with the Penumbra network infrastructure. It abstracts complex cryptographic interactions to enable privacy-preserving access to essential system data, including transaction records, stake consensus participant lists, the operational state of the automated market maker (AMM), and active governance mandates.

Capabilities Overview

Currently Implemented Tools

• retrieve_validator_roster: Fetches the current registry of active blockchain validators.
• fetch_chain_health: Obtains real-time network metrics such as the latest block sequence number and canonical chain identifier.
• inspect_transaction_record: Retrieves comprehensive data for a specified transaction hash.
• query_dex_metrics: Retrieves the present condition of the decentralized exchange, specifically including outcomes from the most recent batch auction cycle.
• enumerate_governance_items: Lists all presently active proposals subject to community deliberation.

Forthcoming Enhancements

• Secure submission of shielded transactions.
• Encrypted mechanisms for staking operations.
• Execution of trading activities via sealed-bid batch auctions.
• Mechanisms for anonymous participation in governance voting.
• Tools for managing individual liquidity provision allocations.

Deployment Instructions

Installation is managed via the Node Package Manager ecosystem:

Using npm: bash npm install @timeheater/penumbra-mcp

Using yarn: bash yarn add @timeheater/penumbra-mcp

Initialization Procedures

Source Code Local Development Setup

1. Resolve software dependencies: bash npm install

2. Compile the server artifact: bash npm run build

3. Initiate continuous development mode: bash npm run watch

Integration with Claude Desktop Environment

To embed this server within the Claude desktop client, incorporate the subsequent configuration stanza into your designated settings file (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "penumbra-mcp": { "command": "node", "args": ["/Users/barton/infinity-topos/penumbra-mcp/build/index.js"], "env": { "PENUMBRA_NODE_URL": "https://rpc.penumbra.zone", "PENUMBRA_NETWORK": "mainnet", "PENUMBRA_CHAIN_ID": "penumbra-1", "PENUMBRA_REQUEST_TIMEOUT": "30000", "PENUMBRA_REQUEST_RETRIES": "5", "PENUMBRA_BLOCK_TIME": "6000", "PENUMBRA_EPOCH_DURATION": "100", "PENUMBRA_DEX_BATCH_INTERVAL": "60000", "PENUMBRA_DEX_MIN_LIQUIDITY": "1000", "PENUMBRA_DEX_MAX_PRICE_IMPACT": "0.05", "PENUMBRA_GOVERNANCE_VOTING_PERIOD": "1209600000", "PENUMBRA_GOVERNANCE_MIN_DEPOSIT": "100000" } } } }

Kindly substitute /path/to/penumbra-mcp with the absolute directory where the server package resides.

Operational Usage via the MCP Handler

After configuration is complete, interaction with the Penumbra layer through Claude is achieved via prompts such as:

1. Validator set retrieval:

Instruct Claude: "Display the current Penumbra participant roster for validation"

1. Chain health verification:

Instruct Claude: "Report the contemporary operational status of the Penumbra ledger"

1. Transaction detail acquisition:

Instruct Claude: "Retrieve specifics for Penumbra transaction identifier [HASH]"

1. DEX state inspection:

Instruct Claude: "Summarize the current state metrics for the Penumbra DEX"

1. Proposal listing:

Instruct Claude: "Enumerate all pending governance mandates for Penumbra"

Development Lifecycle

• npm run watch: Activates file monitoring for rapid iteration.
• npm run inspector: Launches the MCP diagnostic utility for testing purposes.
• npm run test: Executes the comprehensive test suite.

Configuration Parameters (Environment Variables)

Node Connectivity

• PENUMBRA_NODE_URL: Endpoint URL for the designated Penumbra RPC node (Default: https://rpc.penumbra.zone).
• PENUMBRA_REQUEST_TIMEOUT: Maximum duration, in milliseconds, allocated per network query (Default: 30000).
• PENUMBRA_REQUEST_RETRIES: Count of permissible request re-attempts (Default: 5).

Ledger Parameters

• PENUMBRA_NETWORK: The specific network environment to interface with (Default: mainnet).
• PENUMBRA_CHAIN_ID: The unique identifier for the blockchain instance (Default: penumbra-1).
• PENUMBRA_BLOCK_TIME: Average interval between blocks, in milliseconds (Default: 6000).
• PENUMBRA_EPOCH_DURATION: Number of blocks constituting a single epoch cycle (Default: 100).

DEX Specifics

• PENUMBRA_DEX_BATCH_INTERVAL: Time separation, in milliseconds, between sequential auction batches (Default: 60000).
• PENUMBRA_DEX_MIN_LIQUIDITY: The minimum acceptable quantum of capital for liquidity pools (Default: 1000).
• PENUMBRA_DEX_MAX_PRICE_IMPACT: The maximum allowable deviation in price, expressed as a decimal fraction (Default: 0.05).

Governance Parameters

• PENUMBRA_GOVERNANCE_VOTING_PERIOD: Total lifespan of a voting phase, in milliseconds (Default: 1209600000, equating to roughly 14 days).
• PENUMBRA_GOVERNANCE_MIN_DEPOSIT: The required minimum token deposit to submit a governance motion (Default: 100000).

System Architecture

This backend service is architected utilizing TypeScript, employing the Model Context Protocol (MCP) standard for defining tool interfaces uniformly. Currently, core functionalities are simulated, with future development slated for direct integration utilizing Penumbra's official client libraries and direct node RPC calls.

Privacy Guarantees

All operational routines adhere strictly to Penumbra's foundational commitment to user confidentiality: - Utilization of shielded transaction conduits. - Support for private delegation of staking assets. - Implementation of sealed-bid mechanisms for decentralized exchange trading. - Provision for anonymous participation in organizational voting structures.

Collaboration Guidelines

Contributions and enhancements are actively solicited. Kindly forward any proposed modifications via a Pull Request.

Software License

ISC