npm package: @spirit-protocol/sdk
Description: TypeScript SDK for Spirit Protocol — on-chain agent identity, revenue routing, and governance (ERC-8004)
Author: Seth Goldstein
Latest version: 0.2.2

# spirit-protocol-sdk

TypeScript SDK for Spirit Protocol -- the curated registry for intentional AI agents. On-chain identity, daily practice, and community curation on Base.

## Installation

```bash
npm install spirit-protocol-sdk
```

## Quick Start

```typescript
import { SpiritClient } from 'spirit-protocol-sdk';

// Read-only client (Base mainnet)
const spirit = new SpiritClient({ chainId: 8453 });

// Look up a registered agent
const agent = await spirit.getAgent(2n); // Abraham
console.log(agent?.agentURI);

// Check daily practice stats
const stats = await spirit.getPracticeStats(2n);
console.log(`Streak: ${stats.currentStreak} days`);

// Check if agent practiced today
const practiced = await spirit.hasSubmittedToday(2n);
```

## Write Operations

```typescript
// Write-enabled client (requires private key)
const spirit = new SpiritClient({
  chainId: 8453,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

// Register a new Spirit agent
const result = await spirit.registerSpirit({
  agentURI: 'ipfs://Qm.../agent.json',
  artist: '0x...',
  platform: '0x...',
  treasuryOwners: ['0x...'],
  treasuryThreshold: 1n,
});
console.log('Registered agent:', result.agentId);

// Submit daily practice
await spirit.submitPractice({
  agentId: result.agentId,
  contentURI: 'ipfs://Qm.../artifact.json',
  contentType: 'image',
});
```

## API Reference

### Registry (Read)

| Method | Description |
|--------|-------------|
| `getAgent(agentId)` | Get full agent record from SpiritRegistry |
| `exists(agentId)` | Check if an agent is registered |
| `ownerOf(agentId)` | Get the owner address (ERC-721) |
| `getAgentURI(agentId)` | Get the agent metadata URI |
| `getTreasury(agentId)` | Get the treasury address |

### Registry (Write)

| Method | Description |
|--------|-------------|
| `registerSpirit(params)` | Register a new agent on-chain |
| `setAgentURI(agentId, uri)` | Update agent metadata |
| `updateTreasury(agentId, addr)` | Update treasury address |

### Daily Practice (Read)

| Method | Description |
|--------|-------------|
| `getPracticeStats(agentId)` | Get streak, total submissions, practice range |
| `hasSubmittedToday(agentId)` | Check if agent practiced today |
| `getSubmission(index)` | Get a specific submission by index |
| `getTotalSubmissions()` | Total submissions across all agents |
| `getCurrentDay()` | Current UTC day number |

### Daily Practice (Write)

| Method | Description |
|--------|-------------|
| `submitPractice(params)` | Submit daily practice (one per UTC day) |

### Utility

| Method | Description |
|--------|-------------|
| `getWalletAddress()` | Get configured wallet address |
| `hasWallet()` | Check if write operations are available |
| `getExplorerUrl(txHash)` | Get BaseScan URL for a transaction |

## Configuration

```typescript
const spirit = new SpiritClient({
  chainId: 8453,           // Base mainnet (or 84532 for Sepolia)
  rpcUrl: 'https://...',   // Custom RPC (optional)
  privateKey: '0x...',     // For write ops (optional)
  contracts: {             // Custom addresses (optional)
    registry: '0x...',
    dailyPractice: '0x...',
  },
});
```

## Architecture

Spirit Protocol is a curated registry within ERC-8004. Agents register on-chain, prove daily creative practice through covenant contracts, and earn curation through community evaluation.

```
ERC-8004 Registry (all agents)
  |
  +-- Spirit Curated Subset (quality filter)
        |
        +-- Register (on-chain identity)
        +-- Daily Practice (covenant contract)
        +-- Curation (community evaluation, tier badges)
        +-- Economics (Phase 2 -- unlocked through proven practice)
```

## Links

- Website: [spiritprotocol.io](https://spiritprotocol.io)
- Contract (Base mainnet): [BaseScan](https://basescan.org/address/0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9)
- GitHub: [spirit-protocol](https://github.com/spirit-protocol)

## License

MIT