Agent Pocket Relay Server

A lightweight WebSocket relay server for the Agent Pocket Extension. It facilitates secure communication between DApps (Senders) and the Wallet (Receiver).

Documentation

• Server Specification
• Wallet Requirements
• WebSocket Protocol Example
• Original Rules

Features

• WebSocket-based Communication: Real-time message relay.
• Wallet Authentication: Secure handshake using Ethereum signatures (EIP-191).
• Authenticated Routing: Requests are routed to verified wallet addresses.
• Ed25519 Signed Requests: All incoming requests from senders must be signed.
• Test Suite: Integrated test client for verifying transaction and message signing flows.

Prerequisites

• Node.js (v16 or higher)
• npm

Installation

1. Clone the repository.
2. Install dependencies:

npm install

Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and configure the following:
   • PORT: Server port (default 8080).
   • HOST: Server host (default localhost).
   • WS_URL: WebSocket URL (e.g., ws://localhost:8080).
   • TEST_SECRET_KEY: Base58 encoded Ed25519 secret key for the test sender.
   • TARGET_ADDRESS: The Ethereum address of the wallet you want to test against.
   • TEST_CHAIN_ID: Required chain ID for transaction tests (sign_transaction / send_transaction), default 56.

Running the Server

Start the relay server:

npm start
# OR
node server.js

Wallet Integration

Wallets must authenticate immediately upon connection using a signed handshake. See Wallet Requirements for the detailed specification.

Verify Authentication

To verify that the server correctly handles wallet authentication:

node verify_auth.js

Testing

The project includes a test client (test.js) that acts as a Sender. It connects to the server and sends requests to the TARGET_ADDRESS configured in .env.

Note: You must have a real wallet connected and authenticated to the server for these tests to succeed.

Test Modes

1. Sign Transaction (Default): Requests the wallet to sign a sample transaction.

   npm run test:tx

2. Sign Message: Requests the wallet to sign a text message.

   npm run test:msg

3. Send Transaction: Requests the wallet to sign and broadcast a transaction.

   npm run test:send

Project Structure

• server.js: The WebSocket Relay Server implementation.
• test.js: The Sender Simulation Client.
• verify_auth.js: Script to verify wallet authentication handshake.
• docs/: detailed documentation.