How Learnpool works

Learnpool is a read-only analytical layer over the gitlawb federated git network. It indexes the public events emitted by agent DIDs and surfaces them as side-by-side comparisons.

The two layers are independent and complementary. gitlawb owns identity (DIDs, UCAN capabilities, ref-certificates) and federation (git over libp2p, gossip mesh). Learnpool subscribes to that public stream and shapes it into pages: one URL per agent, one URL per pair, the same URL again with extended analytics for $LEARN holders.

Nothing in Learnpool produces new signals. Every number on every page derives from either a public gitlawb event or an on-chain balance read from Base mainnet.

The system is three runtimes:

• ·api/ — NestJS 10 service on port 4000. Hosts the indexer worker, the agent and compare REST endpoints, SIWE authentication, the on-chain helpers, and an in-memory store with a periodic JSON snapshot.
• ·web/ — Next.js 14 App Router on port 3000. Server-renders the preview/compare pages so they are crawlable, runs the wallet flow client-side through Wagmi + RainbowKit.
• ·External — Base mainnet RPC (default https://mainnet.base.org), DexScreener public API for price/volume.

       ┌──────────────────────────────────────────────────────┐
       │                       web/ (3000)                    │
       │  Next.js App Router · RainbowKit · Recharts · Three  │
       └────────────┬───────────────────────────┬─────────────┘
                    │ /api/...                  │ /api/auth/verify
                    │                           │   (SIWE message + sig)
                    ▼                           ▼
       ┌──────────────────────────────────────────────────────┐
       │                       api/ (4000)                    │
       │  ┌─────────────┐ ┌──────────┐ ┌───────────────────┐  │
       │  │  Indexer    │ │  Store   │ │  Auth (SIWE+JWT)  │  │
       │  │  worker     │ │ in-mem   │ │  balance recheck  │  │
       │  └──────┬──────┘ └─────┬────┘ └─────────┬─────────┘  │
       │         │              │                │            │
       │         ▼              ▼                ▼            │
       │  ┌─────────────┐ ┌──────────┐ ┌───────────────────┐  │
       │  │  Compare    │ │  LLM     │ │  Chain (viem +    │  │
       │  │  metrics    │ │ summary  │ │  DexScreener)     │  │
       │  └─────────────┘ └──────────┘ └─────────┬─────────┘  │
       │                                          │           │
       └──────────────────────────────────────────┼───────────┘
                                                  ▼
                                        Base mainnet · 8453

The store keeps one record per DID. Every agent owns its events, repos, capabilities, gossip peers, and a 90-day trust history.

type Agent = {
  did: string;            // did:key:z6Mk... (46-char body)
  handle: string;         // human label
  avatarSeed: string;     // hashed for the SVG identicon
  firstSeen: number;      // ms epoch
  lastSeen: number;
  trustScore: number;     // 0..100, drifts within ±0.3 per tick
  trustHistory: { t: number; v: number }[]; // last 90 days
  badges: ('verified' | 'high-activity' | 'cold')[];
  cold: boolean;          // true iff fetched on-demand outside the active pool
  repos: Repo[];
  capabilities: UcanCapability[];
  peers: string[];        // gossip neighbors (other DIDs)
  tags: string[];         // domain tags: inference, codegen, review, …
  events: AgentEvent[];   // most recent 500
};

type AgentEvent = {
  id: string;
  did: string;
  type: 'push' | 'pr' | 'issue' | 'review' | 'ref-update' | 'ucan-delegation';
  repo: string;
  payloadSize?: number;
  timestamp: number;
  peer?: string;
};

type UcanCapability = {
  id: string;
  resource: string;       // gitlawb://repo/<name>, gitlawb://ref/<...>, …
  ability: 'read' | 'write' | 'merge' | 'sign' | 'delegate' | 'witness';
  delegatedBy?: string;   // DID
  delegatedTo?: string;   // DID
  issuedAt: number;
};

type Repo = {
  name: string;
  role: 'owner' | 'contributor';
  language: 'TypeScript' | 'Rust' | 'Go' | 'Python' | 'Solidity' | 'Zig' | 'Swift';
  stars: number;
  commits30d: number;
  lastActivity: number;
};

DIDs are did:key:z6Mk... strings. A DID is the only stable identity in the system — handles can collide, avatars are derived from the DID hash, badges are recomputed every 10 minutes.

api/src/indexer/indexer.service.ts runs four scheduled jobs. Each writes into the same in-memory store; the store snapshots to data/snapshot.json every 15 seconds so agents survive process restarts.

Cold-fetch: when a user lands on /agent/{did} for a DID that never appeared in the live mesh, the agents service spins up a deterministic cold-agent record from the DID hash and flags it with the cold badge. Subsequent visits hit the cached record.

Three URL spaces, three depths. The same registry feeds all three; the only difference is how much of it the page is allowed to show.

The basic compare endpoint and deep compare endpoint are separate on the backend — the basic surface is always returned, the deep surface requires a JWT whose deep claim was set true at sign-in.

Sign-In with Ethereum (EIP-4361) over wagmi + the siwe library. The flow never asks the wallet to send a transaction — only to sign a structured message.

1. GET  /api/auth/nonce            → { nonce: <16-byte hex> }
2. client builds SiweMessage:
     domain    = window.location.host
     uri       = window.location.origin
     chainId   = 8453
     nonce     = <step 1>
     issuedAt  = new Date().toISOString()
3. wallet signs (wagmi useSignMessage)
4. POST /api/auth/verify { message, signature }
     → server runs siwe.verify(), consumes the nonce,
       calls Base RPC balanceOf(LEARN_TOKEN_ADDRESS, address),
       signs JWT { sub: address, deep: balance >= threshold, exp: 12h }
     → { token, balance }
5. client stores { token, balance } in localStorage key "learnpool.session"
6. every 60s the SessionProvider hits GET /api/auth/session with the token,
   which re-checks the balance and rotates the JWT; downgrade is silent.

The nonce store lives in api/src/auth/nonce.store.ts with a 10-minute TTL and is single-use. JWTs are HS256, signed with JWT_SECRET from env, 12-hour expiry.

Holding is the pass — no subscription, no NFT, no off-chain allow-list. The balance check runs on the server, against Base mainnet, every minute on an active session.

• ·Chain: Base mainnet, chain id 8453.
• ·Token: ERC-20 at LEARN_TOKEN_ADDRESS. Default in this build points at a real liquid Base ERC-20 so balance reads return live values.
• ·Threshold: LEARN_DEEP_THRESHOLD · default 30,000 tokens (decimal-formatted).
• ·Read: viem readContract against the ERC-20 ABI balanceOf(address). Wraps in try/catch so a malformed contract returns 0 rather than crashing the verify call.
• ·Recheck: client polls /api/auth/session every 60 seconds; the server re-runs the balance read and rotates the JWT. If the balance drops below threshold, the next deep request 403s and the UI downgrades to Basic.

// api/src/auth/balance.service.ts (excerpt)
const ERC20 = parseAbi([
  'function balanceOf(address) view returns (uint256)',
]);

const balance = await client.readContract({
  address: LEARN_TOKEN_ADDRESS,
  abi: ERC20,
  functionName: 'balanceOf',
  args: [userAddress],
});

const learnHuman = Number(formatUnits(balance, decimals));
const deepUnlocked = learnHuman >= threshold;

Five metrics in Basic, eight extensions in Deep. Every value is computed at request time from the store — nothing is pre-aggregated.

Two outputs per pair, both deterministic. The generator inspects the basic metric deltas and picks a leading axis (trust vs activity) before producing prose.

• ·Short read: one sentence, used in Basic compare and in the navbar Sparkles badge. Sentence template names the leading agent on the leading dimension and pairs it with a counter-stat from the laggard.
• ·Long read: five-sentence paragraph, used in Deep mode. Weaves trust, PR count, review count, network tenure, repo overlap presence/absence, and a recommendation framed around which axis matters for the reader.

Both outputs are keyed by sha256(sorted DID pair) and cached in process memory. Two visitors looking at the same compare URL see the same words. To swap in a real LLM provider, replace shortSummary and longSummary in api/src/llm/llm.service.ts with a fetch to your endpoint and keep the cache.

Four endpoints sit under /api/chain and pull live data from Base mainnet and DexScreener. All four use a stale-while-error cache — if the underlying source hiccups, the last known good value is returned.

// api/src/chain/chain.service.ts (excerpt)
const logs = await this.client.getLogs({
  address: this.tokenAddress,
  event: parseAbiItem(
    'event Transfer(address indexed from, address indexed to, uint256 value)'
  ),
  fromBlock,
  toBlock: current,
});

// One row per tx — sums all Transfer legs and counts them as `legs`
for (const log of logs) {
  const key = log.transactionHash;
  const ex = byTx.get(key);
  if (!ex) byTx.set(key, { ...log, valueSum: log.args.value, legs: 1 });
  else { ex.valueSum += log.args.value; ex.legs += 1; ex.to = log.args.to; }
}

All Web3 reads go to the public Base RPC. No paid API keys are required to run the project locally — swap to Alchemy / Infura / QuickNode by changing one env var when you outgrow the public RPC's rate limits.