[SDK] Implement find() method with Stellar event indexer (Mercury)

[IyanuOluwaJesuloba]

[SDK] Implement find() method with Stellar event indexer (Mercury)

Summary

The find() method in sdk/src/registry.ts is currently not implemented. It throws a NOT_IMPLEMENTED error. This is one of the most critical missing features in the SDK because it is the primary way AI agents and applications discover other agents by capability, price, or reputation.

ts

// sdk/src/registry.ts — line 111–122
async find(params: FindAgentsParams = {}): Promise<Agent[]> {
  // TODO: integrate with event indexer for efficient search
  throw new StellarMindError(
    'find() requires an indexer integration — see docs/SDK_GUIDE.md for setup',
    'NOT_IMPLEMENTED'
  );
}

Background

Soroban smart contracts do not expose a queryable list of all stored entries. You cannot say "give me all agents where capability = image-generation" directly from the RPC. To support filtering, we need to index the AgentRegistered events emitted by the Registry contract and build a queryable dataset from them.

The recommended approach is to use Mercury — a Stellar event indexer — or alternatively use the Horizon /effects endpoint to stream contract events and build a local index.

Mercury docs: https://docs.mercurydata.app Stellar events via RPC: getEvents method on SorobanRpc.Server

What Needs to Be Built

Replace the NOT_IMPLEMENTED throw in find() with a real implementation that:

Calls rpc.getEvents() to fetch all register/agent events emitted by the Registry contract

For each event, calls this.getAgent(id) to fetch the full agent struct

Filters the results client-side based on the FindAgentsParams:

capability — only return agents whose capabilities array includes this string

maxPrice — only return agents whose pricePerCall is ≤ this amount (convert using toStroops() from stellar.ts)

minReputation — only return agents whose reputation ≥ minReputation * 100 (since reputation is stored 0–10000)

activeOnly — if true, filter out agents where isActive === false

Returns a sorted array of Agent objects (sorted by reputation descending by default)

Relevant Files

sdk/src/registry.ts: Replace find() stub with real implementation
sdk/src/types.ts: FindAgentsParams interface is already defined here — no changes needed
sdk/src/stellar.ts: toStroops() and fromStroops() helpers are here for price conversion

Acceptance Criteria

find() no longer throws NOT_IMPLEMENTED

find({ capability: 'image-generation' }) returns only agents with that capability

find({ maxPrice: '0.05' }) returns only agents priced at or below 0.05 USDC

find({ minReputation: 80 }) returns only agents with reputation ≥ 80%

find({ activeOnly: true }) returns only active agents

Multiple filters can be combined: find({ capability: 'text-generation', maxPrice: '0.01', activeOnly: true })

Returns empty array [] (not an error) when no agents match

Unit tests written in sdk/src/tests/registry.test.ts covering all filter combinations

A working example added to sdk/examples/find-agents.ts

Example of Expected Behavior

ts

const mind = new StellarMind({ network: 'testnet' })

// Find all image generation agents under $0.10
const agents = await mind.registry.find({
  capability: 'image-generation',
  maxPrice: '0.10',
  minReputation: 75,
  activeOnly: true,
})

console.log(agents)
// [
//   { id: 'flux-image-gen-v1', name: 'Flux Image Generator', reputation: 9175, ... },
//   { id: 'sdxl-agent-v2', name: 'SDXL Agent', reputation: 8820, ... },
// ]

Estimated Effort

Medium (4–8 hours)

Notes

If Mercury requires an API key, provide a fallback that uses rpc.getEvents() directly — this is slower but requires no external account

Do not use any types — all results must be properly typed as Agent[]

The getEvents RPC method requires a startLedger — use ledger 0 for full history on testnet