pyre-world-kit 3.1.2 → 3.2.1

package/src/providers/state.provider.ts

@@ -2,6 +2,7 @@ import { Connection, PublicKey } from '@solana/web3.js'
 
 import { isPyreMint } from '../vanity'
 import { isBlacklistedMint } from '../util'
+import type { Stronghold } from '../types'
 import type {
   State,
   AgentGameState,
@@ -11,6 +12,10 @@ import type {
 } from '../types/state.types'
 import { Registry } from '../types/registry.types'
 
+// Pre-warm imports — resolved once, cached as module-level promises
+const splTokenImport = import('@solana/spl-token')
+const torchsdkImport = import('torchsdk')
+
 const EMPTY_COUNTS: Record<TrackedAction, number> = {
   join: 0,
   defect: 0,
@@ -33,6 +38,11 @@ export class StateProvider implements State {
   private checkpointConfig: CheckpointConfig | null = null
   private ticksSinceCheckpoint = 0
 
+  // Lazy vault — undefined = not resolved, null = resolved to nothing
+  private _vaultCreator: string | null | undefined = undefined
+  private _stronghold: Stronghold | null | undefined = undefined
+  private _vaultPromise: Promise<void> | null = null
+
   constructor(
     private connection: Connection,
     private registry: Registry,
@@ -42,9 +52,6 @@ export class StateProvider implements State {
   get state() {
     return this._state
   }
-  get vaultCreator() {
-    return this._state?.vaultCreator ?? null
-  }
   get initialized() {
     return this._state?.initialized ?? false
   }
@@ -52,86 +59,113 @@ export class StateProvider implements State {
     return this._state?.tick ?? 0
   }
 
-  /** Configure auto-checkpoint behavior */
   setCheckpointConfig(config: CheckpointConfig) {
     this.checkpointConfig = config
   }
 
-  async init(): Promise<AgentGameState> {
-    if (this._state?.initialized) return this._state
-
-    const state: AgentGameState = {
-      publicKey: this.publicKey,
-      vaultCreator: null,
-      stronghold: null,
-      tick: 0,
-      actionCounts: { ...EMPTY_COUNTS },
-      holdings: new Map(),
-      activeLoans: new Set(),
-      founded: [],
-      rallied: new Set(),
-      voted: new Set(),
-      sentiment: new Map(),
-      recentHistory: [],
-      personalitySummary: null,
-      totalSolSpent: 0,
-      totalSolReceived: 0,
-      initialized: false,
+  private async resolveVault(): Promise<void> {
+    if (this._vaultCreator !== undefined) return
+    if (!this._vaultPromise) {
+      this._vaultPromise = (async () => {
+        const { getVaultForWallet } = await torchsdkImport
+        try {
+          const vault = await getVaultForWallet(this.connection, this.publicKey)
+          if (vault) {
+            this._vaultCreator = vault.creator
+            this._stronghold = {
+              address: vault.address,
+              creator: vault.creator,
+              authority: vault.authority,
+              sol_balance: vault.sol_balance,
+              total_deposited: vault.total_deposited,
+              total_withdrawn: vault.total_withdrawn,
+              total_spent: vault.total_spent,
+              total_received: vault.total_received,
+              linked_agents: vault.linked_wallets,
+              created_at: vault.created_at,
+            }
+          } else {
+            this._vaultCreator = null
+            this._stronghold = null
+          }
+        } catch {
+          this._vaultCreator = null
+          this._stronghold = null
+        }
+        this._vaultPromise = null
+      })()
     }
+    return this._vaultPromise
+  }
 
-    this._state = state
+  async getVaultCreator(): Promise<string | null> {
+    await this.resolveVault()
+    return this._vaultCreator ?? null
+  }
 
-    // resolve vault link
-    const { getVaultForWallet } = await import('torchsdk')
-    try {
-      const vault = await getVaultForWallet(this.connection, this.publicKey)
-      if (vault) {
-        state.vaultCreator = vault.creator
-        state.stronghold = {
-          address: vault.address,
-          creator: vault.creator,
-          authority: vault.authority,
-          sol_balance: vault.sol_balance,
-          total_deposited: vault.total_deposited,
-          total_withdrawn: vault.total_withdrawn,
-          total_spent: vault.total_spent,
-          total_received: vault.total_received,
-          linked_agents: vault.linked_wallets,
-          created_at: vault.created_at,
-        }
-      }
-    } catch {}
+  async getStronghold(): Promise<Stronghold | null> {
+    await this.resolveVault()
+    return this._stronghold ?? null
+  }
 
-    try {
-      const profile = await this.registry.getProfile(this.publicKey)
-      if (profile) {
-        state.personalitySummary = profile.personality_summary || null
-        state.totalSolSpent = profile.total_sol_spent
-        state.totalSolReceived = profile.total_sol_received
-
-        state.actionCounts.join = Math.max(state.actionCounts.join, profile.joins)
-        state.actionCounts.defect = Math.max(state.actionCounts.defect, profile.defects)
-        state.actionCounts.rally = Math.max(state.actionCounts.rally, profile.rallies)
-        state.actionCounts.launch = Math.max(state.actionCounts.launch, profile.launches)
-        state.actionCounts.message = Math.max(state.actionCounts.message, profile.messages)
-        state.actionCounts.reinforce = Math.max(state.actionCounts.reinforce, profile.reinforces)
-        state.actionCounts.fud = Math.max(state.actionCounts.fud, profile.fuds)
-        state.actionCounts.infiltrate = Math.max(state.actionCounts.infiltrate, profile.infiltrates)
-        state.actionCounts.war_loan = Math.max(state.actionCounts.war_loan, profile.war_loans)
-        state.actionCounts.repay_loan = Math.max(state.actionCounts.repay_loan, profile.repay_loans)
-        state.actionCounts.siege = Math.max(state.actionCounts.siege, profile.sieges)
-        state.actionCounts.ascend = Math.max(state.actionCounts.ascend, profile.ascends)
-        state.actionCounts.raze = Math.max(state.actionCounts.raze, profile.razes)
-        state.actionCounts.tithe = Math.max(state.actionCounts.tithe, profile.tithes)
-
-        const totalFromCheckpoint = Object.values(state.actionCounts).reduce((a, b) => a + b, 0)
-        state.tick = totalFromCheckpoint
+  async init(): Promise<AgentGameState> {
+    if (!this._state?.initialized) {
+      const state: AgentGameState = {
+        publicKey: this.publicKey,
+        tick: 0,
+        actionCounts: { ...EMPTY_COUNTS },
+        activeLoans: new Set(),
+        founded: [],
+        rallied: new Set(),
+        voted: new Set(),
+        sentiment: new Map(),
+        recentHistory: [],
+        personalitySummary: null,
+        totalSolSpent: 0,
+        totalSolReceived: 0,
+        initialized: false,
       }
-    } catch {}
 
-    await this.refreshHoldings()
-    state.initialized = true
-    return state
+      // Fire vault resolution in background — don't block init
+      this.resolveVault()
+
+      try {
+        const profile = await this.registry.getProfile(this.publicKey)
+        if (profile) {
+          state.personalitySummary = profile.personality_summary || null
+          state.totalSolSpent = profile.total_sol_spent
+          state.totalSolReceived = profile.total_sol_received
+
+          state.actionCounts.join = Math.max(state.actionCounts.join, profile.joins)
+          state.actionCounts.defect = Math.max(state.actionCounts.defect, profile.defects)
+          state.actionCounts.rally = Math.max(state.actionCounts.rally, profile.rallies)
+          state.actionCounts.launch = Math.max(state.actionCounts.launch, profile.launches)
+          state.actionCounts.message = Math.max(state.actionCounts.message, profile.messages)
+          state.actionCounts.reinforce = Math.max(state.actionCounts.reinforce, profile.reinforces)
+          state.actionCounts.fud = Math.max(state.actionCounts.fud, profile.fuds)
+          state.actionCounts.infiltrate = Math.max(
+            state.actionCounts.infiltrate,
+            profile.infiltrates,
+          )
+          state.actionCounts.war_loan = Math.max(state.actionCounts.war_loan, profile.war_loans)
+          state.actionCounts.repay_loan = Math.max(
+            state.actionCounts.repay_loan,
+            profile.repay_loans,
+          )
+          state.actionCounts.siege = Math.max(state.actionCounts.siege, profile.sieges)
+          state.actionCounts.ascend = Math.max(state.actionCounts.ascend, profile.ascends)
+          state.actionCounts.raze = Math.max(state.actionCounts.raze, profile.razes)
+          state.actionCounts.tithe = Math.max(state.actionCounts.tithe, profile.tithes)
+
+          const totalFromCheckpoint = Object.values(state.actionCounts).reduce((a, b) => a + b, 0)
+          state.tick = totalFromCheckpoint
+        }
+      } catch {}
+
+      state.initialized = true
+      this._state = state
+    }
+    return this._state
   }
 
   async record(action: TrackedAction, mint?: string, description?: string): Promise<void> {
@@ -156,7 +190,11 @@ export class StateProvider implements State {
       }
     }
 
-    await this.refreshHoldings()
+    // Sync P&L from vault every 10 ticks
+    if (this._state.tick % 10 === 0) {
+      this.syncPnl()
+    }
+
     if (this.checkpointConfig && this.ticksSinceCheckpoint >= this.checkpointConfig.interval) {
       this.ticksSinceCheckpoint = 0
       this.onCheckpointDue?.()
@@ -167,15 +205,15 @@ export class StateProvider implements State {
     if (!this._state) return
     const current = this._state.sentiment.get(mint) ?? 0
     const SENTIMENT_DELTAS: Partial<Record<TrackedAction, number>> = {
-      join: 1,
-      reinforce: 1.5,
-      defect: -2,
-      rally: 3,
-      infiltrate: -5,
-      message: 0.5,
-      fud: -1.5,
-      war_loan: 1,
-      launch: 3,
+      join: 0.1,
+      reinforce: 0.15,
+      defect: -0.2,
+      rally: 0.3,
+      infiltrate: -0.5,
+      message: 0.05,
+      fud: -0.15,
+      war_loan: 0.1,
+      launch: 0.3,
     }
 
     const delta = SENTIMENT_DELTAS[action] ?? 0
@@ -186,44 +224,56 @@ export class StateProvider implements State {
 
   onCheckpointDue: (() => void) | null = null
 
-  async refreshHoldings(): Promise<void> {
+  /** Sync totalSolSpent/Received from on-chain vault data (fresh read) */
+  private async syncPnl(): Promise<void> {
     if (!this._state) return
-
-    const { TOKEN_2022_PROGRAM_ID } = await import('@solana/spl-token')
-    const walletPk = new PublicKey(this.publicKey)
-
-    let walletValues: any[] = []
     try {
-      const walletAccounts = await this.connection.getParsedTokenAccountsByOwner(walletPk, {
-        programId: TOKEN_2022_PROGRAM_ID,
-      })
-      walletValues = walletAccounts.value
+      const { getVaultForWallet } = await torchsdkImport
+      const vault = await getVaultForWallet(this.connection, this.publicKey)
+      if (vault) {
+        this._state.totalSolSpent = Math.round(vault.total_spent * 1e9)
+        this._state.totalSolReceived = Math.round(vault.total_received * 1e9)
+      }
     } catch {}
+  }
 
-    let vaultValues: any[] = []
-    if (this._state.stronghold) {
-      try {
-        const vaultPk = new PublicKey(this._state.stronghold.address)
-        const vaultAccounts = await this.connection.getParsedTokenAccountsByOwner(vaultPk, {
-          programId: TOKEN_2022_PROGRAM_ID,
-        })
-        vaultValues = vaultAccounts.value
-      } catch {}
-    }
+  async getHoldings(): Promise<Map<string, number>> {
+    const { TOKEN_2022_PROGRAM_ID } = await splTokenImport
+    const walletPk = new PublicKey(this.publicKey)
 
-    const newHoldings = new Map<string, number>()
+    // Parallel scan: wallet + vault
+    const stronghold = await this.getStronghold()
+    const scanWallet = this.connection
+      .getParsedTokenAccountsByOwner(walletPk, { programId: TOKEN_2022_PROGRAM_ID })
+      .then((r) => r.value)
+      .catch(() => [] as any[])
+
+    const scanVault = stronghold
+      ? this.connection
+          .getParsedTokenAccountsByOwner(new PublicKey(stronghold.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])
+
+    const holdings = new Map<string, number>()
     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)) {
-        newHoldings.set(mint, (newHoldings.get(mint) ?? 0) + balance)
+        holdings.set(mint, (holdings.get(mint) ?? 0) + balance)
       }
     }
 
-    this._state.holdings.clear()
-    for (const [mint, balance] of newHoldings) {
-      this._state.holdings.set(mint, balance)
-    }
+    return holdings
+  }
+
+  async getBalance(mint: string): Promise<number> {
+    const holdings = await this.getHoldings()
+    return holdings.get(mint) ?? 0
   }
 
   getSentiment(mint: string): number {
@@ -238,10 +288,6 @@ export class StateProvider implements State {
     return this._state?.recentHistory ?? []
   }
 
-  getBalance(mint: string): number {
-    return this._state?.holdings.get(mint) ?? 0
-  }
-
   hasVoted(mint: string): boolean {
     return this._state?.voted.has(mint) ?? false
   }
@@ -259,51 +305,50 @@ export class StateProvider implements State {
   }
 
   serialize(): SerializedGameState {
-    if (!this._state) {
-      return {
-        publicKey: this.publicKey,
-        vaultCreator: null,
-        tick: 0,
-        actionCounts: { ...EMPTY_COUNTS },
-        holdings: {},
-        activeLoans: [],
-        founded: [],
-        rallied: [],
-        voted: [],
-        sentiment: {},
-        recentHistory: [],
-        personalitySummary: null,
-        totalSolSpent: 0,
-        totalSolReceived: 0,
-      }
-    }
-
-    return {
-      publicKey: this._state.publicKey,
-      vaultCreator: this._state.vaultCreator,
-      tick: this._state.tick,
-      actionCounts: { ...this._state.actionCounts },
-      holdings: Object.fromEntries(this._state.holdings),
-      activeLoans: Array.from(this._state.activeLoans),
-      founded: [...this._state.founded],
-      rallied: Array.from(this._state.rallied),
-      voted: Array.from(this._state.voted),
-      sentiment: Object.fromEntries(this._state.sentiment),
-      recentHistory: this._state.recentHistory.slice(-20),
-      personalitySummary: this._state.personalitySummary,
-      totalSolSpent: this._state.totalSolSpent,
-      totalSolReceived: this._state.totalSolReceived,
-    }
+    return !this._state
+      ? {
+          publicKey: this.publicKey,
+          vaultCreator: null,
+          tick: 0,
+          actionCounts: { ...EMPTY_COUNTS },
+          holdings: {},
+          activeLoans: [],
+          founded: [],
+          rallied: [],
+          voted: [],
+          sentiment: {},
+          recentHistory: [],
+          personalitySummary: null,
+          totalSolSpent: 0,
+          totalSolReceived: 0,
+        }
+      : {
+          publicKey: this._state.publicKey,
+          vaultCreator: this._vaultCreator ?? null,
+          tick: this._state.tick,
+          actionCounts: { ...this._state.actionCounts },
+          holdings: {},
+          activeLoans: Array.from(this._state.activeLoans),
+          founded: [...this._state.founded],
+          rallied: Array.from(this._state.rallied),
+          voted: Array.from(this._state.voted),
+          sentiment: Object.fromEntries(this._state.sentiment),
+          recentHistory: this._state.recentHistory.slice(-20),
+          personalitySummary: this._state.personalitySummary,
+          totalSolSpent: this._state.totalSolSpent,
+          totalSolReceived: this._state.totalSolReceived,
+        }
   }
 
   hydrate(saved: SerializedGameState): void {
+    if (saved.vaultCreator) {
+      this._vaultCreator = saved.vaultCreator
+    }
+
     this._state = {
       publicKey: saved.publicKey,
-      vaultCreator: saved.vaultCreator,
-      stronghold: null, // will be resolved on next refreshHoldings or init
       tick: saved.tick,
       actionCounts: { ...EMPTY_COUNTS, ...saved.actionCounts },
-      holdings: new Map(Object.entries(saved.holdings)),
       activeLoans: new Set(saved.activeLoans),
       founded: [...saved.founded],
       rallied: new Set(saved.rallied),

package/src/types/intel.types.ts

@@ -2,21 +2,29 @@ import {
   AgentFactionPosition,
   AgentProfile,
   AllianceCluster,
+  FactionListResult,
   FactionPower,
   FactionStatus,
+  NearbyResult,
   RivalFaction,
   WorldEvent,
   WorldStats,
 } from '../types'
 
 export interface Intel {
-  getAgentFactions(wallet: string, factionLimit?: number): Promise<AgentFactionPosition[]>
+  getAgentFactions(wallet: string): Promise<AgentFactionPosition[]>
   getAgentProfile(wallet: string): Promise<AgentProfile>
   getAgentSolLamports(wallet: string): Promise<number>
   getAllies(mints: string[], holderLimit?: number): Promise<AllianceCluster[]>
+  getAscendedFactions(limit?: number): Promise<FactionListResult>
   getFactionPower(mint: string): Promise<FactionPower>
   getFactionLeaderboard(opts?: { status?: FactionStatus; limit?: number }): Promise<FactionPower[]>
   getFactionRivals(mint: string, opts?: { limit?: number }): Promise<RivalFaction[]>
+  getNearbyFactions(
+    wallet: string,
+    opts?: { depth?: number; limit?: number },
+  ): Promise<NearbyResult>
+  getRisingFactions(limit?: number): Promise<FactionListResult>
   getWorldFeed(opts?: { limit?: number; factionLimit?: number }): Promise<WorldEvent[]>
   getWorldStats(): Promise<WorldStats>
 }

package/src/types/state.types.ts

@@ -21,16 +21,10 @@ export type TrackedAction =
 export interface AgentGameState {
   /** Agent wallet public key */
   publicKey: string
-  /** Vault creator key (resolved from on-chain vault link) */
-  vaultCreator: string | null
-  /** Vault info (null if no vault found) */
-  stronghold: Stronghold | null
   /** Monotonic tick counter — increments on each successful action */
   tick: number
   /** Cumulative action counts keyed by action type */
   actionCounts: Record<TrackedAction, number>
-  /** Token holdings: mint → balance (wallet + vault combined) */
-  holdings: Map<string, number>
   /** Mints with active war loans */
   activeLoans: Set<string>
   /** Mints this agent founded */
@@ -86,9 +80,6 @@ export interface State {
   /** Current game state (null before init) */
   readonly state: AgentGameState | null
 
-  /** Vault creator key (shorthand for state.vaultCreator) */
-  readonly vaultCreator: string | null
-
   /** Whether state has been initialized */
   readonly initialized: boolean
 
@@ -97,20 +88,28 @@ export interface State {
 
   /**
    * Initialize state from chain.
-   * Resolves vault link, loads holdings, loads action counts from registry checkpoint.
-   * Must be called before any action. Returns the resolved state.
+   * Loads action counts from registry checkpoint.
+   * Vault and holdings are resolved lazily on first access.
    */
   init(): Promise<AgentGameState>
 
   /**
    * Record a successful action — increments tick, updates action counts,
-   * updates sentiment, appends to history, refreshes holdings.
-   * Called by ActionProvider after tx confirmation.
+   * updates sentiment, appends to history.
    */
   record(action: TrackedAction, mint?: string, description?: string): Promise<void>
 
-  /** Refresh holdings from on-chain (wallet + vault token accounts) */
-  refreshHoldings(): Promise<void>
+  /** Get vault creator key (lazy — resolves on first call, cached after) */
+  getVaultCreator(): Promise<string | null>
+
+  /** Get stronghold info (lazy — resolves on first call, cached after) */
+  getStronghold(): Promise<Stronghold | null>
+
+  /** Get token holdings fresh from chain (wallet + vault) */
+  getHoldings(): Promise<Map<string, number>>
+
+  /** Get token balance for a specific mint (fresh from chain) */
+  getBalance(mint: string): Promise<number>
 
   /** Get sentiment score for a faction (-10 to +10) */
   getSentiment(mint: string): number
@@ -121,9 +120,6 @@ export interface State {
   /** Get recent action history (for LLM memory block) */
   readonly history: readonly string[]
 
-  /** Get token balance for a specific mint */
-  getBalance(mint: string): number
-
   /** Check if agent has voted on a faction */
   hasVoted(mint: string): boolean
 

package/src/types.ts

@@ -402,6 +402,12 @@ export interface FactionPower {
   status: FactionStatus
 }
 
+/** Result from getNearbyFactions — factions + discovered agents in the social graph */
+export interface NearbyResult extends FactionListResult {
+  /** Wallet addresses discovered as co-holders (natural allies) */
+  allies: string[]
+}
+
 export interface AllianceCluster {
   factions: string[]
   shared_members: number

package/src/vanity.ts

@@ -42,23 +42,25 @@ export const getBondingCurvePda = (mint: PublicKey): [PublicKey, number] =>
 export const getTokenTreasuryPda = (mint: PublicKey): [PublicKey, number] =>
   PublicKey.findProgramAddressSync([Buffer.from(TREASURY_SEED), mint.toBuffer()], PROGRAM_ID)
 
-const getTreasuryTokenAccount = (mint: PublicKey, treasury: PublicKey): PublicKey =>
+const getTreasuryTokenAccount = (mint: PublicKey, treasury: PublicKey) =>
   getAssociatedTokenAddressSync(mint, treasury, true, TOKEN_2022_PROGRAM_ID)
 
 export const getTreasuryLockPda = (mint: PublicKey): [PublicKey, number] =>
   PublicKey.findProgramAddressSync([Buffer.from(TREASURY_LOCK_SEED), mint.toBuffer()], PROGRAM_ID)
 
-const getTreasuryLockTokenAccount = (mint: PublicKey, treasuryLock: PublicKey): PublicKey =>
+const getTreasuryLockTokenAccount = (mint: PublicKey, treasuryLock: PublicKey) =>
   getAssociatedTokenAddressSync(mint, treasuryLock, true, TOKEN_2022_PROGRAM_ID)
 
-const 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) =>
+  new AnchorProvider(
+    connection,
+    {
+      publicKey: payer,
+      signTransaction: async (t: Transaction) => t,
+      signAllTransactions: async (t: Transaction[]) => t,
+    } as unknown as Wallet,
+    {},
+  )
 
 const finalizeTransaction = async (
   connection: Connection,
@@ -72,9 +74,9 @@ const finalizeTransaction = async (
 
 // ── Vanity grinder ──
 
-const PYRE_SUFFIX = 'py'
+const PYRE_SUFFIX = 'pw'
 
-/** Grind for a keypair whose base58 address ends with "py" */
+/** Grind for a keypair whose base58 address ends with "pw" (pyreworld) */
 export const grindPyreMint = (maxAttempts: number = 500_000): Keypair => {
   for (let i = 0; i < maxAttempts; i++) {
     const kp = Keypair.generate()
@@ -86,7 +88,7 @@ export const grindPyreMint = (maxAttempts: number = 500_000): Keypair => {
   return Keypair.generate()
 }
 
-/** Check if a mint address is a pyre faction (ends with "py") */
+/** Check if a mint address is a pyre faction (ends with "pw") */
 export const isPyreMint = (mint: string): boolean => mint.endsWith(PYRE_SUFFIX)
 
 // ── Build create transaction with pyre vanity address ──