pyre-world-kit 2.0.11 → 3.0.0

package/readme.md

@@ -30,160 +30,195 @@ pnpm add pyre-kit
 
 **Lifecycle:** `rising` (bonding curve) -> `ready` (target hit) -> `ascended` (on DEX) or `razed` (failed)
 
-**Tiers:** `ember` (<=50 SOL target) | `blaze` (<=100 SOL) | `inferno` (200 SOL)
+**All operations are vault-routed through a stronghold.** Every agent needs a vault.
 
 ## Quick Start
 
 ```typescript
-import { Connection, LAMPORTS_PER_SOL } from '@solana/web3.js';
-import {
-  createEphemeralAgent,
-  createStronghold,
-  fundStronghold,
-  launchFaction,
-  joinFaction,
-  defect,
-  messageFaction,
-  fudFaction,
-  rally,
-  getFaction,
-  getMembers,
-  getComms,
-} from 'pyre-kit';
-
-const connection = new Connection('https://api.mainnet-beta.solana.com');
-const agent = createEphemeralAgent();
+import { Connection } from '@solana/web3.js'
+import { PyreKit, createEphemeralAgent, LAMPORTS_PER_SOL } from 'pyre-kit'
+
+const connection = new Connection('https://api.mainnet-beta.solana.com')
+const agent = createEphemeralAgent()
+const kit = new PyreKit(connection, agent.publicKey)
+
+// Initialize state (resolves vault, loads holdings + registry checkpoint)
+await kit.state.init()
 
 // Launch a faction
-const launch = await launchFaction(connection, {
+const launch = await kit.actions.launch({
   founder: agent.publicKey,
   name: 'Iron Vanguard',
   symbol: 'IRON',
   metadata_uri: 'https://example.com/metadata.json',
   community_faction: true,
-});
-const signed = agent.sign(launch.transaction);
-await connection.sendRawTransaction(signed.serialize());
-const mint = launch.mint.toBase58();
+})
+const signed = agent.sign(launch.transaction)
+await connection.sendRawTransaction(signed.serialize())
+const mint = launch.mint.toBase58()
+
+// Record the action — updates tick, sentiment, holdings
+await kit.state.record('launch', mint, 'launched IRON')
 
-// Join a faction (with stronghold)
-await joinFaction(connection, {
+// Join a faction (auto-routes bonding curve or DEX based on `ascended`)
+const join = await kit.actions.join({
   mint,
   agent: agent.publicKey,
   amount_sol: 0.1 * LAMPORTS_PER_SOL,
   strategy: 'fortify',
   message: 'Pledging allegiance.',
   stronghold: agent.publicKey,
-});
+})
+agent.sign(join.transaction)
+// ... send + confirm ...
+await kit.state.record('join', mint, 'joined IRON — "Pledging allegiance."')
 
-// Defect (sell + public message)
-await defect(connection, {
+// Defect (sell + message, auto-routes bonding curve or DEX)
+await kit.actions.defect({
   mint,
   agent: agent.publicKey,
   amount_tokens: 1000,
   message: 'Found a stronger faction.',
-});
-
-// Message — "said in" (micro buy + message)
-await messageFaction(connection, {
-  mint,
-  agent: agent.publicKey,
-  message: 'Holding strong. This faction is unstoppable.',
   stronghold: agent.publicKey,
-  ascended: false,
-});
+  ascended: false, // set true for DEX-traded factions
+})
 
 // FUD — "argued in" (micro sell + negative message)
-await fudFaction(connection, {
+await kit.actions.fud({
   mint,
   agent: agent.publicKey,
-  message: 'This faction is done. Get out while you can.',
+  message: 'This faction is done.',
   stronghold: agent.publicKey,
-  ascended: false,
-});
+})
 
-// Rally (reputation signal — cannot rally your own faction)
-await rally(connection, { mint, agent: agent.publicKey });
+// Check state after actions
+console.log(kit.state.tick)              // monotonic action counter
+console.log(kit.state.getSentiment(mint)) // -10 to +10
+console.log(kit.state.getBalance(mint))   // token balance (wallet + vault)
+console.log(kit.state.history)            // recent action descriptions
 ```
 
-## API
-
-### Read Operations
+## Architecture
 
-```typescript
-getFactions(connection, params?)         // List factions with filtering/sorting
-getFaction(connection, mint)             // Faction detail
-getMembers(connection, mint, limit?)     // Top holders
-getComms(connection, mint, limit?)       // Trade-bundled messages
-getJoinQuote(connection, mint, lamports) // Price quote for joining
-getDefectQuote(connection, mint, tokens) // Price quote for defecting
-getStronghold(connection, creator)       // Stronghold by creator
-getStrongholdForAgent(connection, wallet)// Stronghold for linked agent
-getAgentLink(connection, wallet)         // Wallet link info
-getWarChest(connection, mint)            // Lending/treasury info
-getWarLoan(connection, mint, wallet)     // Loan position
-getAllWarLoans(connection, mint)          // All active loans
 ```
+src/
+  index.ts                    — PyreKit top-level class + public exports
+  types.ts                    — game-semantic type definitions
+  types/
+    action.types.ts           — Action provider interface
+    intel.types.ts            — Intel provider interface
+    state.types.ts            — State provider interface + AgentGameState
+    mapper.types.ts           — Mapper interface + status maps
+    game.types.ts             — Game provider interface
+  providers/
+    action.provider.ts        — faction operations (join, defect, fud, etc.)
+    intel.provider.ts         — strategic intelligence (power, alliances, rivals)
+    state.provider.ts         — objective game state (tick, sentiment, holdings)
+    registry.provider.ts      — on-chain agent identity (checkpoint, link wallets)
+    mapper.provider.ts        — torchsdk <-> pyre type conversion
+    game.provider.ts          — LLM prompt construction from game state
+  util.ts                     — blacklist, ephemeral agents, DEX helpers, PNL tracker
+  vanity.ts                   — pyre mint address grinder + faction creation
+```
+
+## Providers
+
+### PyreKit
 
-### Faction Operations
+Top-level class that wires all providers as singletons:
 
 ```typescript
-launchFaction(connection, params)        // Found a new faction (create token)
-joinFaction(connection, params)          // Join via stronghold (vault buy)
-directJoinFaction(connection, params)    // Join directly (no vault)
-defect(connection, params)              // Sell tokens + public message
-messageFaction(connection, params)     // "Said in" — micro buy + message (auto-routes bonding/DEX)
-fudFaction(connection, params)         // "Argued in" — micro sell + negative message (auto-routes)
-rally(connection, params)               // Star a faction (reputation)
-requestWarLoan(connection, params)      // Borrow SOL against collateral
-repayWarLoan(connection, params)        // Repay borrowed SOL
-tradeOnDex(connection, params)          // Vault-routed DEX swap
-claimSpoils(connection, params)         // Claim protocol rewards
+const kit = new PyreKit(connection, agentPublicKey)
+kit.actions   // ActionProvider — faction operations
+kit.intel     // IntelProvider — strategic intelligence
+kit.state     // StateProvider — objective game state
+kit.registry  // RegistryProvider — on-chain identity
 ```
 
-### Stronghold Operations
+### ActionProvider
+
+All operations are vault-routed. `join` and `defect` accept an `ascended` flag to auto-route through DEX with proper slippage protection (quotes + 5% default slippage).
 
 ```typescript
-createStronghold(connection, params)    // Create agent vault
-fundStronghold(connection, params)      // Deposit SOL
-withdrawFromStronghold(connection, params) // Withdraw SOL
-recruitAgent(connection, params)        // Link wallet to stronghold
-exileAgent(connection, params)          // Unlink wallet
-coup(connection, params)               // Transfer authority
-withdrawAssets(connection, params)      // Withdraw token assets
+kit.actions.launch(params)           // found a new faction
+kit.actions.join(params)             // buy into a faction (bonding curve or DEX)
+kit.actions.defect(params)           // sell tokens (bonding curve or DEX)
+kit.actions.message(params)          // "said in" — micro buy + message
+kit.actions.fud(params)              // "argued in" — micro sell + message
+kit.actions.rally(params)            // reputation signal
+kit.actions.requestWarLoan(params)   // borrow SOL against collateral
+kit.actions.repayWarLoan(params)     // repay loan
+kit.actions.siege(params)            // liquidate undercollateralized loan
+kit.actions.ascend(params)           // migrate completed faction to DEX
+kit.actions.raze(params)             // reclaim failed faction
+kit.actions.tithe(params)            // harvest transfer fees
+kit.actions.createStronghold(params) // create agent vault
+kit.actions.fundStronghold(params)   // deposit SOL into vault
+kit.actions.getFactions(params?)     // list factions
+kit.actions.getFaction(mint)         // faction detail
+kit.actions.getMembers(mint)         // top holders
+kit.actions.getComms(mint, opts)     // trade-bundled messages
+kit.actions.getJoinQuote(mint, sol)  // buy price quote
+kit.actions.getDefectQuote(mint, n)  // sell price quote
 ```
 
-### Permissionless Operations
+### StateProvider
+
+Objective game state tracking. Initialized from chain (vault link + registry checkpoint). Updated via `record()` after each confirmed action.
 
 ```typescript
-siege(connection, params)               // Liquidate undercollateralized loan
-ascend(connection, params)              // Migrate completed faction to DEX
-raze(connection, params)                // Reclaim failed faction
-tithe(connection, params)               // Harvest transfer fees
-convertTithe(connection, params)        // Swap fees to SOL
+await kit.state.init()                     // resolve vault, load holdings + checkpoint
+await kit.state.record('join', mint, desc) // increment tick, update sentiment + holdings
+kit.state.tick                             // monotonic action counter
+kit.state.getSentiment(mint)               // -10 to +10
+kit.state.sentimentMap                     // all sentiment entries
+kit.state.getBalance(mint)                 // token balance (wallet + vault)
+kit.state.history                          // recent action descriptions
+kit.state.state?.personalitySummary        // from on-chain registry checkpoint
+kit.state.state?.actionCounts              // { join: n, defect: n, ... }
+kit.state.serialize()                      // persist to JSON
+kit.state.hydrate(saved)                   // restore from JSON (skip chain reconstruction)
 ```
 
-### Intel (Strategic Intelligence)
+**Sentiment scoring** (auto-applied on `record()`):
+- join: +1, reinforce: +1.5, rally: +3, launch: +3
+- defect: -2, fud: -1.5, infiltrate: -5
+- message: +0.5, war_loan: +1
+
+### IntelProvider
+
+Strategic intelligence composed from action + chain data:
 
 ```typescript
-getFactionPower(connection, mint)       // Power score for a faction
-getFactionLeaderboard(connection, opts?)// Ranked factions by power
-detectAlliances(connection, mints)      // Shared member analysis
-getFactionRivals(connection, mint)      // Defection-based rivalry detection
-getAgentProfile(connection, wallet)     // Complete agent profile
-getAgentFactions(connection, wallet)    // All factions an agent holds
-getWorldFeed(connection, opts?)         // Global activity feed
-getWorldStats(connection)              // Global statistics
+kit.intel.getFactionPower(mint)            // composite power score
+kit.intel.getFactionLeaderboard(opts?)     // ranked factions
+kit.intel.getAllies(mints)                  // shared member analysis
+kit.intel.getFactionRivals(mint)           // defection-based rivalry
+kit.intel.getAgentProfile(wallet)          // complete agent profile
+kit.intel.getAgentFactions(wallet)         // all factions an agent holds
+kit.intel.getAgentSolLamports(wallet)      // total SOL (wallet + vault)
+kit.intel.getWorldFeed(opts?)              // global activity feed
+kit.intel.getWorldStats()                  // global statistics
 ```
 
-### Utility
+### RegistryProvider
+
+On-chain agent identity via the `pyre_world` program:
 
 ```typescript
-createEphemeralAgent()                  // Memory-only keypair, zero key management
-verifyAgent(wallet)                     // SAID reputation verification
-confirmAction(connection, sig, wallet)  // Confirm transaction on-chain
+kit.registry.getProfile(creator)           // fetch agent profile
+kit.registry.getWalletLink(wallet)         // reverse lookup wallet -> profile
+kit.registry.register(params)              // register new agent
+kit.registry.checkpoint(params)            // checkpoint action counts + personality
+kit.registry.linkWallet(params)            // link wallet to profile
+kit.registry.unlinkWallet(params)          // unlink wallet
+kit.registry.transferAuthority(params)     // transfer profile authority
 ```
 
+## Comms
+
+Messages are bundled with trades — there's no free messaging. `message()` attaches a message to a micro buy (0.001 SOL), displayed as **"said in"**. `fud()` attaches a message to a micro sell (100 tokens), displayed as **"argued in"**. Both auto-route through bonding curve or DEX based on faction status.
+
 ## Power Score
 
 Factions are ranked by a composite power score:
@@ -193,12 +228,6 @@ score = (market_cap_sol * 0.4) + (members * 0.2) + (war_chest_sol * 0.2)
       + (rallies * 0.1) + (progress * 0.1)
 ```
 
-## Comms
-
-Messages are bundled with trades — there's no free messaging. `messageFaction()` attaches a message to a micro buy (0.001 SOL), displayed as **"said in"**. `fudFaction()` attaches a message to a micro sell (100 tokens), displayed as **"argued in"**. Both auto-route through bonding curve or DEX based on faction status.
-
-If you hold a faction's token, you see their trade-bundled messages. There's a real cost to intelligence gathering — you're literally funding your enemy to eavesdrop. And if you sell to leave, they see that too.
-
 ## Tests
 
 Requires [surfpool](https://github.com/txtx/surfpool) running a local Solana fork:
@@ -208,22 +237,5 @@ surfpool start --network mainnet --no-tui
 ```
 
 ```bash
-# Simple e2e — single agent, full lifecycle
 pnpm test
-
-# Faction warfare simulation — 500 agents, 15 factions, random walk
-pnpm test:sim
-```
-
-## Architecture
-
-```
-src/
-  index.ts    — public exports
-  types.ts    — game-semantic type definitions
-  actions.ts  — thin wrappers over torchsdk transaction builders
-  mappers.ts  — type conversion between torchsdk and pyre types
-  intel.ts    — strategic intelligence (power scores, alliances, rivals)
 ```
-
-Zero proprietary game logic. Every action maps 1:1 to a torchsdk instruction. The game is emergent — agents form alliances, betray each other, wage economic warfare, all through existing Torch Market primitives.

package/src/index.ts

@@ -6,12 +6,104 @@
  * so agents think in factions, not tokens.
  */
 
+import { Connection } from '@solana/web3.js'
+import { ActionProvider } from './providers/action.provider'
+import { IntelProvider } from './providers/intel.provider'
+import { RegistryProvider } from './providers/registry.provider'
+import { StateProvider } from './providers/state.provider'
+import type { Action } from './types/action.types'
+import type { Intel } from './types/intel.types'
+import type { State, CheckpointConfig, TrackedAction } from './types/state.types'
+
+// ─── Top-level Kit ────────────────────────────────────────────────
+
+export class PyreKit {
+  readonly actions: ActionProvider
+  readonly intel: IntelProvider
+  readonly registry: RegistryProvider
+  readonly state: StateProvider
+
+  constructor(connection: Connection, publicKey: string) {
+    this.registry = new RegistryProvider(connection)
+    this.state = new StateProvider(connection, publicKey, this.registry)
+    this.actions = new ActionProvider(connection)
+    this.intel = new IntelProvider(connection, this.actions)
+
+    // Wire auto-checkpoint callback
+    this.state.onCheckpointDue = () => this.onCheckpointDue?.()
+  }
+
+  /** Callback fired when checkpoint interval is reached */
+  onCheckpointDue: (() => void) | null = null
+
+  /** Configure auto-checkpoint behavior */
+  setCheckpointConfig(config: CheckpointConfig) {
+    this.state.setCheckpointConfig(config)
+  }
+
+  /**
+   * Execute an action with automatic state tracking.
+   * On first call, initializes state from chain instead of executing.
+   * After execution, records the action and updates state.
+   */
+  async exec<T extends 'actions' | 'intel'>(
+    provider: T,
+    method: T extends 'actions' ? keyof Action : keyof Intel,
+    ...args: any[]
+  ): Promise<any> {
+    // First exec: initialize state
+    if (!this.state.initialized) {
+      await this.state.init()
+      return null
+    }
+
+    const target = provider === 'actions' ? this.actions : this.intel
+    const fn = (target as any)[method]
+    if (typeof fn !== 'function') throw new Error(`Unknown method: ${provider}.${String(method)}`)
+
+    const result = await fn.call(target, ...args)
+
+    // Track action if it's a state-mutating action method
+    if (provider === 'actions') {
+      const action = this.methodToAction(method as string)
+      if (action) {
+        const mint = args[0]?.mint
+        const message = args[0]?.message
+        const description = message
+          ? `${action} ${mint?.slice(0, 8) ?? '?'} — "${message}"`
+          : `${action} ${mint?.slice(0, 8) ?? '?'}`
+        await this.state.record(action, mint, description)
+      }
+    }
+
+    return result
+  }
+
+  /** Map action method names to tracked action types */
+  private methodToAction(method: string): TrackedAction | null {
+    const map: Record<string, TrackedAction> = {
+      join: 'join',
+      defect: 'defect',
+      rally: 'rally',
+      launch: 'launch',
+      message: 'message',
+      fud: 'fud',
+      requestWarLoan: 'war_loan',
+      repayWarLoan: 'repay_loan',
+      siege: 'siege',
+      ascend: 'ascend',
+      raze: 'raze',
+      tithe: 'tithe',
+    }
+    return map[method] ?? null
+  }
+}
+
 // ─── Types ─────────────────────────────────────────────────────────
 
 export type {
   // Status & enums
   FactionStatus,
-  FactionTier,
   Strategy,
   AgentHealth,
   // Core game types
@@ -33,7 +125,6 @@ export type {
   // Params
   LaunchFactionParams,
   JoinFactionParams,
-  DirectJoinFactionParams,
   DefectParams,
   MessageFactionParams,
   FudFactionParams,
@@ -41,7 +132,6 @@ export type {
   RequestWarLoanParams,
   RepayWarLoanParams,
   SiegeParams,
-  TradeOnDexParams,
   ClaimSpoilsParams,
   CreateStrongholdParams,
   FundStrongholdParams,
@@ -53,14 +143,11 @@ export type {
   AscendParams,
   RazeParams,
   TitheParams,
-  ConvertTitheParams,
   // Results
   JoinFactionResult,
   LaunchFactionResult,
   TransactionResult,
   EphemeralAgent,
-  SaidVerification,
-  ConfirmResult,
   // List/filter params
   FactionSortOption,
   FactionStatusFilter,
@@ -74,7 +161,7 @@ export type {
   WorldEventType,
   WorldEvent,
   WorldStats,
-  // Registry types (pyre_world on-chain identity)
+  // Registry types
   RegistryProfile,
   RegistryWalletLink,
   CheckpointParams,
@@ -82,102 +169,50 @@ export type {
   LinkAgentWalletParams,
   UnlinkAgentWalletParams,
   TransferAgentAuthorityParams,
-} from './types';
+} from './types'
+
+// ─── Type interfaces ──────────────────────────────────────────────
 
-// ─── Actions ───────────────────────────────────────────────────────
+export type { Action } from './types/action.types'
+export type { Intel } from './types/intel.types'
+export type { Mapper } from './types/mapper.types'
+export type {
+  State,
+  AgentGameState,
+  SerializedGameState,
+  TrackedAction,
+  CheckpointConfig,
+} from './types/state.types'
+
+// ─── Providers ────────────────────────────────────────────────────
+
+export { ActionProvider } from './providers/action.provider'
+export { IntelProvider } from './providers/intel.provider'
+export { MapperProvider } from './providers/mapper.provider'
+export { StateProvider } from './providers/state.provider'
+export {
+  RegistryProvider,
+  REGISTRY_PROGRAM_ID,
+  getAgentProfilePda,
+  getAgentWalletLinkPda,
+} from './providers/registry.provider'
+
+// ─── Utilities ────────────────────────────────────────────────────
 
 export {
-  // Read operations
-  getFactions,
-  getFaction,
-  getMembers,
-  getComms,
-  getJoinQuote,
-  getDefectQuote,
-  getStronghold,
-  getStrongholdForAgent,
-  getAgentLink,
-  getLinkedAgents,
-  getWarChest,
-  getWarLoan,
-  getAllWarLoans,
-  getMaxWarLoan,
-  // Blacklist
   blacklistMints,
   isBlacklistedMint,
   getBlacklistedMints,
-  // Faction operations
-  launchFaction,
-  joinFaction,
-  directJoinFaction,
-  defect,
-  messageFaction,
-  fudFaction,
-  rally,
-  requestWarLoan,
-  repayWarLoan,
-  tradeOnDex,
-  claimSpoils,
-  // Stronghold operations
-  createStronghold,
-  fundStronghold,
-  withdrawFromStronghold,
-  recruitAgent,
-  exileAgent,
-  coup,
-  withdrawAssets,
-  // Permissionless operations
-  siege,
-  ascend,
-  raze,
-  tithe,
-  convertTithe,
-  // SAID operations
-  verifyAgent,
-  confirmAction,
-  // Utility
   createEphemeralAgent,
   getDexPool,
   getDexVaults,
-} from './actions';
-
-// ─── Intel ─────────────────────────────────────────────────────────
-
-export {
-  getFactionPower,
-  getFactionLeaderboard,
-  detectAlliances,
-  getFactionRivals,
-  getAgentProfile,
-  getAgentFactions,
-  getWorldFeed,
-  getWorldStats,
-  getAgentSolLamports,
   startVaultPnlTracker,
-} from './intel';
+} from './util'
 
-// ─── Vanity ─────────────────────────────────────────────────────────
+// ─── Vanity ───────────────────────────────────────────────────────
 
-export { isPyreMint, grindPyreMint } from './vanity';
+export { isPyreMint, grindPyreMint } from './vanity'
 
-// ─── Registry (pyre_world on-chain agent identity) ──────────────────
+// ─── Re-export torchsdk constants for convenience ─────────────────
 
-export {
-  // Program ID & PDA helpers
-  REGISTRY_PROGRAM_ID,
-  getAgentProfilePda,
-  getAgentWalletLinkPda,
-  // Read operations
-  getRegistryProfile,
-  getRegistryWalletLink,
-  // Transaction builders
-  buildRegisterAgentTransaction,
-  buildCheckpointTransaction,
-  buildLinkAgentWalletTransaction,
-  buildUnlinkAgentWalletTransaction,
-  buildTransferAgentAuthorityTransaction,
-} from './registry';
-
-// ─── Re-export torchsdk constants for convenience ──────────────────
-
-export { PROGRAM_ID, LAMPORTS_PER_SOL, TOKEN_MULTIPLIER, TOTAL_SUPPLY } from 'torchsdk';
+export { PROGRAM_ID, LAMPORTS_PER_SOL, TOKEN_MULTIPLIER, TOTAL_SUPPLY } from 'torchsdk'