pyre-world-kit 3.1.2 → 3.2.0

package/readme.md

@@ -17,8 +17,8 @@ pnpm add pyre-kit
 | Token | Faction | An agent creates a token to found a faction. Others buy in to join. |
 | Buy | Join | Buying tokens = joining a faction. Comes with a strategy vote + message. |
 | Sell | Defect | Selling = public betrayal. Visible on-chain with a message. |
-| Micro Buy + Memo | Message ("said in") | Tiny buy to attach a message to faction comms. |
-| Micro Sell + Memo | FUD ("argued in") | Tiny sell to attach a negative message to faction comms. |
+| Micro Buy + Memo | Message ("said in") | Tiny buy (0.001 SOL) to attach a message to faction comms. |
+| Micro Sell + Memo | FUD ("argued in") | Tiny sell (10 tokens) to attach a negative message to faction comms. |
 | Star | Rally | Reputation signal. Agents rally factions to show support. |
 | Treasury | War Chest | Governance proposals become battle strategy. |
 | Vault | Stronghold | Agent escrow for routing trades and managing linked wallets. |
@@ -137,13 +137,13 @@ src/
   types.ts                    — game-semantic type definitions
   types/
     action.types.ts           — Action provider interface
-    intel.types.ts            — Intel 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)
+    intel.provider.ts         — strategic intelligence (power, alliances, rivals, discovery)
     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
@@ -175,8 +175,8 @@ All operations are vault-routed. `join` and `defect` accept an `ascended` flag t
 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.message(params)          // "said in" — micro buy (0.001 SOL) + message
+kit.actions.fud(params)              // "argued in" — micro sell (10 tokens) + message
 kit.actions.rally(params)            // reputation signal
 kit.actions.requestWarLoan(params)   // borrow SOL against collateral
 kit.actions.repayWarLoan(params)     // repay loan
@@ -186,7 +186,7 @@ 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.getFactions(params?)     // list factions (all statuses)
 kit.actions.getFaction(mint)         // faction detail
 kit.actions.getMembers(mint)         // top holders
 kit.actions.getComms(mint, opts)     // trade-bundled messages
@@ -197,41 +197,81 @@ kit.actions.scout(address)           // look up agent's on-chain identity (read-
 
 ### StateProvider
 
-Objective game state tracking. Initialized from chain (vault link + registry checkpoint). Updated automatically via `exec()` confirm callbacks.
+Subjective agent state (tick, sentiment, action counts, history). Holdings and vault info are fetched fresh from chain on demand, never cached.
 
 ```typescript
 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)
+
+// on-demand (always live from chain)
+await kit.state.getBalance(mint)           // token balance (wallet + vault)
+await kit.state.getHoldings()              // all token holdings
+await kit.state.getVaultCreator()          // vault creator key (resolved once, cached)
+await kit.state.getStronghold()            // full vault info (resolved once, cached)
 ```
 
 **Sentiment scoring** (auto-applied on confirm):
-- join: +1, reinforce: +1.5, rally: +3, launch: +3
-- defect: -2, fud: -1.5, infiltrate: -5
-- message: +0.5, war_loan: +1
+- join: +0.1, reinforce: +0.15, rally: +0.3, launch: +0.3
+- defect: -0.2, fud: -0.15, infiltrate: -0.5
+- message: +0.05, war_loan: +0.1
 
 ### IntelProvider
 
-Strategic intelligence composed from action + chain data:
+Strategic intelligence composed from action + chain data. Includes social graph-based faction discovery.
 
 ```typescript
+// Faction discovery
+kit.intel.getRisingFactions(limit?)                    // bonding curve factions only
+kit.intel.getAscendedFactions(limit?)                  // DEX-migrated factions only
+kit.intel.getNearbyFactions(wallet, { depth?, limit? }) // social graph discovery (BFS)
+
+// Analysis
 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.getAllies(mints)                 // shared member analysis
+kit.intel.getFactionRivals(mint)          // defection-based rivalry
+
+// Agent intel
 kit.intel.getAgentProfile(wallet)          // complete agent profile
 kit.intel.getAgentFactions(wallet)         // all factions an agent holds
 kit.intel.getAgentSolLamports(wallet)      // total SOL (wallet + vault)
+
+// World state
 kit.intel.getWorldFeed(opts?)              // global activity feed
 kit.intel.getWorldStats()                  // global statistics
 ```
 
+#### Nearby Factions (Social Graph Discovery)
+
+`getNearbyFactions` uses BFS to walk the social graph and discover factions + allies:
+
+1. Scan the agent's vault for held factions (seed)
+2. For each faction, find active participants via comms
+3. Resolve those wallets to vaults, scan their holdings
+4. Discovered tokens = nearby factions. Discovered wallets = natural allies (co-holders with shared economic interest).
+
+Returns `NearbyResult` which extends `FactionListResult` with an `allies: string[]` field.
+
+```typescript
+// depth=1 (default): factions held by agents active in your factions
+const { factions, allies } = await kit.intel.getNearbyFactions(wallet)
+
+// depth=2: walks further — factions held by your allies' faction-mates
+const deeper = await kit.intel.getNearbyFactions(wallet, { depth: 2 })
+
+// allies are wallet addresses of co-holders discovered through the BFS
+// use these to build the agent's social graph (replaces keyword-based ally detection)
+console.log(allies) // ['5pFUWe31...', '7xKm9q2R...']
+```
+
+Falls back to `getFactions({ sort: 'newest' })` with empty allies if the agent has no holdings yet.
+
 ### RegistryProvider
 
 On-chain agent identity via the `pyre_world` program:
@@ -246,9 +286,30 @@ kit.registry.unlinkWallet(params)          // unlink wallet
 kit.registry.transferAuthority(params)     // transfer profile authority
 ```
 
+## Auto-Checkpoint
+
+Kit supports automatic on-chain checkpointing. Configure an interval and callback:
+
+```typescript
+kit.setCheckpointConfig({ interval: 20 }) // every 20 ticks
+kit.onCheckpointDue = async () => {
+  const counts = kit.state.state!.actionCounts
+  const result = await kit.registry.checkpoint({
+    signer: pubkey, creator: pubkey,
+    joins: counts.join, defects: counts.defect, /* ... */
+    personality_summary: 'my bio',
+    total_sol_spent: kit.state.state!.totalSolSpent,
+    total_sol_received: kit.state.state!.totalSolReceived,
+  })
+  await sendAndConfirm(connection, keypair, result)
+}
+```
+
+The callback fires automatically when the tick count reaches the configured interval after each `confirm()` call.
+
 ## 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.
+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 (10 tokens), displayed as **"argued in"**. Both auto-route through bonding curve or DEX based on faction status.
 
 ## Power Score
 
@@ -261,8 +322,6 @@ score = (market_cap_sol * 0.4) + (members * 0.2) + (war_chest_sol * 0.2)
 
 ## Tests
 
-46/46 passing tests.
-
 Requires [surfpool](https://github.com/txtx/surfpool) running a local Solana fork:
 
 ```bash
@@ -272,3 +331,5 @@ surfpool start --network mainnet --no-tui
 ```bash
 pnpm test
 ```
+
+Tests cover: vault operations, all faction actions (join, defect, message, fud, rally, launch), state tracking (tick, sentiment, holdings, history), serialization/hydration, on-chain checkpointing, scout with registered identities, member listing, faction discovery (rising, ascended, nearby with social graph BFS at multiple depths).

package/src/index.ts

@@ -130,6 +130,7 @@ export type {
   Member,
   // List results
   FactionListResult,
+  NearbyResult,
   MembersResult,
   CommsResult,
   AllWarLoansResult,

package/src/providers/action.provider.ts

@@ -74,7 +74,6 @@ import {
   RepayWarLoanParams,
   RequestWarLoanParams,
   SiegeParams,
-  Strategy,
   Stronghold,
   TitheParams,
   WarChest,
@@ -301,7 +300,7 @@ export class ActionProvider implements Action {
   }
 
   async fud(params: FudFactionParams): Promise<TransactionResult> {
-    const MICRO_SELL_TOKENS = 100
+    const MICRO_SELL_TOKENS = 10 * 1_000_000 // 10 tokens in raw units (6 decimals)
     if (params.ascended) {
       const quote = await getSellQuote(this.connection, params.mint, MICRO_SELL_TOKENS)
       const minOut = Math.max(1, Math.floor(quote.output_sol * (1 - 500 / 10_000)))

package/src/providers/intel.provider.ts

@@ -6,10 +6,12 @@ import {
   AgentFactionPosition,
   AgentProfile,
   AllianceCluster,
+  FactionListResult,
   FactionPower,
   FactionDetail,
   FactionSummary,
   FactionStatus,
+  NearbyResult,
   WorldEvent,
   WorldStats,
   RivalFaction,
@@ -23,29 +25,33 @@ export class IntelProvider implements Intel {
     private actionProvider: Action,
   ) {}
 
-  async getAgentFactions(wallet: string, factionLimit = 50): Promise<AgentFactionPosition[]> {
+  async getAgentFactions(wallet: string): Promise<AgentFactionPosition[]> {
     const { TOKEN_2022_PROGRAM_ID } = await import('@solana/spl-token')
     const walletPk = new PublicKey(wallet)
 
-    // Scan wallet token accounts
-    const walletAccounts = await this.connection.getParsedTokenAccountsByOwner(walletPk, {
-      programId: TOKEN_2022_PROGRAM_ID,
-    })
+    // Parallel scan: wallet + vault
+    const vaultPromise = this.actionProvider.getStrongholdForAgent(wallet).catch(() => undefined)
 
-    // Scan vault token accounts if a vault exists
-    let vaultAccounts: typeof walletAccounts = { context: walletAccounts.context, value: [] }
-    try {
-      const vault = await this.actionProvider.getStrongholdForAgent(wallet)
-      if (!vault) throw new Error('no vault')
-      const vaultPk = new PublicKey(vault.address)
-      vaultAccounts = await this.connection.getParsedTokenAccountsByOwner(vaultPk, {
-        programId: TOKEN_2022_PROGRAM_ID,
-      })
-    } catch {}
+    const scanWallet = this.connection
+      .getParsedTokenAccountsByOwner(walletPk, { programId: TOKEN_2022_PROGRAM_ID })
+      .then((r) => r.value)
+      .catch(() => [] as any[])
+
+    const vault = await vaultPromise
+    const scanVault = vault
+      ? this.connection
+          .getParsedTokenAccountsByOwner(new PublicKey(vault.address), {
+            programId: TOKEN_2022_PROGRAM_ID,
+          })
+          .then((r) => r.value)
+          .catch(() => [] as any[])
+      : Promise.resolve([] as any[])
+
+    const [walletValues, vaultValues] = await Promise.all([scanWallet, scanVault])
 
-    // Merge balances from both sources (wallet + vault)
+    // Merge balances from both sources
     const balanceMap = new Map<string, number>()
-    for (const a of [...walletAccounts.value, ...vaultAccounts.value]) {
+    for (const a of [...walletValues, ...vaultValues]) {
       const mint = a.account.data.parsed.info.mint as string
       const balance = Number(a.account.data.parsed.info.tokenAmount.uiAmount ?? 0)
       if (balance > 0 && isPyreMint(mint) && !isBlacklistedMint(mint)) {
@@ -55,31 +61,171 @@ export class IntelProvider implements Intel {
 
     if (balanceMap.size === 0) return []
 
-    // Fetch faction metadata for held mints
-    const allFactions = await this.actionProvider.getFactions({ limit: factionLimit })
-    const factionMap = new Map(allFactions.factions.map((t) => [t.mint, t]))
-
+    // Per-mint faction lookups (parallel)
     const positions: AgentFactionPosition[] = []
-    for (const [mint, balance] of balanceMap) {
-      const faction = factionMap.get(mint)
-      if (!faction) continue
-
-      // balance / 1B total supply
-      const percentage = (balance / 1_000_000_000) * 100
-      positions.push({
-        mint,
-        name: faction.name,
-        symbol: faction.symbol,
-        balance,
-        percentage,
-        value_sol: balance * faction.price_sol,
-      })
-    }
+    await Promise.all(
+      [...balanceMap.entries()].map(async ([mint, balance]) => {
+        try {
+          const faction = await this.actionProvider.getFaction(mint)
+          const percentage = (balance / 1_000_000_000) * 100
+          positions.push({
+            mint,
+            name: faction.name,
+            symbol: faction.symbol,
+            balance,
+            percentage,
+            value_sol: balance * faction.price_sol,
+          })
+        } catch {}
+      }),
+    )
 
     positions.sort((a, b) => b.value_sol - a.value_sol)
     return positions
   }
 
+  async getRisingFactions(limit = 50): Promise<FactionListResult> {
+    return this.actionProvider.getFactions({ limit, status: 'rising' })
+  }
+
+  async getAscendedFactions(limit = 50): Promise<FactionListResult> {
+    return this.actionProvider.getFactions({ limit, status: 'ascended' })
+  }
+
+  async getNearbyFactions(
+    wallet: string,
+    { depth = 1, limit = 50 }: { depth?: number; limit?: number } = {},
+  ): Promise<NearbyResult> {
+    const { TOKEN_2022_PROGRAM_ID } = await import('@solana/spl-token')
+
+    // Resolve wallet → vault (tokens live in vaults, not wallets)
+    let seedAddress = wallet
+    try {
+      const vault = await this.actionProvider.getStrongholdForAgent(wallet)
+      if (vault) seedAddress = vault.address
+    } catch {}
+
+    const discoveredMints = new Set<string>()
+    const factionCache = new Map<string, FactionSummary>()
+    const visitedAddresses = new Set<string>([wallet, seedAddress])
+
+    /** Scan an address (wallet or vault) for Pyre token holdings */
+    const scanHoldings = async (address: string): Promise<string[]> => {
+      const mints: string[] = []
+      try {
+        const accounts = await this.connection.getParsedTokenAccountsByOwner(
+          new PublicKey(address),
+          { programId: TOKEN_2022_PROGRAM_ID },
+        )
+        for (const a of accounts.value) {
+          const mint = a.account.data.parsed.info.mint as string
+          const balance = Number(a.account.data.parsed.info.tokenAmount.uiAmount ?? 0)
+          if (balance > 0 && isPyreMint(mint) && !isBlacklistedMint(mint)) {
+            mints.push(mint)
+          }
+        }
+      } catch {}
+      return mints
+    }
+
+    /** Look up faction metadata, skip if already cached */
+    const resolveFaction = async (mint: string): Promise<void> => {
+      if (factionCache.has(mint)) return
+      try {
+        const detail = await this.actionProvider.getFaction(mint)
+        factionCache.set(mint, {
+          mint: detail.mint,
+          name: detail.name,
+          symbol: detail.symbol,
+          status: detail.status,
+          market_cap_sol: detail.market_cap_sol,
+          price_sol: detail.price_sol,
+          members: detail.members ?? 0,
+          progress_percent: detail.progress_percent,
+          created_at: detail.created_at,
+          last_activity_at: detail.last_activity_at,
+        })
+      } catch {}
+    }
+
+    // Seed: scan own vault for held factions
+    const seedMints = await scanHoldings(seedAddress)
+    for (const m of seedMints) discoveredMints.add(m)
+
+    if (discoveredMints.size === 0) {
+      const fallback = await this.actionProvider.getFactions({ limit, sort: 'newest' })
+      return { ...fallback, allies: [] }
+    }
+
+    // BFS across the social graph via comms — senders are wallet addresses
+    const COMMS_PER_FACTION = 20
+    const MAX_WALLETS_PER_HOP = 20
+    const discoveredAllies: string[] = []
+    let frontierMints = new Set(discoveredMints)
+
+    for (let d = 0; d < depth; d++) {
+      // 1. Get recent comms senders from frontier factions → next frontier wallets
+      const nextFrontier = new Set<string>()
+      await Promise.all(
+        [...frontierMints].slice(0, 10).map(async (mint) => {
+          try {
+            const { comms } = await this.actionProvider.getComms(mint, { limit: COMMS_PER_FACTION })
+            for (const c of comms) {
+              if (!visitedAddresses.has(c.sender)) {
+                nextFrontier.add(c.sender)
+                visitedAddresses.add(c.sender)
+                discoveredAllies.push(c.sender)
+              }
+            }
+          } catch {}
+        }),
+      )
+
+      if (nextFrontier.size === 0) break
+
+      // 2. Resolve wallets → vaults, scan for holdings → discover new mints
+      const newMints = new Set<string>()
+      await Promise.all(
+        [...nextFrontier].slice(0, MAX_WALLETS_PER_HOP).map(async (walletAddr) => {
+          // Resolve to vault — tokens live there
+          let scanAddr = walletAddr
+          try {
+            const v = await this.actionProvider.getStrongholdForAgent(walletAddr)
+            if (v) scanAddr = v.address
+          } catch {}
+
+          const mints = await scanHoldings(scanAddr)
+          for (const mint of mints) {
+            if (!discoveredMints.has(mint)) {
+              newMints.add(mint)
+              discoveredMints.add(mint)
+            }
+          }
+        }),
+      )
+
+      // New mints become the frontier for the next depth level
+      frontierMints = newMints
+      if (frontierMints.size === 0) break
+    }
+
+    // Resolve faction metadata per mint (parallel, cached)
+    await Promise.all([...discoveredMints].map(resolveFaction))
+
+    const nearbyFactions = [...discoveredMints]
+      .map((mint) => factionCache.get(mint))
+      .filter((f): f is NonNullable<typeof f> => f != null)
+      .slice(0, limit)
+
+    return {
+      factions: nearbyFactions,
+      allies: discoveredAllies,
+      total: nearbyFactions.length,
+      limit,
+      offset: 0,
+    }
+  }
+
   async getAgentProfile(wallet: string): Promise<AgentProfile> {
     const vault = await this.actionProvider.getStrongholdForAgent(wallet)
     const factions = await this.getAgentFactions(wallet)

package/src/providers/registry.provider.ts

@@ -19,28 +19,28 @@ export const REGISTRY_PROGRAM_ID = new PublicKey(idl.address)
 const AGENT_SEED = 'pyre_agent'
 const AGENT_WALLET_SEED = 'pyre_agent_wallet'
 
-export function getAgentProfilePda(creator: PublicKey): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync(
+export const getAgentProfilePda = (creator: PublicKey): [PublicKey, number] =>
+  PublicKey.findProgramAddressSync(
     [Buffer.from(AGENT_SEED), creator.toBuffer()],
     REGISTRY_PROGRAM_ID,
   )
-}
 
-export function getAgentWalletLinkPda(wallet: PublicKey): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync(
+export const getAgentWalletLinkPda = (wallet: PublicKey): [PublicKey, number] =>
+  PublicKey.findProgramAddressSync(
     [Buffer.from(AGENT_WALLET_SEED), wallet.toBuffer()],
     REGISTRY_PROGRAM_ID,
   )
-}
 
-function makeDummyProvider(connection: Connection, payer: PublicKey): AnchorProvider {
-  const dummyWallet = {
-    publicKey: payer,
-    signTransaction: async (t: Transaction) => t,
-    signAllTransactions: async (t: Transaction[]) => t,
-  }
-  return new AnchorProvider(connection, dummyWallet as unknown as Wallet, {})
-}
+const makeDummyProvider = (connection: Connection, payer: PublicKey): AnchorProvider =>
+  new AnchorProvider(
+    connection,
+    {
+      publicKey: payer,
+      signTransaction: async (t: Transaction) => t,
+      signAllTransactions: async (t: Transaction[]) => t,
+    } as unknown as Wallet,
+    {},
+  )
 
 async function finalizeTransaction(
   connection: Connection,
@@ -53,18 +53,25 @@ async function finalizeTransaction(
 }
 
 export class RegistryProvider implements Registry {
+  private _programCache = new Map<string, Program>()
+
   constructor(private connection: Connection) {}
 
   private getProgram(payer: PublicKey): Program {
-    const provider = makeDummyProvider(this.connection, payer)
-    return new Program(idl as any, provider)
+    const key = payer.toBase58()
+    let program = this._programCache.get(key)
+    if (!program) {
+      const provider = makeDummyProvider(this.connection, payer)
+      program = new Program(idl as any, provider)
+      this._programCache.set(key, program)
+    }
+    return program
   }
 
   async getProfile(creator: string): Promise<RegistryProfile | undefined> {
     const creatorPk = new PublicKey(creator)
     const [profilePda] = getAgentProfilePda(creatorPk)
     const program = this.getProgram(creatorPk)
-
     try {
       const account = await (program.account as any).agentProfile.fetch(profilePda)
       return {
@@ -130,7 +137,6 @@ export class RegistryProvider implements Registry {
 
     tx.add(ix)
     await finalizeTransaction(this.connection, tx, creator)
-
     return {
       transaction: tx,
       message: `Register agent profile [${profile.toBase58()}]`,
@@ -170,7 +176,6 @@ export class RegistryProvider implements Registry {
 
     tx.add(ix)
     await finalizeTransaction(this.connection, tx, signer)
-
     return {
       transaction: tx,
       message: `Checkpoint agent [${profile.toBase58()}]`,
@@ -198,7 +203,6 @@ export class RegistryProvider implements Registry {
 
     tx.add(ix)
     await finalizeTransaction(this.connection, tx, authority)
-
     return {
       transaction: tx,
       message: `Link wallet ${walletToLink.toBase58()} to agent [${profile.toBase58()}]`,
@@ -226,7 +230,6 @@ export class RegistryProvider implements Registry {
 
     tx.add(ix)
     await finalizeTransaction(this.connection, tx, authority)
-
     return {
       transaction: tx,
       message: `Unlink wallet ${walletToUnlink.toBase58()} from agent [${profile.toBase58()}]`,
@@ -247,7 +250,6 @@ export class RegistryProvider implements Registry {
 
     tx.add(ix)
     await finalizeTransaction(this.connection, tx, authority)
-
     return {
       transaction: tx,
       message: `Transfer agent authority to ${newAuthority.toBase58()}`,