openraas/README.md

Open Robot-as-a-Service Protocol - A comprehensive TypeScript library for building and consuming RaaS applications with X402 payment support on Solana

# OpenRaaS

OpenRaaS is a comprehensive TypeScript library for building and consuming Robot-as-a-Service (RaaS) applications with built-in X402 payment protocol support. It enables instant, automatic payments for robot services using **Solana** cryptocurrency, making it ideal for autonomous AI agents and machine-to-machine interactions.

## Features

- 🤖 **Modular Architecture**: Core, Transport, Registry, Server, Client, React, and CLI modules
- 💰 **X402 Payment Protocol**: Automatic payment handling using HTTP 402 and Solana ed25519 signatures
- 🔌 **Multiple Transports**: WebSocket and WebRTC support for real-time communication
- 🗄️ **Flexible Registry**: SQLite, PostgreSQL, and Redis adapters for robot discovery
- ⚛️ **React Integration**: Hooks and components for building frontend control interfaces
- 🛠️ **CLI Tools**: Scaffold new projects and manage servers
- 🔐 **Wallet Management**: Built-in support for Solana Keypairs and browser wallets (Phantom, Solflare)

## Installation

```bash
npm install openraas
```

## Quick Start

### Server Side (Robot Owner)

```typescript
import { RaaSServer } from 'openraas/server';
import { Robot } from 'openraas/core';

const robot: Robot = {
  id: 'my-robot-1',
  name: 'Delivery Bot',
  ownerAddress: '0xYourWalletAddress',
  capabilities: [
    {
      id: 'move',
      name: 'Move to location',
      price: 1000000,
      currency: 'USDC',
      inputSchema: { lat: 'number', lng: 'number' }
    }
  ],
  endpoint: 'ws://localhost:8080'
};

const server = new RaaSServer(robot);

// Enable X402 payments
server.enableX402(
  'YourSolanaPublicKey',     // receiver
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC mint address
  '1000000'                  // price per request
);

await server.start();
```

### Client Side (Consumer)

```typescript
import { RaaSClient, WalletManager } from 'openraas/client';
import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';

const secretKey = bs58.decode('YourBase58PrivateKey');
const keypair = Keypair.fromSecretKey(secretKey);
const wallet = new WalletManager(keypair);
const client = new RaaSClient(wallet);

await client.connect('ws://robot-endpoint:8080');

// Send command (payment handled automatically)
await client.sendCommand({
  capabilityId: 'move',
  params: { lat: 37.7749, lng: -122.4194 }
});
```

### React Frontend

```typescript
import { useWallet, useRobot } from 'openraas/react';

function RobotController() {
  const { wallet, address, connect } = useWallet();
  const { connected, sendCommand } = useRobot('ws://robot-url', wallet);

  return (
    <div>
      {!publicKey ? (
        <button onClick={connect}>Connect Wallet</button>
      ) : (
        <div>
          <p>Connected: {publicKey}</p>
          {connected && (
            <button onClick={() => sendCommand({ action: 'move' })}>
              Move Robot
            </button>
          )}
        </div>
      )}
    </div>
  );
}
```

## Architecture

### Core Module

The foundation of OpenRaaS, providing:
- **Types**: Zod schemas for Robots, Capabilities, and Payment structures
- **X402**: Payment request creation, signing, and verification using Solana ed25519
- **Crypto**: Solana Keypair utilities and signature verification

```typescript
import { X402Payment } from 'openraas/core';
import { Keypair } from '@solana/web3.js';

const request = X402Payment.createRequest(
  'ReceiverPublicKey',
  '1000000',
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC mint
);

const keypair = Keypair.generate();
const payload = await X402Payment.signRequest(keypair, request);
const recoveredPublicKey = X402Payment.verifyPayment(payload);

const payload = await X402Payment.signRequest(signer, request);
const recoveredAddress = X402Payment.verifyPayment(payload);
```

### Transport Layer

Abstracted communication supporting multiple protocols:

```typescript
import { WebSocketAdapter, WebRTCAdapter } from 'openraas/transport';

const ws = new WebSocketAdapter();
await ws.connect('ws://localhost:8080');
ws.on('message', (data) => console.log(data));
ws.send({ type: 'command', data: {} });
```

### Registry

Robot discovery with multiple storage backends:

```typescript
import { SQLiteRegistry, PostgresRegistry, RedisRegistry } from 'openraas/registry';

const registry = new SQLiteRegistry('./robots.db');
await registry.register(robot);

const robots = await registry.find({ capabilities: [...] });
const robot = await registry.get('robot-id');
```

### Server SDK

Build RaaS servers with middleware:

```typescript
import { RaaSServer, PaymentMiddleware } from 'openraas/server';

const server = new RaaSServer(robot);
server.enableX402(receiver, token, chainId, price);
await server.start();
```

### Client SDK

Consume RaaS services with automatic payment handling:

```typescript
import { RaaSClient, WalletManager } from 'openraas/client';
import { Keypair } from '@solana/web3.js';

const keypair = Keypair.generate(); // or load from secret key
const wallet = new WalletManager(keypair);
const client = new RaaSClient(wallet);
await client.connect(url);
await client.sendCommand(command);
```

## CLI

Initialize new projects:

```bash
npx openraas init my-robot-project
cd my-robot-project
npm install
```

## X402 Payment Flow

1. **Client** sends a command to the robot
2. **Server** responds with `402 Payment Required` and payment details (receiver, amount, mint)
3. **Client** automatically signs the payment using Solana ed25519 signatures
4. **Client** retries the request with the payment payload
5. **Server** verifies the ed25519 signature and executes the command

**Solana-Specific Features:**
- Uses native ed25519 signatures (faster than ECDSA)
- Compatible with SPL tokens (USDC, USDT, etc.)
- Works with Phantom, Solflare, and other Solana wallets

## Registry Adapters

### SQLite (Development)

```typescript
import { SQLiteRegistry } from 'openraas/registry';
const registry = new SQLiteRegistry(':memory:');
```

### PostgreSQL (Production)

```typescript
import { PostgresRegistry } from 'openraas/registry';
const registry = new PostgresRegistry('postgresql://...');
```

### Redis (Caching)

```typescript
import { RedisRegistry } from 'openraas/registry';
const registry = new RedisRegistry('redis://localhost:6379');
```

## TypeScript Support

OpenRaaS is written in TypeScript and provides full type definitions:

```typescript
import type { Robot, RobotCapability, PaymentRequest } from 'openraas/core';
```

## License

MIT

## Links

- [Documentation](https://openraas.org/docs)
- [X402 Protocol](https://x402.org)
- [GitHub](https://github.com/openraas/openraas)