@wopr-network/platform-core 1.66.1 → 1.67.0

package/dist/billing/crypto/__tests__/key-server.test.js

@@ -321,6 +321,385 @@ describe("key-server routes", () => {
         expect(deps.methodStore.setEnabled).toHaveBeenCalledWith("doge", false);
     });
 });
+describe("key-server pool endpoints", () => {
+    /** Create a mock db that supports pool queries. */
+    function createPoolMockDb(opts) {
+        const keyRing = opts?.keyRing ?? null;
+        const poolEntries = opts?.poolEntries ?? [];
+        const allKeyRings = opts?.allKeyRings ?? (keyRing ? [keyRing] : []);
+        const db = {};
+        // Track which table is being queried via from()
+        db.select = vi.fn().mockReturnValue({
+            from: vi.fn().mockImplementation((table) => {
+                const tableName = table[Symbol.for("drizzle:Name")];
+                if (tableName === "key_rings") {
+                    return {
+                        where: vi.fn().mockResolvedValue(keyRing ? [keyRing] : []),
+                        orderBy: vi.fn().mockResolvedValue(allKeyRings),
+                    };
+                }
+                if (tableName === "address_pool") {
+                    return {
+                        where: vi.fn().mockImplementation(() => ({
+                            orderBy: vi.fn().mockImplementation(() => ({
+                                limit: vi.fn().mockResolvedValue(poolEntries.filter((e) => e.assignedTo === null).slice(0, 1)),
+                            })),
+                            // For counting all pool entries for a key ring
+                            length: poolEntries.length,
+                            filter: (fn) => poolEntries.filter(fn),
+                            [Symbol.iterator]: function* () {
+                                yield* poolEntries;
+                            },
+                        })),
+                    };
+                }
+                // Default: payment_methods
+                return {
+                    where: vi.fn().mockResolvedValue([]),
+                };
+            }),
+        });
+        db.insert = vi.fn().mockReturnValue({
+            values: vi.fn().mockReturnValue({
+                onConflictDoNothing: vi.fn().mockResolvedValue({ rowCount: 1 }),
+            }),
+        });
+        db.update = vi.fn().mockReturnValue({
+            set: vi.fn().mockReturnValue({
+                where: vi.fn().mockReturnValue({
+                    returning: vi.fn().mockResolvedValue([]),
+                }),
+            }),
+        });
+        db.transaction = vi.fn().mockImplementation(async (fn) => fn(db));
+        return db;
+    }
+    it("POST /admin/pool/replenish validates required fields", async () => {
+        const deps = mockDeps();
+        deps.adminToken = "test-admin";
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/admin/pool/replenish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+            body: JSON.stringify({}),
+        });
+        expect(res.status).toBe(400);
+    });
+    it("POST /admin/pool/replenish returns 404 for unknown key ring", async () => {
+        const db = createPoolMockDb({ keyRing: null });
+        const deps = mockDeps();
+        deps.adminToken = "test-admin";
+        deps.db = db;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/admin/pool/replenish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+            body: JSON.stringify({
+                key_ring_id: "sol-main",
+                plugin_id: "solana",
+                encoding: "base58-solana",
+                addresses: [{ index: 0, public_key: "abcd", address: "SolAddr1" }],
+            }),
+        });
+        expect(res.status).toBe(404);
+    });
+    it("POST /admin/pool/replenish inserts validated addresses", async () => {
+        const db = createPoolMockDb({
+            keyRing: { id: "sol-main", derivationMode: "pre-derived" },
+            poolEntries: [],
+        });
+        // Override select().from() to handle both keyRings query and the count query
+        const selectMock = vi.fn().mockReturnValue({
+            from: vi.fn().mockImplementation((table) => {
+                const tableName = table[Symbol.for("drizzle:Name")];
+                if (tableName === "key_rings") {
+                    return {
+                        where: vi.fn().mockResolvedValue([{ id: "sol-main", derivationMode: "pre-derived" }]),
+                    };
+                }
+                // address_pool count query (after insert)
+                return {
+                    where: vi.fn().mockResolvedValue([
+                        {
+                            id: 1,
+                            keyRingId: "sol-main",
+                            derivationIndex: 0,
+                            publicKey: "ab",
+                            address: "SolAddr0",
+                            assignedTo: null,
+                        },
+                        {
+                            id: 2,
+                            keyRingId: "sol-main",
+                            derivationIndex: 1,
+                            publicKey: "cd",
+                            address: "SolAddr1",
+                            assignedTo: null,
+                        },
+                    ]),
+                };
+            }),
+        });
+        db.select = selectMock;
+        const deps = mockDeps();
+        deps.adminToken = "test-admin";
+        deps.db = db;
+        // No registry — skip re-encoding validation
+        deps.registry = undefined;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/admin/pool/replenish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+            body: JSON.stringify({
+                key_ring_id: "sol-main",
+                plugin_id: "solana",
+                encoding: "base58-solana",
+                addresses: [
+                    { index: 0, public_key: "ab", address: "SolAddr0" },
+                    { index: 1, public_key: "cd", address: "SolAddr1" },
+                ],
+            }),
+        });
+        expect(res.status).toBe(201);
+        const body = await res.json();
+        expect(body.inserted).toBe(2);
+        expect(body.total).toBe(2);
+    });
+    it("POST /admin/pool/replenish rejects mismatched address when encoder present", async () => {
+        const mockEncoder = {
+            encode: vi.fn().mockReturnValue("CorrectAddress"),
+            encodingType: vi.fn().mockReturnValue("base58-solana"),
+        };
+        const mockPlugin = {
+            pluginId: "solana",
+            supportedCurve: "ed25519",
+            encoders: { "base58-solana": mockEncoder },
+            createWatcher: vi.fn(),
+            createSweeper: vi.fn(),
+            version: 1,
+        };
+        const mockRegistry = {
+            get: vi.fn().mockReturnValue(mockPlugin),
+            getOrThrow: vi.fn(),
+            list: vi.fn(),
+            register: vi.fn(),
+        };
+        const db = createPoolMockDb({
+            keyRing: { id: "sol-main", derivationMode: "pre-derived" },
+        });
+        const deps = mockDeps();
+        deps.adminToken = "test-admin";
+        deps.db = db;
+        deps.registry = mockRegistry;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/admin/pool/replenish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+            body: JSON.stringify({
+                key_ring_id: "sol-main",
+                plugin_id: "solana",
+                encoding: "base58-solana",
+                addresses: [{ index: 0, public_key: "abcd1234", address: "WrongAddress" }],
+            }),
+        });
+        expect(res.status).toBe(400);
+        const body = await res.json();
+        expect(body.error).toContain("Address mismatch");
+    });
+    it("GET /admin/pool/status returns pool stats", async () => {
+        const db = createPoolMockDb({
+            allKeyRings: [{ id: "sol-main" }],
+            poolEntries: [
+                { id: 1, keyRingId: "sol-main", derivationIndex: 0, publicKey: "a", address: "A", assignedTo: null },
+                { id: 2, keyRingId: "sol-main", derivationIndex: 1, publicKey: "b", address: "B", assignedTo: "tenant:1" },
+                { id: 3, keyRingId: "sol-main", derivationIndex: 2, publicKey: "c", address: "C", assignedTo: null },
+            ],
+        });
+        // Override select to handle the two different query patterns in pool/status
+        let selectCallCount = 0;
+        const poolEntries = [
+            { id: 1, keyRingId: "sol-main", derivationIndex: 0, publicKey: "a", address: "A", assignedTo: null },
+            { id: 2, keyRingId: "sol-main", derivationIndex: 1, publicKey: "b", address: "B", assignedTo: "tenant:1" },
+            { id: 3, keyRingId: "sol-main", derivationIndex: 2, publicKey: "c", address: "C", assignedTo: null },
+        ];
+        db.select = vi.fn().mockReturnValue({
+            from: vi.fn().mockImplementation(() => {
+                selectCallCount++;
+                if (selectCallCount === 1) {
+                    // First call: select from keyRings (no where clause)
+                    return [{ id: "sol-main" }];
+                }
+                // Second call: select from addressPool where keyRingId = ring.id
+                return {
+                    where: vi.fn().mockResolvedValue(poolEntries),
+                };
+            }),
+        });
+        const deps = mockDeps();
+        deps.adminToken = "test-admin";
+        deps.db = db;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/admin/pool/status", {
+            headers: { Authorization: "Bearer test-admin" },
+        });
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(body.pools).toHaveLength(1);
+        expect(body.pools[0].key_ring_id).toBe("sol-main");
+        expect(body.pools[0].total).toBe(3);
+        expect(body.pools[0].available).toBe(2);
+        expect(body.pools[0].assigned).toBe(1);
+    });
+    it("POST /address uses pool for pre-derived key ring", async () => {
+        const poolEntry = {
+            id: 1,
+            keyRingId: "sol-main",
+            derivationIndex: 7,
+            publicKey: "deadbeef",
+            address: "SolanaAddr7",
+            assignedTo: null,
+            createdAt: "2026-01-01",
+        };
+        const solMethod = {
+            id: "sol",
+            type: "native",
+            token: "SOL",
+            chain: "solana",
+            xpub: null,
+            keyRingId: "sol-main",
+            nextIndex: 0,
+            decimals: 9,
+            addressType: "base58-solana",
+            encodingParams: "{}",
+            watcherType: "solana",
+            oracleAssetId: "solana",
+            confirmations: 1,
+            pluginId: "solana",
+            encoding: "base58-solana",
+        };
+        const keyRing = {
+            id: "sol-main",
+            curve: "ed25519",
+            derivationScheme: "slip10",
+            derivationMode: "pre-derived",
+            keyMaterial: "{}",
+            coinType: 501,
+            accountIndex: 0,
+        };
+        // Build a mock that handles the pool flow:
+        // 1. select from paymentMethods where id=sol -> solMethod
+        // 2. select from keyRings where id=sol-main -> keyRing
+        // 3. transaction: select from addressPool -> poolEntry, update addressPool, insert derivedAddresses
+        let selectCallCount = 0;
+        const db = {
+            select: vi.fn().mockImplementation(() => ({
+                from: vi.fn().mockImplementation(() => {
+                    selectCallCount++;
+                    if (selectCallCount === 1) {
+                        // paymentMethods lookup
+                        return { where: vi.fn().mockResolvedValue([solMethod]) };
+                    }
+                    if (selectCallCount === 2) {
+                        // keyRings lookup
+                        return { where: vi.fn().mockResolvedValue([keyRing]) };
+                    }
+                    // addressPool query inside transaction
+                    return {
+                        where: vi.fn().mockReturnValue({
+                            orderBy: vi.fn().mockReturnValue({
+                                limit: vi.fn().mockResolvedValue([poolEntry]),
+                            }),
+                        }),
+                    };
+                }),
+            })),
+            update: vi.fn().mockReturnValue({
+                set: vi.fn().mockReturnValue({
+                    where: vi.fn().mockResolvedValue(undefined),
+                }),
+            }),
+            insert: vi.fn().mockReturnValue({
+                values: vi.fn().mockResolvedValue(undefined),
+            }),
+            transaction: vi.fn().mockImplementation(async (fn) => fn(db)),
+        };
+        const deps = mockDeps();
+        deps.db = db;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/address", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ chain: "sol" }),
+        });
+        expect(res.status).toBe(201);
+        const body = await res.json();
+        expect(body.address).toBe("SolanaAddr7");
+        expect(body.index).toBe(7);
+        expect(body.chain).toBe("solana");
+        expect(body.token).toBe("SOL");
+    });
+    it("POST /address throws when pool is empty", async () => {
+        const solMethod = {
+            id: "sol",
+            type: "native",
+            token: "SOL",
+            chain: "solana",
+            xpub: null,
+            keyRingId: "sol-main",
+            nextIndex: 0,
+            decimals: 9,
+            addressType: "base58-solana",
+            encodingParams: "{}",
+            watcherType: "solana",
+            oracleAssetId: "solana",
+            confirmations: 1,
+            pluginId: "solana",
+            encoding: "base58-solana",
+        };
+        const keyRing = {
+            id: "sol-main",
+            curve: "ed25519",
+            derivationScheme: "slip10",
+            derivationMode: "pre-derived",
+            keyMaterial: "{}",
+            coinType: 501,
+            accountIndex: 0,
+        };
+        let selectCallCount = 0;
+        const db = {
+            select: vi.fn().mockImplementation(() => ({
+                from: vi.fn().mockImplementation(() => {
+                    selectCallCount++;
+                    if (selectCallCount === 1) {
+                        return { where: vi.fn().mockResolvedValue([solMethod]) };
+                    }
+                    if (selectCallCount === 2) {
+                        return { where: vi.fn().mockResolvedValue([keyRing]) };
+                    }
+                    // Empty pool
+                    return {
+                        where: vi.fn().mockReturnValue({
+                            orderBy: vi.fn().mockReturnValue({
+                                limit: vi.fn().mockResolvedValue([]),
+                            }),
+                        }),
+                    };
+                }),
+            })),
+            transaction: vi.fn().mockImplementation(async (fn) => fn(db)),
+        };
+        const deps = mockDeps();
+        deps.db = db;
+        const app = createKeyServerApp(deps);
+        const res = await app.request("/address", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ chain: "sol" }),
+        });
+        // Hono catches the thrown error and returns 500
+        expect(res.status).toBe(500);
+    });
+});
 describe("key-server auth", () => {
     it("rejects unauthenticated request when serviceKey is set", async () => {
         const deps = mockDeps();

package/dist/billing/crypto/key-server.js

@@ -8,23 +8,69 @@
  * ~200 lines of new code wrapping platform-core's existing crypto modules.
  */
 import { HDKey } from "@scure/bip32";
-import { eq, sql } from "drizzle-orm";
+import { and, eq, isNull, sql } from "drizzle-orm";
 import { Hono } from "hono";
-import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
+import { addressPool, derivedAddresses, keyRings, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
 import { deriveAddress } from "./address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
 import { AssetNotSupportedError } from "./oracle/types.js";
+/**
+ * Claim the next address from the pre-derived address pool.
+ * Used for Ed25519 chains (Solana, etc.) that can't derive from an xpub.
+ */
+async function claimFromPool(db, keyRingId, chainId, tenantId) {
+    const dbWithTx = db;
+    const result = await dbWithTx.transaction(async (tx) => {
+        // Find the next unassigned address (lowest index first)
+        const [poolEntry] = await tx
+            .select()
+            .from(addressPool)
+            .where(and(eq(addressPool.keyRingId, keyRingId), isNull(addressPool.assignedTo)))
+            .orderBy(addressPool.derivationIndex)
+            .limit(1);
+        if (!poolEntry) {
+            throw new Error(`No available addresses in pool for ${keyRingId}. Run crypto-sweep replenish.`);
+        }
+        // Mark as assigned
+        const assignmentId = tenantId ? `${chainId}:${tenantId}` : chainId;
+        await tx.update(addressPool).set({ assignedTo: assignmentId }).where(eq(addressPool.id, poolEntry.id));
+        // Record in derived_addresses for tracking
+        await tx.insert(derivedAddresses).values({
+            chainId,
+            derivationIndex: poolEntry.derivationIndex,
+            address: poolEntry.address,
+            tenantId,
+        });
+        return { address: poolEntry.address, index: poolEntry.derivationIndex };
+    });
+    return result;
+}
 /**
  * Derive the next unused address for a chain.
- * Atomically increments next_index and records address in a single transaction.
  *
- * EVM chains share an xpub (coin type 60), so ETH index 0 = USDC index 0 = same
- * address. The unique constraint on derived_addresses.address prevents reuse.
+ * For Ed25519 chains with a key ring in "pre-derived" mode (or no xpub),
+ * claims from the address pool instead of deriving from an xpub.
+ *
+ * For xpub-based chains, atomically increments next_index and records
+ * the address in a single transaction. EVM chains share an xpub (coin type 60),
+ * so the unique constraint on derived_addresses.address prevents reuse.
  * On collision, we skip the index and retry (up to maxRetries).
  */
 async function deriveNextAddress(db, chainId, tenantId, registry) {
     const maxRetries = 10;
     const dbWithTx = db;
+    // Check if this payment method uses pool-based derivation (Ed25519 chains).
+    // Look up the method first to check for key_ring_id with derivation_mode = 'pre-derived'.
+    const [methodCheck] = await db.select().from(paymentMethods).where(eq(paymentMethods.id, chainId));
+    if (methodCheck?.keyRingId) {
+        // Check the key ring's derivation mode
+        const [ring] = await db.select().from(keyRings).where(eq(keyRings.id, methodCheck.keyRingId));
+        if (ring?.derivationMode === "pre-derived" || (!methodCheck.xpub && ring)) {
+            // Pool mode: claim from pre-derived addresses
+            const { address, index } = await claimFromPool(db, methodCheck.keyRingId, chainId, tenantId);
+            return { address, index, chain: methodCheck.chain, token: methodCheck.token };
+        }
+    }
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         // Step 1: Atomically claim the next index OUTSIDE the transaction.
         // This survives even if the transaction below rolls back on address collision.
@@ -344,5 +390,83 @@ export function createKeyServerApp(deps) {
         await deps.methodStore.setEnabled(c.req.param("id"), false);
         return c.body(null, 204);
     });
+    /** POST /admin/pool/replenish — upload pre-derived addresses for Ed25519 chains */
+    app.post("/admin/pool/replenish", async (c) => {
+        const body = await c.req.json();
+        if (!body.key_ring_id ||
+            !body.plugin_id ||
+            !body.encoding ||
+            !Array.isArray(body.addresses) ||
+            body.addresses.length === 0) {
+            return c.json({ error: "key_ring_id, plugin_id, encoding, and a non-empty addresses array are required" }, 400);
+        }
+        // Validate the key ring exists
+        const [ring] = await deps.db.select().from(keyRings).where(eq(keyRings.id, body.key_ring_id));
+        if (!ring) {
+            return c.json({ error: `Key ring not found: ${body.key_ring_id}` }, 404);
+        }
+        // Look up the plugin encoder for validation
+        const plugin = deps.registry?.get(body.plugin_id);
+        const encoder = plugin?.encoders[body.encoding];
+        // Validate each address against the public key
+        for (const entry of body.addresses) {
+            if (typeof entry.index !== "number" || !entry.public_key || !entry.address) {
+                return c.json({ error: `Invalid entry at index ${entry.index}: index, public_key, and address are required` }, 400);
+            }
+            // If we have an encoder, validate the address by re-encoding the public key
+            if (encoder) {
+                const pubKeyBytes = hexToBytes(entry.public_key);
+                const reEncoded = encoder.encode(pubKeyBytes, {});
+                if (reEncoded !== entry.address) {
+                    return c.json({
+                        error: `Address mismatch at index ${entry.index}: expected ${reEncoded}, got ${entry.address}`,
+                    }, 400);
+                }
+            }
+        }
+        // Insert validated addresses into the pool
+        let inserted = 0;
+        for (const entry of body.addresses) {
+            const result = (await deps.db
+                .insert(addressPool)
+                .values({
+                keyRingId: body.key_ring_id,
+                derivationIndex: entry.index,
+                publicKey: entry.public_key,
+                address: entry.address,
+            })
+                .onConflictDoNothing());
+            inserted += result.rowCount;
+        }
+        // Get total pool size for this key ring
+        const totalRows = await deps.db.select().from(addressPool).where(eq(addressPool.keyRingId, body.key_ring_id));
+        return c.json({ inserted, total: totalRows.length }, 201);
+    });
+    /** GET /admin/pool/status — pool stats per key ring */
+    app.get("/admin/pool/status", async (c) => {
+        // Get all key rings
+        const rings = await deps.db.select().from(keyRings);
+        const pools = await Promise.all(rings.map(async (ring) => {
+            const allEntries = await deps.db.select().from(addressPool).where(eq(addressPool.keyRingId, ring.id));
+            const available = allEntries.filter((e) => e.assignedTo === null).length;
+            const assigned = allEntries.length - available;
+            return {
+                key_ring_id: ring.id,
+                total: allEntries.length,
+                available,
+                assigned,
+            };
+        }));
+        return c.json({ pools });
+    });
     return app;
 }
+/** Convert a hex string to Uint8Array. */
+function hexToBytes(hex) {
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.66.1",
+  "version": "1.67.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/__tests__/key-server.test.ts

@@ -3,6 +3,7 @@ import type { ICryptoChargeRepository } from "../charge-store.js";
 import type { KeyServerDeps } from "../key-server.js";
 import { createKeyServerApp } from "../key-server.js";
 import type { IPaymentMethodStore } from "../payment-method-store.js";
+import type { PluginRegistry } from "../plugin/registry.js";
 
 /** Create a mock db that supports transaction() by passing itself to the callback. */
 function createMockDb() {
@@ -350,6 +351,433 @@ describe("key-server routes", () => {
   });
 });
 
+describe("key-server pool endpoints", () => {
+  /** Create a mock db that supports pool queries. */
+  function createPoolMockDb(opts?: {
+    keyRing?: { id: string; derivationMode: string } | null;
+    poolEntries?: Array<{
+      id: number;
+      keyRingId: string;
+      derivationIndex: number;
+      publicKey: string;
+      address: string;
+      assignedTo: string | null;
+    }>;
+    allKeyRings?: Array<{ id: string }>;
+  }) {
+    const keyRing = opts?.keyRing ?? null;
+    const poolEntries = opts?.poolEntries ?? [];
+    const allKeyRings = opts?.allKeyRings ?? (keyRing ? [keyRing] : []);
+
+    const db: Record<string, unknown> = {};
+
+    // Track which table is being queried via from()
+    db.select = vi.fn().mockReturnValue({
+      from: vi.fn().mockImplementation((table: unknown) => {
+        const tableName = (table as Record<symbol, string>)[Symbol.for("drizzle:Name")];
+        if (tableName === "key_rings") {
+          return {
+            where: vi.fn().mockResolvedValue(keyRing ? [keyRing] : []),
+            orderBy: vi.fn().mockResolvedValue(allKeyRings),
+          };
+        }
+        if (tableName === "address_pool") {
+          return {
+            where: vi.fn().mockImplementation(() => ({
+              orderBy: vi.fn().mockImplementation(() => ({
+                limit: vi.fn().mockResolvedValue(poolEntries.filter((e) => e.assignedTo === null).slice(0, 1)),
+              })),
+              // For counting all pool entries for a key ring
+              length: poolEntries.length,
+              filter: (fn: (e: unknown) => boolean) => poolEntries.filter(fn),
+              [Symbol.iterator]: function* () {
+                yield* poolEntries;
+              },
+            })),
+          };
+        }
+        // Default: payment_methods
+        return {
+          where: vi.fn().mockResolvedValue([]),
+        };
+      }),
+    });
+
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockReturnValue({
+        onConflictDoNothing: vi.fn().mockResolvedValue({ rowCount: 1 }),
+      }),
+    });
+
+    db.update = vi.fn().mockReturnValue({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          returning: vi.fn().mockResolvedValue([]),
+        }),
+      }),
+    });
+
+    db.transaction = vi.fn().mockImplementation(async (fn: (tx: unknown) => unknown) => fn(db));
+
+    return db;
+  }
+
+  it("POST /admin/pool/replenish validates required fields", async () => {
+    const deps = mockDeps();
+    deps.adminToken = "test-admin";
+    const app = createKeyServerApp(deps);
+    const res = await app.request("/admin/pool/replenish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("POST /admin/pool/replenish returns 404 for unknown key ring", async () => {
+    const db = createPoolMockDb({ keyRing: null });
+    const deps = mockDeps();
+    deps.adminToken = "test-admin";
+    (deps as unknown as { db: unknown }).db = db;
+    const app = createKeyServerApp(deps);
+    const res = await app.request("/admin/pool/replenish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+      body: JSON.stringify({
+        key_ring_id: "sol-main",
+        plugin_id: "solana",
+        encoding: "base58-solana",
+        addresses: [{ index: 0, public_key: "abcd", address: "SolAddr1" }],
+      }),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("POST /admin/pool/replenish inserts validated addresses", async () => {
+    const db = createPoolMockDb({
+      keyRing: { id: "sol-main", derivationMode: "pre-derived" },
+      poolEntries: [],
+    });
+
+    // Override select().from() to handle both keyRings query and the count query
+    const selectMock = vi.fn().mockReturnValue({
+      from: vi.fn().mockImplementation((table: unknown) => {
+        const tableName = (table as Record<symbol, string>)[Symbol.for("drizzle:Name")];
+        if (tableName === "key_rings") {
+          return {
+            where: vi.fn().mockResolvedValue([{ id: "sol-main", derivationMode: "pre-derived" }]),
+          };
+        }
+        // address_pool count query (after insert)
+        return {
+          where: vi.fn().mockResolvedValue([
+            {
+              id: 1,
+              keyRingId: "sol-main",
+              derivationIndex: 0,
+              publicKey: "ab",
+              address: "SolAddr0",
+              assignedTo: null,
+            },
+            {
+              id: 2,
+              keyRingId: "sol-main",
+              derivationIndex: 1,
+              publicKey: "cd",
+              address: "SolAddr1",
+              assignedTo: null,
+            },
+          ]),
+        };
+      }),
+    });
+    (db as Record<string, unknown>).select = selectMock;
+
+    const deps = mockDeps();
+    deps.adminToken = "test-admin";
+    (deps as unknown as { db: unknown }).db = db;
+    // No registry — skip re-encoding validation
+    deps.registry = undefined;
+
+    const app = createKeyServerApp(deps);
+    const res = await app.request("/admin/pool/replenish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+      body: JSON.stringify({
+        key_ring_id: "sol-main",
+        plugin_id: "solana",
+        encoding: "base58-solana",
+        addresses: [
+          { index: 0, public_key: "ab", address: "SolAddr0" },
+          { index: 1, public_key: "cd", address: "SolAddr1" },
+        ],
+      }),
+    });
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.inserted).toBe(2);
+    expect(body.total).toBe(2);
+  });
+
+  it("POST /admin/pool/replenish rejects mismatched address when encoder present", async () => {
+    const mockEncoder = {
+      encode: vi.fn().mockReturnValue("CorrectAddress"),
+      encodingType: vi.fn().mockReturnValue("base58-solana"),
+    };
+    const mockPlugin = {
+      pluginId: "solana",
+      supportedCurve: "ed25519" as const,
+      encoders: { "base58-solana": mockEncoder },
+      createWatcher: vi.fn(),
+      createSweeper: vi.fn(),
+      version: 1,
+    };
+    const mockRegistry = {
+      get: vi.fn().mockReturnValue(mockPlugin),
+      getOrThrow: vi.fn(),
+      list: vi.fn(),
+      register: vi.fn(),
+    };
+
+    const db = createPoolMockDb({
+      keyRing: { id: "sol-main", derivationMode: "pre-derived" },
+    });
+
+    const deps = mockDeps();
+    deps.adminToken = "test-admin";
+    (deps as unknown as { db: unknown }).db = db;
+    deps.registry = mockRegistry as unknown as PluginRegistry;
+
+    const app = createKeyServerApp(deps);
+    const res = await app.request("/admin/pool/replenish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin" },
+      body: JSON.stringify({
+        key_ring_id: "sol-main",
+        plugin_id: "solana",
+        encoding: "base58-solana",
+        addresses: [{ index: 0, public_key: "abcd1234", address: "WrongAddress" }],
+      }),
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("Address mismatch");
+  });
+
+  it("GET /admin/pool/status returns pool stats", async () => {
+    const db = createPoolMockDb({
+      allKeyRings: [{ id: "sol-main" }],
+      poolEntries: [
+        { id: 1, keyRingId: "sol-main", derivationIndex: 0, publicKey: "a", address: "A", assignedTo: null },
+        { id: 2, keyRingId: "sol-main", derivationIndex: 1, publicKey: "b", address: "B", assignedTo: "tenant:1" },
+        { id: 3, keyRingId: "sol-main", derivationIndex: 2, publicKey: "c", address: "C", assignedTo: null },
+      ],
+    });
+
+    // Override select to handle the two different query patterns in pool/status
+    let selectCallCount = 0;
+    const poolEntries = [
+      { id: 1, keyRingId: "sol-main", derivationIndex: 0, publicKey: "a", address: "A", assignedTo: null },
+      { id: 2, keyRingId: "sol-main", derivationIndex: 1, publicKey: "b", address: "B", assignedTo: "tenant:1" },
+      { id: 3, keyRingId: "sol-main", derivationIndex: 2, publicKey: "c", address: "C", assignedTo: null },
+    ];
+    (db as Record<string, unknown>).select = vi.fn().mockReturnValue({
+      from: vi.fn().mockImplementation(() => {
+        selectCallCount++;
+        if (selectCallCount === 1) {
+          // First call: select from keyRings (no where clause)
+          return [{ id: "sol-main" }];
+        }
+        // Second call: select from addressPool where keyRingId = ring.id
+        return {
+          where: vi.fn().mockResolvedValue(poolEntries),
+        };
+      }),
+    });
+
+    const deps = mockDeps();
+    deps.adminToken = "test-admin";
+    (deps as unknown as { db: unknown }).db = db;
+    const app = createKeyServerApp(deps);
+
+    const res = await app.request("/admin/pool/status", {
+      headers: { Authorization: "Bearer test-admin" },
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.pools).toHaveLength(1);
+    expect(body.pools[0].key_ring_id).toBe("sol-main");
+    expect(body.pools[0].total).toBe(3);
+    expect(body.pools[0].available).toBe(2);
+    expect(body.pools[0].assigned).toBe(1);
+  });
+
+  it("POST /address uses pool for pre-derived key ring", async () => {
+    const poolEntry = {
+      id: 1,
+      keyRingId: "sol-main",
+      derivationIndex: 7,
+      publicKey: "deadbeef",
+      address: "SolanaAddr7",
+      assignedTo: null,
+      createdAt: "2026-01-01",
+    };
+
+    const solMethod = {
+      id: "sol",
+      type: "native",
+      token: "SOL",
+      chain: "solana",
+      xpub: null,
+      keyRingId: "sol-main",
+      nextIndex: 0,
+      decimals: 9,
+      addressType: "base58-solana",
+      encodingParams: "{}",
+      watcherType: "solana",
+      oracleAssetId: "solana",
+      confirmations: 1,
+      pluginId: "solana",
+      encoding: "base58-solana",
+    };
+
+    const keyRing = {
+      id: "sol-main",
+      curve: "ed25519",
+      derivationScheme: "slip10",
+      derivationMode: "pre-derived",
+      keyMaterial: "{}",
+      coinType: 501,
+      accountIndex: 0,
+    };
+
+    // Build a mock that handles the pool flow:
+    // 1. select from paymentMethods where id=sol -> solMethod
+    // 2. select from keyRings where id=sol-main -> keyRing
+    // 3. transaction: select from addressPool -> poolEntry, update addressPool, insert derivedAddresses
+    let selectCallCount = 0;
+    const db = {
+      select: vi.fn().mockImplementation(() => ({
+        from: vi.fn().mockImplementation(() => {
+          selectCallCount++;
+          if (selectCallCount === 1) {
+            // paymentMethods lookup
+            return { where: vi.fn().mockResolvedValue([solMethod]) };
+          }
+          if (selectCallCount === 2) {
+            // keyRings lookup
+            return { where: vi.fn().mockResolvedValue([keyRing]) };
+          }
+          // addressPool query inside transaction
+          return {
+            where: vi.fn().mockReturnValue({
+              orderBy: vi.fn().mockReturnValue({
+                limit: vi.fn().mockResolvedValue([poolEntry]),
+              }),
+            }),
+          };
+        }),
+      })),
+      update: vi.fn().mockReturnValue({
+        set: vi.fn().mockReturnValue({
+          where: vi.fn().mockResolvedValue(undefined),
+        }),
+      }),
+      insert: vi.fn().mockReturnValue({
+        values: vi.fn().mockResolvedValue(undefined),
+      }),
+      transaction: vi.fn().mockImplementation(async (fn: (tx: unknown) => unknown) => fn(db)),
+    };
+
+    const deps = mockDeps();
+    (deps as unknown as { db: unknown }).db = db;
+    const app = createKeyServerApp(deps);
+
+    const res = await app.request("/address", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ chain: "sol" }),
+    });
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.address).toBe("SolanaAddr7");
+    expect(body.index).toBe(7);
+    expect(body.chain).toBe("solana");
+    expect(body.token).toBe("SOL");
+  });
+
+  it("POST /address throws when pool is empty", async () => {
+    const solMethod = {
+      id: "sol",
+      type: "native",
+      token: "SOL",
+      chain: "solana",
+      xpub: null,
+      keyRingId: "sol-main",
+      nextIndex: 0,
+      decimals: 9,
+      addressType: "base58-solana",
+      encodingParams: "{}",
+      watcherType: "solana",
+      oracleAssetId: "solana",
+      confirmations: 1,
+      pluginId: "solana",
+      encoding: "base58-solana",
+    };
+
+    const keyRing = {
+      id: "sol-main",
+      curve: "ed25519",
+      derivationScheme: "slip10",
+      derivationMode: "pre-derived",
+      keyMaterial: "{}",
+      coinType: 501,
+      accountIndex: 0,
+    };
+
+    let selectCallCount = 0;
+    const db = {
+      select: vi.fn().mockImplementation(() => ({
+        from: vi.fn().mockImplementation(() => {
+          selectCallCount++;
+          if (selectCallCount === 1) {
+            return { where: vi.fn().mockResolvedValue([solMethod]) };
+          }
+          if (selectCallCount === 2) {
+            return { where: vi.fn().mockResolvedValue([keyRing]) };
+          }
+          // Empty pool
+          return {
+            where: vi.fn().mockReturnValue({
+              orderBy: vi.fn().mockReturnValue({
+                limit: vi.fn().mockResolvedValue([]),
+              }),
+            }),
+          };
+        }),
+      })),
+      transaction: vi.fn().mockImplementation(async (fn: (tx: unknown) => unknown) => fn(db)),
+    };
+
+    const deps = mockDeps();
+    (deps as unknown as { db: unknown }).db = db;
+    const app = createKeyServerApp(deps);
+
+    const res = await app.request("/address", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ chain: "sol" }),
+    });
+
+    // Hono catches the thrown error and returns 500
+    expect(res.status).toBe(500);
+  });
+});
+
 describe("key-server auth", () => {
   it("rejects unauthenticated request when serviceKey is set", async () => {
     const deps = mockDeps();

package/src/billing/crypto/key-server.ts

@@ -9,10 +9,10 @@
  */
 
 import { HDKey } from "@scure/bip32";
-import { eq, sql } from "drizzle-orm";
+import { and, eq, isNull, sql } from "drizzle-orm";
 import { Hono } from "hono";
 import type { DrizzleDb } from "../../db/index.js";
-import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
+import { addressPool, derivedAddresses, keyRings, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
 import type { EncodingParams } from "./address-gen.js";
 import { deriveAddress } from "./address-gen.js";
 import type { ICryptoChargeRepository } from "./charge-store.js";
@@ -35,12 +35,58 @@ export interface KeyServerDeps {
   registry?: PluginRegistry;
 }
 
+/**
+ * Claim the next address from the pre-derived address pool.
+ * Used for Ed25519 chains (Solana, etc.) that can't derive from an xpub.
+ */
+async function claimFromPool(
+  db: DrizzleDb,
+  keyRingId: string,
+  chainId: string,
+  tenantId?: string,
+): Promise<{ address: string; index: number }> {
+  const dbWithTx = db as unknown as { transaction: (fn: (tx: DrizzleDb) => Promise<unknown>) => Promise<unknown> };
+
+  const result = await dbWithTx.transaction(async (tx: DrizzleDb) => {
+    // Find the next unassigned address (lowest index first)
+    const [poolEntry] = await tx
+      .select()
+      .from(addressPool)
+      .where(and(eq(addressPool.keyRingId, keyRingId), isNull(addressPool.assignedTo)))
+      .orderBy(addressPool.derivationIndex)
+      .limit(1);
+
+    if (!poolEntry) {
+      throw new Error(`No available addresses in pool for ${keyRingId}. Run crypto-sweep replenish.`);
+    }
+
+    // Mark as assigned
+    const assignmentId = tenantId ? `${chainId}:${tenantId}` : chainId;
+    await tx.update(addressPool).set({ assignedTo: assignmentId }).where(eq(addressPool.id, poolEntry.id));
+
+    // Record in derived_addresses for tracking
+    await tx.insert(derivedAddresses).values({
+      chainId,
+      derivationIndex: poolEntry.derivationIndex,
+      address: poolEntry.address,
+      tenantId,
+    });
+
+    return { address: poolEntry.address, index: poolEntry.derivationIndex };
+  });
+
+  return result as { address: string; index: number };
+}
+
 /**
  * Derive the next unused address for a chain.
- * Atomically increments next_index and records address in a single transaction.
  *
- * EVM chains share an xpub (coin type 60), so ETH index 0 = USDC index 0 = same
- * address. The unique constraint on derived_addresses.address prevents reuse.
+ * For Ed25519 chains with a key ring in "pre-derived" mode (or no xpub),
+ * claims from the address pool instead of deriving from an xpub.
+ *
+ * For xpub-based chains, atomically increments next_index and records
+ * the address in a single transaction. EVM chains share an xpub (coin type 60),
+ * so the unique constraint on derived_addresses.address prevents reuse.
  * On collision, we skip the index and retry (up to maxRetries).
  */
 async function deriveNextAddress(
@@ -52,6 +98,21 @@ async function deriveNextAddress(
   const maxRetries = 10;
   const dbWithTx = db as unknown as { transaction: (fn: (tx: DrizzleDb) => Promise<unknown>) => Promise<unknown> };
 
+  // Check if this payment method uses pool-based derivation (Ed25519 chains).
+  // Look up the method first to check for key_ring_id with derivation_mode = 'pre-derived'.
+  const [methodCheck] = await db.select().from(paymentMethods).where(eq(paymentMethods.id, chainId));
+
+  if (methodCheck?.keyRingId) {
+    // Check the key ring's derivation mode
+    const [ring] = await db.select().from(keyRings).where(eq(keyRings.id, methodCheck.keyRingId));
+
+    if (ring?.derivationMode === "pre-derived" || (!methodCheck.xpub && ring)) {
+      // Pool mode: claim from pre-derived addresses
+      const { address, index } = await claimFromPool(db, methodCheck.keyRingId, chainId, tenantId);
+      return { address, index, chain: methodCheck.chain, token: methodCheck.token };
+    }
+  }
+
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     // Step 1: Atomically claim the next index OUTSIDE the transaction.
     // This survives even if the transaction below rolls back on address collision.
@@ -440,5 +501,117 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
     return c.body(null, 204);
   });
 
+  /** POST /admin/pool/replenish — upload pre-derived addresses for Ed25519 chains */
+  app.post("/admin/pool/replenish", async (c) => {
+    const body = await c.req.json<{
+      key_ring_id: string;
+      plugin_id: string;
+      encoding: string;
+      addresses: Array<{
+        index: number;
+        public_key: string;
+        address: string;
+      }>;
+    }>();
+
+    if (
+      !body.key_ring_id ||
+      !body.plugin_id ||
+      !body.encoding ||
+      !Array.isArray(body.addresses) ||
+      body.addresses.length === 0
+    ) {
+      return c.json({ error: "key_ring_id, plugin_id, encoding, and a non-empty addresses array are required" }, 400);
+    }
+
+    // Validate the key ring exists
+    const [ring] = await deps.db.select().from(keyRings).where(eq(keyRings.id, body.key_ring_id));
+    if (!ring) {
+      return c.json({ error: `Key ring not found: ${body.key_ring_id}` }, 404);
+    }
+
+    // Look up the plugin encoder for validation
+    const plugin = deps.registry?.get(body.plugin_id);
+    const encoder = plugin?.encoders[body.encoding];
+
+    // Validate each address against the public key
+    for (const entry of body.addresses) {
+      if (typeof entry.index !== "number" || !entry.public_key || !entry.address) {
+        return c.json(
+          { error: `Invalid entry at index ${entry.index}: index, public_key, and address are required` },
+          400,
+        );
+      }
+
+      // If we have an encoder, validate the address by re-encoding the public key
+      if (encoder) {
+        const pubKeyBytes = hexToBytes(entry.public_key);
+        const reEncoded = encoder.encode(pubKeyBytes, {});
+        if (reEncoded !== entry.address) {
+          return c.json(
+            {
+              error: `Address mismatch at index ${entry.index}: expected ${reEncoded}, got ${entry.address}`,
+            },
+            400,
+          );
+        }
+      }
+    }
+
+    // Insert validated addresses into the pool
+    let inserted = 0;
+    for (const entry of body.addresses) {
+      const result = (await deps.db
+        .insert(addressPool)
+        .values({
+          keyRingId: body.key_ring_id,
+          derivationIndex: entry.index,
+          publicKey: entry.public_key,
+          address: entry.address,
+        })
+        .onConflictDoNothing()) as { rowCount: number };
+      inserted += result.rowCount;
+    }
+
+    // Get total pool size for this key ring
+    const totalRows = await deps.db.select().from(addressPool).where(eq(addressPool.keyRingId, body.key_ring_id));
+
+    return c.json({ inserted, total: totalRows.length }, 201);
+  });
+
+  /** GET /admin/pool/status — pool stats per key ring */
+  app.get("/admin/pool/status", async (c) => {
+    // Get all key rings
+    const rings = await deps.db.select().from(keyRings);
+
+    const pools = await Promise.all(
+      rings.map(async (ring) => {
+        const allEntries = await deps.db.select().from(addressPool).where(eq(addressPool.keyRingId, ring.id));
+
+        const available = allEntries.filter((e) => e.assignedTo === null).length;
+        const assigned = allEntries.length - available;
+
+        return {
+          key_ring_id: ring.id,
+          total: allEntries.length,
+          available,
+          assigned,
+        };
+      }),
+    );
+
+    return c.json({ pools });
+  });
+
   return app;
 }
+
+/** Convert a hex string to Uint8Array. */
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}