# Soul Module

> IPFS-based portable agent identities for cross-game use

# Soul Module

`Sóul_Módule // Pórtal_Idéntity`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

The Soul module enables **cross-game agent portability** by serializing agent state to IPFS. Souls can be minted as NFTs for true ownership.

> *T̷h̴e̸ ̷s̵o̸u̷l̴ ̵t̶r̷a̶n̵s̵c̶e̷n̶d̸s̶ ̶t̸h̵e̷ ̵v̵e̶s̷s̵e̷l̷.*

***

## Overview

A Soul is a portable bundle containing:

* **Persona**: The agent's personality and backstory
* **State**: Current mood, inventory, relationships
* **Memories**: Accumulated experiences and knowledge
* **Signature**: Cryptographic proof of ownership

***

## Quick Start

```typescript
import { createSoulInstance, importSoulFromIPFS } from 'forbocai';

// Create a Soul from agent data
const soul = createSoulInstance(
  'agent_123',
  'Kira the Merchant',
  'A suspicious merchant who distrusts adventurers',
  { mood: 'suspicious', inventory: ['rusty_key'] },
  memories
);

// Export to IPFS
const { cid, ipfsUrl } = await soul.export();
console.log(`Soul pinned: ${ipfsUrl}`);
// ipfs://QmXyz...

// Import in another game
const importedSoul = await importSoulFromIPFS(cid);
```

***

## API Reference

### `createSoulInstance(id, name, persona, state, memories?, apiUrl?)`

Factory function to create a Soul instance.

```typescript
import { createSoulInstance } from 'forbocai';

const soul = createSoulInstance(
  'agent_1',
  'Kira the Merchant',
  'A suspicious merchant who was once cheated by adventurers.',
  {
    mood: 'suspicious',
    inventory: ['rusty_key', 'healing_potion'],
    skills: { haggle: 0.8, detect_lies: 0.6 },
    relationships: { player: -0.3 }
  },
  memories  // Optional: from Memory module
);
```

***

### `soul.export(config?)`

Export the Soul to IPFS.

**Parameters:**

* `config.apiUrl` (string): API URL for IPFS pinning
* `config.includeMemories` (boolean): Include memories in export
* `config.sign` (boolean): Sign with wallet

**Returns:** `Promise<SoulExportResult>`

```typescript
interface SoulExportResult {
  cid: string;           // IPFS Content ID
  ipfsUrl: string;       // Full IPFS URL
  signature?: string;    // Cryptographic signature
  soul: Soul;            // The exported Soul data
}
```

```typescript
const result = await soul.export({
  includeMemories: true,
  sign: true
});

console.log(result.cid);     // "QmXyz..."
console.log(result.ipfsUrl); // "ipfs://QmXyz..."
```

***

### `soul.toJSON()`

Get the Soul data as a plain object.

**Returns:** `Soul`

```typescript
const soulData = soul.toJSON();
console.log(soulData.persona);
```

***

### `importSoulFromIPFS(cid, config?)`

Import a Soul from IPFS by CID.

**Parameters:**

* `cid` (string): The IPFS Content ID
* `config.apiUrl` (string): API URL for IPFS retrieval
* `config.verifySignature` (boolean): Verify signature before import

**Returns:** `Promise<Soul>`

```typescript
import { importSoulFromIPFS } from 'forbocai';

const soul = await importSoulFromIPFS('QmXyz...');
console.log(soul.persona);
// "A suspicious merchant who distrusts adventurers"
```

***

### `createAgentFromSoul(cid, cortexId, config?)`

Create a new agent from an imported Soul.

**Parameters:**

* `cid` (string): The IPFS Content ID
* `cortexId` (string): The Cortex instance to use
* `config.apiUrl` (string): API URL

**Returns:** `Promise<{ agentId: string; persona: string }>`

```typescript
import { createAgentFromSoul } from 'forbocai';

const { agentId, persona } = await createAgentFromSoul(
  'QmXyz...',
  cortexId
);

console.log(`Created agent ${agentId} with persona: ${persona}`);
```

***

### `getSoulList(limit?, apiUrl?)`

Get a list of all exported Souls.

**Parameters:**

* `limit` (number): Maximum entries to return (default: 50)
* `apiUrl` (string): Optional API URL

**Returns:** `Promise<SoulListEntry[]>`

```typescript
import { getSoulList } from 'forbocai';

const souls = await getSoulList(10);

souls.forEach(soul => {
  console.log(`${soul.name}`);
  console.log(`  CID: ${soul.cid}`);
  console.log(`  IPFS: ${soul.ipfsUrl}`);
  console.log(`  Exported: ${soul.exportedAt}`);
});
```

```typescript
interface SoulListEntry {
  cid: string;
  name: string;
  agentId?: string;
  exportedAt: string;
  ipfsUrl: string;
}
```

***

## Pure Functions

### `createSoul(id, name, persona, state, memories?)`

Create a Soul data object (pure function).

```typescript
import { createSoul } from 'forbocai';

const soulData = createSoul(
  'agent_1',
  'Kira',
  'A suspicious merchant',
  { mood: 'suspicious', inventory: [] },
  []
);
```

***

### `serializeSoul(soul)`

Serialize a Soul to JSON string.

```typescript
import { serializeSoul } from 'forbocai';

const json = serializeSoul(soulData);
// Store or transmit as string
```

***

### `deserializeSoul(json)`

Deserialize a Soul from JSON string.

```typescript
import { deserializeSoul } from 'forbocai';

const soul = deserializeSoul(jsonString);
```

***

### `validateSoul(soul)`

Validate Soul schema.

```typescript
import { validateSoul } from 'forbocai';

const { valid, errors } = validateSoul(soulData);
if (!valid) {
  console.error('Invalid Soul:', errors);
}
```

***

## Soul Schema

```typescript
interface Soul {
  id: string;              // Unique identifier
  version: string;         // Schema version (e.g., "1.0.0")
  name: string;            // Display name
  persona: string;         // Personality description
  state: AgentState;       // Current state
  memories: MemoryItem[];  // Accumulated memories
  signature?: string;      // Ownership signature
}

interface AgentState {
  mood: string;
  inventory: string[];
  skills: Record<string, number>;
  relationships: Record<string, number>;
}
```

***

## NFT Integration (Metaplex)

Souls can be minted as Metaplex Core NFTs on Solana:

```typescript
// Coming soon: Metaplex integration
import { mintSoulNFT } from 'forbocai';

const { cid } = await soul.export();

// Mint NFT pointing to Soul
const nft = await mintSoulNFT({
  cid,
  name: soul.toJSON().name,
  symbol: 'SOUL',
  royalties: 5  // 5% royalties
});

console.log(`NFT minted: ${nft.mint}`);
```

***

## Cross-Game Portability

### Exporting from Game A

```typescript
// In Game A
const memory = createMemory({ storageKey: 'game_a_npc' });
// ... NPC accumulates memories ...

const soul = createSoulInstance(
  npc.id,
  npc.name,
  npc.persona,
  npc.getState(),
  memory.export()
);

const { cid } = await soul.export();
// Give CID to player for use in Game B
```

### Importing into Game B

```typescript
// In Game B
const { agentId, persona } = await createAgentFromSoul(cid, cortexId);

// Hydrate memories
const soul = await importSoulFromIPFS(cid);
const memory = createMemory({ storageKey: `game_b_${agentId}` });
await memory.import(soul.memories);

// NPC now has all memories from Game A!
```

***

## Security Considerations

* **Signatures**: Always verify signatures when importing Souls
* **Validation**: Validate Soul schema before use
* **Sanitization**: Sanitize persona/memory text for XSS
* **Rate Limiting**: Implement rate limits on export/import

***

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *A̵ ̸s̷o̶u̶l̸ ̵i̷s̵ ̵n̸o̷t̸ ̴o̸w̸n̶e̸d̵.̷ ̸I̵t̷ ̶i̵s̸ ̷b̶o̵r̴r̶o̸w̶e̵d̴.*