@stellar-agent-services/provider-kit 0.0.0-stage → 0.1.0

package/dist/provider.js

@@ -0,0 +1,177 @@
+// createProvider(): wires services, payments, the job store, the queue and the HTTP routes into one
+// Fetch-API handler.
+//
+// Returns { fetch(request) } for Hono, Node, Workers, Deno or Bun. The provider holds no Stellar
+// secret key: it knows its payTo address, and the facilitator verifies and settles.
+//
+// Startup, in order:
+// 1. createProvider() checks the config and the manifest it builds, and throws on any problem a client
+//    or verifier would reject (§2.4), so a broken provider never takes a payment.
+// 2. ready() checks that the facilitator settles this network with sponsored fees, runs the recovery
+//    sweep for jobs a restart left behind, and starts the queue's workers. create-job awaits it, and
+//    answers 503 (nothing charged) until it has succeeded; it is retried after a failure.
+// Each service gets a lane with its capacity (jobs/scheduler.ts), and create-job can have a per-caller
+// rate limit (http/rate-limit.ts): docs/provider-standard.md §5.8.
+//
+// With a Soroban RPC (`rpc`, the public one by default on testnet), the provider reads the chain: it
+// decides payment_uncertain jobs after every sweep (jobs/reconcile.ts) [J13], and times on-success jobs
+// by their payment's expiration ledger (payments/chain.ts). Neither holds up startup or a request when
+// the RPC is slow or down.
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_MANIFEST_PATH, DEFAULT_RETENTION_SECONDS, stellarAddressKind } from "@stellar-agent-services/protocol";
+import { rateLimiter } from "./http/rate-limit.js";
+import { MAX_HOLD_SECONDS, route } from "./http/router.js";
+import { memoryStore } from "./jobs/memory-store.js";
+import { reconcile } from "./jobs/reconcile.js";
+import { strandedJobs, sweep } from "./jobs/recovery.js";
+import { runLeased } from "./jobs/runner.js";
+import { laneFor, scheduler } from "./jobs/scheduler.js";
+import { buildManifest, checkManifest, DEFAULT_MAX_TIMEOUT_SECONDS } from "./manifest.js";
+import { ledgerClock, rpcChain } from "./payments/chain.js";
+import { checkFacilitator, httpFacilitator, settleTimeoutSeconds } from "./payments/facilitator.js";
+const QUEUE_POLL_MS = 1000;
+const SWEEP_INTERVAL_MS = 30_000;
+const READY_RETRY_MS = 10_000;
+export function createProvider(config) {
+    const baseUrl = new URL(config.baseUrl);
+    const local = baseUrl.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(baseUrl.hostname);
+    if (baseUrl.protocol !== "https:" && !(config.dev && local)) {
+        throw new TypeError("baseUrl must be https:// (http://localhost is allowed with dev: true)");
+    }
+    if (stellarAddressKind(config.payTo) === undefined)
+        throw new TypeError("payTo must be a valid G... or C... address");
+    const holdSeconds = config.holdSeconds ?? MAX_HOLD_SECONDS;
+    if (holdSeconds < 0 || holdSeconds > MAX_HOLD_SECONDS)
+        throw new RangeError(`holdSeconds must be 0–${MAX_HOLD_SECONDS}`);
+    const leaseSeconds = config.leaseSeconds ?? 30;
+    if (!Number.isInteger(leaseSeconds) || leaseSeconds < 3)
+        throw new RangeError("leaseSeconds must be a whole number of at least 3");
+    const maxTimeoutSeconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+    const settleSeconds = config.settleTimeoutSeconds ?? settleTimeoutSeconds(maxTimeoutSeconds);
+    if (!Number.isInteger(settleSeconds) || settleSeconds < 1)
+        throw new RangeError("settleTimeoutSeconds must be a whole number of at least 1");
+    const names = new Set();
+    for (const service of config.services) {
+        if (names.has(service.name))
+            throw new TypeError(`two services are named "${service.name}" [M7]`);
+        names.add(service.name);
+        // The signed payment expires about maxTimeoutSeconds after signing, so on-success work must
+        // finish well inside it [S2].
+        if (service.charge === "on-success" && service.expectedDurationSeconds > maxTimeoutSeconds / 2) {
+            throw new RangeError(`service "${service.name}": on-success work must take at most half of maxTimeoutSeconds [S2]; use charge "upfront"`);
+        }
+    }
+    const manifest = buildManifest(config, config.services);
+    const manifestPath = config.manifestPath ?? DEFAULT_MANIFEST_PATH;
+    const manifestUrl = new URL(manifestPath, baseUrl.origin).toString();
+    const violations = checkManifest(manifest, manifestUrl, config.dev);
+    if (violations.length > 0) {
+        const list = violations.map((violation) => `  [${violation.rule}] ${violation.pointer || "/"}: ${violation.message}`).join("\n");
+        throw new TypeError(`the manifest would not pass Provider Standard v1 checks:\n${list}`);
+    }
+    const facilitator = typeof config.facilitator === "string"
+        ? httpFacilitator(config.facilitator, { dev: config.dev ?? false, settleTimeoutSeconds: settleSeconds })
+        : config.facilitator;
+    const store = config.store ?? memoryStore();
+    const chain = config.rpc === false ? undefined : typeof config.rpc === "object" ? config.rpc : rpcChain(config.network, config.rpc, { dev: config.dev ?? false });
+    const clock = chain === undefined ? undefined : ledgerClock(chain);
+    const services = new Map(config.services.map((service) => [service.name, service]));
+    const owner = `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+    const queue = scheduler({
+        store,
+        lanes: config.services.map((service) => laneFor(service, maxTimeoutSeconds)),
+        owner,
+        leaseSeconds,
+        pollMs: QUEUE_POLL_MS,
+        ...(config.runQueuedJobs === false ? {} : { work: (job) => runLeased(job, { store, services, scheduler: queue, owner, leaseSeconds }) }),
+    });
+    const sweepOptions = {
+        maxTimeoutSeconds,
+        settleTimeoutSeconds: settleSeconds,
+        retentionSeconds: config.retentionSeconds ?? DEFAULT_RETENTION_SECONDS,
+        clock,
+    };
+    let starting;
+    let sweeps;
+    let closed = false;
+    // One reconciliation at a time: a slow RPC must not stack them up.
+    let reconciling;
+    const reconcileJobs = () => {
+        if (chain === undefined || closed)
+            return;
+        reconciling ??= (async () => {
+            const results = await reconcile(store, { chain, network: config.network, asset: manifest.payment.accepts[0].asset });
+            for (const result of results) {
+                // Undecided jobs were logged when they became uncertain, and are looked at again next time.
+                if (result.outcome === "settled")
+                    console.error(`[provider-kit] job ${result.jobId}: reconciled, settled in ${result.transaction}; now ${result.status}`);
+                if (result.outcome === "not_settled")
+                    console.error(`[provider-kit] job ${result.jobId}: reconciled, not settled (${result.reason}); now ${result.status}, nothing charged`);
+            }
+            // Paid and queued again: start them now rather than at the next poll.
+            for (const result of results)
+                if (result.status === "queued" && services.has(result.service))
+                    queue.wake(result.service);
+        })()
+            .catch((error) => console.error("[provider-kit] reconciliation failed:", error))
+            .finally(() => (reconciling = undefined));
+    };
+    const ready = () => {
+        if (closed)
+            return Promise.reject(new Error("the provider is closed"));
+        starting ??= (async () => {
+            await checkFacilitator(facilitator, config.network);
+            if (chain === undefined && config.rpc !== false) {
+                console.warn(`[provider-kit] no Soroban RPC for ${config.network}: set rpc to decide payment_uncertain jobs automatically; until then, run provider-kit reconcile`);
+            }
+            await sweep(store, sweepOptions);
+            const stranded = await strandedJobs(store, services);
+            if (stranded.size > 0) {
+                const list = [...stranded].map(([service, count]) => `${count} of "${service}"`).join(", ");
+                console.warn(`[provider-kit] paid jobs of services this provider no longer offers wait until they are offered again: ${list}`);
+            }
+            queue.start();
+            reconcileJobs();
+            sweeps = setInterval(() => {
+                sweep(store, sweepOptions).then(reconcileJobs, (error) => console.error("[provider-kit] the recovery sweep failed:", error));
+            }, SWEEP_INTERVAL_MS);
+            sweeps.unref();
+        })().catch((error) => {
+            // Try again on a later request, not on every one.
+            setTimeout(() => (starting = undefined), READY_RETRY_MS).unref();
+            throw error;
+        });
+        return starting;
+    };
+    const context = {
+        manifest,
+        manifestPath,
+        services,
+        store,
+        facilitator,
+        scheduler: queue,
+        ready,
+        rateLimit: config.rateLimit === undefined ? undefined : rateLimiter(config.rateLimit),
+        holdSeconds,
+        settleTimeoutMs: settleSeconds * 1000,
+        clock,
+        retentionSeconds: sweepOptions.retentionSeconds,
+        loseCreateJobResponse: config.loseCreateJobResponse ?? false,
+    };
+    return {
+        manifest,
+        manifestUrl,
+        fetch: (request) => route(request, context),
+        ready,
+        async close() {
+            closed = true;
+            queue.stop();
+            clearInterval(sweeps);
+            // Its writes are compare-and-set, but the store must stay open until they finish.
+            await reconciling;
+            await store.close?.();
+        },
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,qBAAqB;AACrB,EAAE;AACF,iGAAiG;AACjG,oFAAoF;AACpF,EAAE;AACF,qBAAqB;AACrB,uGAAuG;AACvG,kFAAkF;AAClF,qGAAqG;AACrG,qGAAqG;AACrG,0FAA0F;AAC1F,uGAAuG;AACvG,mEAAmE;AACnE,EAAE;AACF,qGAAqG;AACrG,wGAAwG;AACxG,uGAAuG;AACvG,2BAA2B;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,kBAAkB,EAAiE,MAAM,kCAAkC,CAAC;AAEvL,OAAO,EAAE,WAAW,EAAwB,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAoB,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAoB,MAAM,2BAA2B,CAAC;AA2DtH,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACjC,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7G,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,SAAS,CAAC,uEAAuE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACtH,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,gBAAgB,CAAC;IAC3D,IAAI,WAAW,GAAG,CAAC,IAAI,WAAW,GAAG,gBAAgB;QAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,gBAAgB,EAAE,CAAC,CAAC;IACzH,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IAEnI,MAAM,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,IAAI,2BAA2B,CAAC;IAClF,MAAM,aAAa,GAAG,MAAM,CAAC,oBAAoB,IAAI,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAC7F,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,2DAA2D,CAAC,CAAC;IAC7I,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,2BAA2B,OAAO,CAAC,IAAI,QAAQ,CAAC,CAAC;QAClG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,4FAA4F;QAC5F,8BAA8B;QAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,YAAY,IAAI,OAAO,CAAC,uBAAwB,GAAG,iBAAiB,GAAG,CAAC,EAAE,CAAC;YAChG,MAAM,IAAI,UAAU,CAAC,YAAY,OAAO,CAAC,IAAI,2FAA2F,CAAC,CAAC;QAC5I,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAClE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrE,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACpE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,IAAI,GAAG,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjI,MAAM,IAAI,SAAS,CAAC,6DAA6D,IAAI,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,WAAW,GACf,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ;QACpC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,CAAC;QACxG,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,WAAW,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC;IAClK,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,GAAG,QAAQ,EAAE,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACzE,MAAM,KAAK,GAAG,SAAS,CAAC;QACtB,KAAK;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAC5E,KAAK;QACL,YAAY;QACZ,MAAM,EAAE,aAAa;QACrB,GAAG,CAAC,MAAM,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;KACzI,CAAC,CAAC;IACH,MAAM,YAAY,GAAG;QACnB,iBAAiB;QACjB,oBAAoB,EAAE,aAAa;QACnC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,yBAAyB;QACtE,KAAK;KACN,CAAC;IAEF,IAAI,QAAmC,CAAC;IACxC,IAAI,MAAkC,CAAC;IACvC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,mEAAmE;IACnE,IAAI,WAAsC,CAAC;IAC3C,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM;YAAE,OAAO;QAC1C,WAAW,KAAK,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACrH,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,4FAA4F;gBAC5F,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;oBAAE,OAAO,CAAC,KAAK,CAAC,sBAAsB,MAAM,CAAC,KAAK,4BAA4B,MAAM,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC1J,IAAI,MAAM,CAAC,OAAO,KAAK,aAAa;oBAAE,OAAO,CAAC,KAAK,CAAC,sBAAsB,MAAM,CAAC,KAAK,8BAA8B,MAAM,CAAC,MAAM,UAAU,MAAM,CAAC,MAAM,mBAAmB,CAAC,CAAC;YAC/K,CAAC;YACD,sEAAsE;YACtE,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3H,CAAC,CAAC,EAAE;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC;aAC/E,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAAkB,EAAE;QAChC,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC;QACvE,QAAQ,KAAK,CAAC,KAAK,IAAI,EAAE;YACvB,MAAM,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACpD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,EAAE,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,qCAAqC,MAAM,CAAC,OAAO,kGAAkG,CAAC,CAAC;YACtK,CAAC;YACD,MAAM,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;YACjC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACrD,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,QAAQ,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC5F,OAAO,CAAC,IAAI,CAAC,0GAA0G,IAAI,EAAE,CAAC,CAAC;YACjI,CAAC;YACD,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,aAAa,EAAE,CAAC;YAChB,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;gBACxB,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC,CAAC;YAC/H,CAAC,EAAE,iBAAiB,CAAC,CAAC;YACtB,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACnB,kDAAkD;YAClD,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC,KAAK,EAAE,CAAC;YACjE,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,QAAQ;QACR,YAAY;QACZ,QAAQ;QACR,KAAK;QACL,WAAW;QACX,SAAS,EAAE,KAAK;QAChB,KAAK;QACL,SAAS,EAAE,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC;QACrF,WAAW;QACX,eAAe,EAAE,aAAa,GAAG,IAAI;QACrC,KAAK;QACL,gBAAgB,EAAE,YAAY,CAAC,gBAAgB;QAC/C,qBAAqB,EAAE,MAAM,CAAC,qBAAqB,IAAI,KAAK;KAC7D,CAAC;IAEF,OAAO;QACL,QAAQ;QACR,WAAW;QACX,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;QAC3C,KAAK;QACL,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,IAAI,CAAC;YACd,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,aAAa,CAAC,MAAM,CAAC,CAAC;YACtB,kFAAkF;YAClF,MAAM,WAAW,CAAC;YAClB,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/registration.d.ts

@@ -0,0 +1,86 @@
+import type { ProviderManifest, StellarNetwork } from "@stellar-agent-services/protocol";
+import { type StellarConfig } from "@trionlabs/stellar8004";
+/** The registration's service entry that points to the manifest [I1]. */
+export declare const REGISTRATION_SERVICE_NAME = "stellar-agent-services";
+export interface RegistrationOptions {
+    /** An image URL for explorers. */
+    image?: string;
+    /** ERC-8004 trust models, such as "reputation". */
+    supportedTrust?: string[];
+}
+/** The 8004 registration file for a provider whose manifest is served at `manifestUrl` [I1]. */
+export declare function registrationFile(manifest: ProviderManifest, manifestUrl: string, options?: RegistrationOptions): Record<string, unknown>;
+/** The file as a data: URI, which the registry stores on chain. Throws above 8 KiB: host the file and register its URL instead. */
+export declare function registrationDataUri(file: Record<string, unknown>): string;
+/** The 8004 contracts and RPC for a network. */
+export declare function registryConfig(network: StellarNetwork): StellarConfig;
+/** A validation request as the Validation Registry keeps it. `response` and `responseHash` are set once answered. */
+export interface ValidationRecord {
+    validator: string;
+    agentId: number;
+    hasResponse: boolean;
+    /** 0–100, higher is better. */
+    response: number;
+    /** Lowercase hex. */
+    responseHash: string;
+    tag: string;
+    /** The ledger of the last change. */
+    lastUpdate: number;
+}
+/** The registry reads the kit makes, each a simulation: no key, no transaction. rpcRegistry() is the real one; tests pass a fake. */
+export interface RegistryReader {
+    readonly network: StellarNetwork;
+    /** The contract ids, for the invocations the CLI hands to the Stellar CLI. */
+    readonly contracts: {
+        identity: string;
+        validation: string;
+    };
+    /** The agent's registration URI, or undefined when the agent doesn't exist. */
+    agentUri(agentId: number): Promise<string | undefined>;
+    /** The agent's wallet, or undefined when none is set. */
+    agentWallet(agentId: number): Promise<string | undefined>;
+    /** The agent's owner, or undefined when the agent doesn't exist. */
+    agentOwner(agentId: number): Promise<string | undefined>;
+    /** The one address the owner approved for the agent, if any. */
+    agentApproved(agentId: number): Promise<string | undefined>;
+    /** Whether the owner made `operator` an operator of all its agents. */
+    isOperator(owner: string, operator: string): Promise<boolean>;
+    /** The validation request with this hash (64 hex characters), or undefined when there is none. */
+    validation(requestHash: string): Promise<ValidationRecord | undefined>;
+    /** The agent's validation requests, newest last: each one's hash and record, at most AGENT_VALIDATIONS_READ. */
+    agentValidations(agentId: number): Promise<(ValidationRecord & {
+        requestHash: string;
+    })[]>;
+}
+/** The most validation requests agentValidations() reads for one agent. */
+export declare const AGENT_VALIDATIONS_READ = 100;
+export declare function rpcRegistry(network: StellarNetwork, rpcUrl?: string): RegistryReader;
+/**
+ * The registries' rule for who may act for an agent, by changing its registration (set_agent_uri) or asking
+ * for its validation (validation_request): its owner, the address approved for it, or an operator of the owner's.
+ */
+export declare function mayActFor(registry: RegistryReader, agentId: number, owner: string, address: string): Promise<boolean>;
+export interface RegistrationFinding {
+    rule: "I1" | "I2" | "I3";
+    ok: boolean;
+    message: string;
+}
+/**
+ * Checks the provider's 8004 registration against its manifest (I1–I3), reading the identity registry
+ * over RPC. Without provider.agentId there is nothing on chain to check, which is an I2 finding.
+ */
+export declare function checkRegistration(manifest: ProviderManifest, manifestUrl: string, options?: {
+    rpcUrl?: string;
+    fetch?: typeof fetch;
+    registry?: RegistryReader;
+}): Promise<RegistrationFinding[]>;
+/** checkRegistration(), and the registration file it read: undefined when there is none, or it can't be read. */
+export declare function inspectRegistration(manifest: ProviderManifest, manifestUrl: string, options?: {
+    rpcUrl?: string;
+    fetch?: typeof fetch;
+    registry?: RegistryReader;
+}): Promise<{
+    findings: RegistrationFinding[];
+    file?: Record<string, unknown>;
+}>;
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"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"}

package/dist/registration.js

@@ -0,0 +1,162 @@
+// Stellar 8004 identity for the provider (docs/provider-standard.md §7).
+//
+// - registrationFile(): the ERC-8004 registration file that names the manifest [I1], built with the
+//   @trionlabs/stellar8004 helpers. `provider-kit register` puts it on chain.
+// - checkRegistration(): reads the registry (no key needed) and checks I1–I3: the registration names
+//   this manifest, the manifest names the agent, and the agent's wallet is the manifest's payTo.
+//   inspectRegistration() also returns the registration file it read, which is what search shows.
+// - rpcRegistry(): the identity and validation registry reads, which tests replace with a fake.
+// - mayActFor(): who may change an agent's registration or ask for its validation.
+// Nothing here signs. Registering is an owner action: the CLI has the owner's wallet sign it on a local
+// approval page, or hands it to the Stellar CLI keychain (--source).
+import { buildMetadataJson, IdentityClient, MAINNET_CONFIG, TESTNET_CONFIG, toDataUri, ValidationClient } from "@trionlabs/stellar8004";
+/** The registration's service entry that points to the manifest [I1]. */
+export const REGISTRATION_SERVICE_NAME = "stellar-agent-services";
+/** The 8004 registration file for a provider whose manifest is served at `manifestUrl` [I1]. */
+export function registrationFile(manifest, manifestUrl, options = {}) {
+    return buildMetadataJson({
+        name: manifest.provider.name,
+        description: manifest.provider.description ?? "",
+        imageUrl: options.image ?? "",
+        services: [
+            { name: REGISTRATION_SERVICE_NAME, endpoint: manifestUrl, version: "1" },
+            { name: "web", endpoint: manifest.baseUrl },
+        ],
+        supportedTrust: options.supportedTrust ?? [],
+        x402Enabled: true,
+    });
+}
+/** The file as a data: URI, which the registry stores on chain. Throws above 8 KiB: host the file and register its URL instead. */
+export function registrationDataUri(file) {
+    return toDataUri(file);
+}
+/** The 8004 contracts and RPC for a network. */
+export function registryConfig(network) {
+    return network === "stellar:pubnet" ? MAINNET_CONFIG : TESTNET_CONFIG;
+}
+/** The most validation requests agentValidations() reads for one agent. */
+export const AGENT_VALIDATIONS_READ = 100;
+export function rpcRegistry(network, rpcUrl) {
+    const config = registryConfig(network);
+    const options = { networkPassphrase: config.networkPassphrase, rpcUrl: rpcUrl ?? config.rpcUrl };
+    const identity = new IdentityClient({ ...options, contractId: config.contracts.identity });
+    const validation = new ValidationClient({ ...options, contractId: config.contracts.validation });
+    return {
+        network,
+        contracts: { identity: config.contracts.identity, validation: config.contracts.validation },
+        async agentUri(agentId) {
+            const result = (await identity.agent_uri({ agent_id: agentId })).result;
+            return result.isOk() ? result.unwrap() : undefined;
+        },
+        async agentWallet(agentId) {
+            return (await identity.get_agent_wallet({ agent_id: agentId })).result ?? undefined;
+        },
+        async agentOwner(agentId) {
+            return (await identity.find_owner({ agent_id: agentId })).result ?? undefined;
+        },
+        async agentApproved(agentId) {
+            return (await identity.get_approved({ token_id: agentId })).result ?? undefined;
+        },
+        async isOperator(owner, operator) {
+            return (await identity.is_approved_for_all({ owner, operator })).result;
+        },
+        validation: readValidation,
+        async agentValidations(agentId) {
+            const hashes = [];
+            const page = 25;
+            while (hashes.length < AGENT_VALIDATIONS_READ) {
+                const found = (await validation.get_agent_validations_paginated({ agent_id: agentId, start: hashes.length, limit: page })).result;
+                hashes.push(...found.map((hash) => Buffer.from(hash).toString("hex")));
+                if (found.length < page)
+                    break;
+            }
+            const records = await Promise.all(hashes.slice(0, AGENT_VALIDATIONS_READ).map(async (requestHash) => ({ requestHash, record: await readValidation(requestHash) })));
+            return records.flatMap(({ requestHash, record }) => (record === undefined ? [] : [{ ...record, requestHash }]));
+        },
+    };
+    async function readValidation(requestHash) {
+        const result = (await validation.get_validation_status({ request_hash: Buffer.from(requestHash, "hex") })).result;
+        if (!result.isOk())
+            return undefined;
+        const status = result.unwrap();
+        return {
+            validator: status.validator_address,
+            agentId: status.agent_id,
+            hasResponse: status.has_response,
+            response: status.response,
+            responseHash: Buffer.from(status.response_hash).toString("hex"),
+            tag: status.tag,
+            lastUpdate: Number(status.last_update),
+        };
+    }
+}
+/**
+ * The registries' rule for who may act for an agent, by changing its registration (set_agent_uri) or asking
+ * for its validation (validation_request): its owner, the address approved for it, or an operator of the owner's.
+ */
+export async function mayActFor(registry, agentId, owner, address) {
+    if (address === owner)
+        return true;
+    if ((await registry.agentApproved(agentId)) === address)
+        return true;
+    return registry.isOperator(owner, address);
+}
+/**
+ * Checks the provider's 8004 registration against its manifest (I1–I3), reading the identity registry
+ * over RPC. Without provider.agentId there is nothing on chain to check, which is an I2 finding.
+ */
+export async function checkRegistration(manifest, manifestUrl, options = {}) {
+    return (await inspectRegistration(manifest, manifestUrl, options)).findings;
+}
+/** checkRegistration(), and the registration file it read: undefined when there is none, or it can't be read. */
+export async function inspectRegistration(manifest, manifestUrl, options = {}) {
+    const agentId = manifest.provider.agentId;
+    if (agentId === undefined) {
+        return { findings: [{ rule: "I2", ok: false, message: "provider.agentId is not set: `provider-kit launch` registers the provider and saves its agent id" }] };
+    }
+    const network = manifest.payment.accepts[0].network;
+    const registry = options.registry ?? rpcRegistry(network, options.rpcUrl);
+    const uri = await registry.agentUri(agentId);
+    if (uri === undefined)
+        return { findings: [{ rule: "I2", ok: false, message: `agent ${agentId} does not exist in the ${network} identity registry` }] };
+    const findings = [{ rule: "I2", ok: true, message: `agent ${agentId} is registered on ${network}` }];
+    const file = await readRegistration(uri, options.fetch ?? fetch);
+    const services = Array.isArray(file?.["services"]) ? file["services"] : [];
+    const listed = services.some((service) => service.name === REGISTRATION_SERVICE_NAME && service.endpoint === manifestUrl);
+    findings.push(file === undefined
+        ? { rule: "I1", ok: false, message: "the registration file can't be read from the agent URI" }
+        : listed
+            ? { rule: "I1", ok: true, message: "the registration file lists this manifest" }
+            : { rule: "I1", ok: false, message: `the registration file does not list { name: "${REGISTRATION_SERVICE_NAME}", endpoint: "${manifestUrl}" }` });
+    const wallet = await registry.agentWallet(agentId);
+    const payTo = manifest.payment.accepts[0].payTo;
+    findings.push(wallet === payTo
+        ? { rule: "I3", ok: true, message: "the agent wallet is the manifest's payTo" }
+        : { rule: "I3", ok: false, message: `the agent wallet is ${wallet ?? "not set"}, but payTo is ${payTo}` });
+    return file === undefined ? { findings } : { findings, file };
+}
+/** A registration file from a data: or https: agent URI. Undefined if it can't be read. */
+async function readRegistration(uri, fetcher) {
+    try {
+        let text;
+        const data = /^data:application\/json(;base64)?,(.*)$/s.exec(uri);
+        if (data !== null) {
+            text = data[1] === undefined ? decodeURIComponent(data[2]) : Buffer.from(data[2], "base64").toString("utf8");
+        }
+        else if (uri.startsWith("https://")) {
+            const response = await fetcher(uri, { redirect: "error", signal: AbortSignal.timeout(15_000) });
+            if (!response.ok)
+                return undefined;
+            text = await response.text();
+        }
+        else {
+            return undefined;
+        }
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,13 @@
+import { Keypair } from "@stellar/stellar-sdk";
+import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
+export interface TestPaymentOptions {
+    /** The auth-entry nonce. Default: random. Two payments with the same payer and nonce are one payment. */
+    nonce?: bigint;
+    /** The last ledger the signature is valid for. Default 1,000,000 (fixtures use fixed values). */
+    expirationLedger?: number;
+    /** Pay this instead of what the requirements ask, to test refusals. */
+    override?: Partial<Pick<PaymentRequirements, "amount" | "payTo" | "asset">>;
+}
+/** A signed x402 v2 `exact` payment for the requirements, from `payer`. */
+export declare function signTestPayment(requirements: PaymentRequirements, payer: Keypair, options?: TestPaymentOptions): Promise<PaymentPayload>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAUA,OAAO,EAAoC,OAAO,EAAgF,MAAM,sBAAsB,CAAC;AAC/J,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAK5E,MAAM,WAAW,kBAAkB;IACjC,yGAAyG;IACzG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAC7E;AAED,2EAA2E;AAC3E,wBAAsB,eAAe,CACnC,YAAY,EAAE,mBAAmB,EACjC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAiCzB"}

package/dist/testing.js

@@ -0,0 +1,48 @@
+// Test helpers for providers and clients: real x402 `exact` payments, signed offline.
+//
+//   import { signTestPayment } from "@stellar-agent-services/provider-kit/testing";
+//
+// The payment is the same transaction the x402 client builds (one SAC transfer authorized by the
+// payer's signed auth entry), without the RPC round trips, so the provider's local payment checks run
+// on it unchanged. Nothing here touches the network; pair it with a fake facilitator.
+import { randomBytes } from "node:crypto";
+import { Account, Address, authorizeEntry, Keypair, nativeToScVal, Networks, Operation, TimeoutInfinite, TransactionBuilder, xdr } from "@stellar/stellar-sdk";
+/** The all-zero account the x402 client uses as transaction source; the facilitator rebuilds the transaction. */
+const NULL_ACCOUNT = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
+/** A signed x402 v2 `exact` payment for the requirements, from `payer`. */
+export async function signTestPayment(requirements, payer, options = {}) {
+    const passphrase = requirements.network === "stellar:pubnet" ? Networks.PUBLIC : Networks.TESTNET;
+    const paid = { ...requirements, ...options.override };
+    const call = new xdr.InvokeContractArgs({
+        contractAddress: Address.fromString(paid.asset).toScAddress(),
+        functionName: "transfer",
+        args: [
+            nativeToScVal(payer.publicKey(), { type: "address" }),
+            nativeToScVal(paid.payTo, { type: "address" }),
+            nativeToScVal(BigInt(paid.amount), { type: "i128" }),
+        ],
+    });
+    const unsigned = new xdr.SorobanAuthorizationEntry({
+        credentials: xdr.SorobanCredentials.sorobanCredentialsAddress(new xdr.SorobanAddressCredentials({
+            address: Address.fromString(payer.publicKey()).toScAddress(),
+            nonce: xdr.Int64.fromString((options.nonce ?? randomNonce()).toString()),
+            signatureExpirationLedger: 0,
+            signature: xdr.ScVal.scvVoid(),
+        })),
+        rootInvocation: new xdr.SorobanAuthorizedInvocation({
+            function: xdr.SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(call),
+            subInvocations: [],
+        }),
+    });
+    const signed = await authorizeEntry(unsigned, payer, options.expirationLedger ?? 1_000_000, passphrase);
+    const transaction = new TransactionBuilder(new Account(NULL_ACCOUNT, "0"), { fee: "100", networkPassphrase: passphrase })
+        .addOperation(Operation.invokeHostFunction({ func: xdr.HostFunction.hostFunctionTypeInvokeContract(call), auth: [signed] }))
+        // No wall-clock timebounds, so fixtures never expire.
+        .setTimeout(TimeoutInfinite)
+        .build();
+    return { x402Version: 2, accepted: requirements, payload: { transaction: transaction.toXDR() } };
+}
+function randomNonce() {
+    return randomBytes(8).readBigInt64BE() & 0x7fffffffffffffffn;
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,oFAAoF;AACpF,EAAE;AACF,iGAAiG;AACjG,sGAAsG;AACtG,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAG/J,iHAAiH;AACjH,MAAM,YAAY,GAAG,0DAA0D,CAAC;AAWhF,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,YAAiC,EACjC,KAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,KAAM,gBAA0C,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IAC7H,MAAM,IAAI,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,kBAAkB,CAAC;QACtC,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;QAC7D,YAAY,EAAE,UAAU;QACxB,IAAI,EAAE;YACJ,aAAa,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YACrD,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC9C,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACrD;KACF,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,yBAAyB,CAAC;QACjD,WAAW,EAAE,GAAG,CAAC,kBAAkB,CAAC,yBAAyB,CAC3D,IAAI,GAAG,CAAC,yBAAyB,CAAC;YAChC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,WAAW,EAAE;YAC5D,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,WAAW,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;YACxE,yBAAyB,EAAE,CAAC;YAC5B,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;SAC/B,CAAC,CACH;QACD,cAAc,EAAE,IAAI,GAAG,CAAC,2BAA2B,CAAC;YAClD,QAAQ,EAAE,GAAG,CAAC,yBAAyB,CAAC,uCAAuC,CAAC,IAAI,CAAC;YACrF,cAAc,EAAE,EAAE;SACnB,CAAC;KACH,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,gBAAgB,IAAI,SAAS,EAAE,UAAU,CAAC,CAAC;IACxG,MAAM,WAAW,GAAG,IAAI,kBAAkB,CAAC,IAAI,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,CAAC;SACtH,YAAY,CAAC,SAAS,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,8BAA8B,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5H,sDAAsD;SACrD,UAAU,CAAC,eAAe,CAAC;SAC3B,KAAK,EAAE,CAAC;IACX,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC;AACnG,CAAC;AAED,SAAS,WAAW;IAClB,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,GAAG,mBAAmB,CAAC;AAC/D,CAAC"}

package/dist/validation-request.d.ts

@@ -0,0 +1,36 @@
+import { type ProviderManifest, type ValidationRequest } from "@stellar-agent-services/protocol";
+import { type RegistryReader } from "./registration.js";
+/** One validation_request, checked and ready to sign. */
+export interface PreparedValidationRequest {
+    request: ValidationRequest;
+    /** sha256 of the request's canonical bytes, 64 hex characters: the on-chain request_hash. */
+    requestHash: string;
+    /** A data: URI holding exactly those bytes. */
+    requestUri: string;
+    /** The Validation Registry contract. */
+    contractId: string;
+}
+export declare class ValidationRequestError extends Error {
+    readonly problems: string[];
+    name: string;
+    constructor(problems: string[]);
+}
+export interface ValidationRequestOptions {
+    /** The verifier's G... account: the only one that may answer. */
+    validator: string;
+    /** The account that will sign, when it is known. Without it, who may ask is left to the registry. */
+    signer?: string;
+    registry: RegistryReader;
+    /** For a registration file at an https: agent URI. */
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+/** Checks everything a validation_request depends on, then builds it. Throws a ValidationRequestError listing every problem. */
+export declare function prepareValidationRequest(manifest: ProviderManifest, manifestUrl: string, options: ValidationRequestOptions): Promise<PreparedValidationRequest>;
+/** The arguments of `stellar` that send the request: a contract invocation of validation_request. `caller` is the --source key's address. */
+export declare function validationRequestArguments(prepared: PreparedValidationRequest, options: {
+    source: string;
+    network: string;
+    caller: string;
+}): string[];
+//# sourceMappingURL=validation-request.d.ts.map

package/dist/validation-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-request.d.ts","sourceRoot":"","sources":["../src/validation-request.ts"],"names":[],"mappings":"AAeA,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEtF,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAEnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE;IAD9B,IAAI,SAA4B;gBACpB,QAAQ,EAAE,MAAM,EAAE;CAGxC;AAED,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,CAAC;IACzB,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,gIAAgI;AAChI,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,yBAAyB,CAAC,CA0CpC;AAED,6IAA6I;AAC7I,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,yBAAyB,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAuBtJ"}