@sorandomains/owner 0.8.0 → 0.9.0

package/README.md

@@ -1,14 +1,14 @@
 # @sorandomains/owner
 
 
-> Native claim testnet deployment verified at ledger 4534629 on 6 September 2026 (12:12 UTC). See the
+> Governed testnet migration sealed at ledger 4604192 on 10 September 2026. See the
 > [release status](https://docs.soran.domains/reference/release-status) for package and service availability.
 
 
 Version 0.8.0 targets Stellar SDK17 (`>=17 <18`). ASCII names
 and labels are validated before lowercase normalization; Unicode lookalikes are
 rejected. Writes continue to target the owning Registry/Registrar/Resolver. Universal
-Lookup is the read entry point in `@sorandomains/lookup` 0.8.0.
+Lookup is the read entry point in `@sorandomains/lookup` 0.10.0.
 
 Ownership, issuer, holder and treasury inputs remain G/C account or contract
 addresses. Muxed M addresses are payment destinations only: issue the name to its
@@ -91,11 +91,11 @@ Read the [native claim APIs, security boundaries and complete signup flow](https
 
 ## Verified testnet deployment
 
-Verified on 6 September 2026 at ledger **4534629** (12:12 UTC). Network passphrase: `Test SDF Network ; September 2015`.
+See the [deployment manifest](../../deployments/testnet.json) for confirmed code hashes, transaction receipts and verification scope. Network passphrase: `Test SDF Network ; September 2015`.
 
 | Contract | Address |
 |---|---|
-| Registry | `CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK` |
+| Registry | `CCSORANDPQINYOYB5SVO45WJP2LBBYKC72HHUIRVXB4J6RUZKDAUW7G4` |
 
 Mainnet has no deployment preset. Custom networks must supply their own verified
 addresses. Universal Lookup upgrades remain immediately executable; an address
@@ -121,3 +121,22 @@ The older `maxNativeFeeStroops` option remains supported: when the new option is
 On a governed Registry, native verification reads the exact per-namespace Registrar code pin and its upgrade history. Approved upgrades do not have to match the current factory default. Missing or malformed provenance still prevents signing and receipt confirmation; RPC failure never downgrades verification to a legacy rule.
 
 Historical claim recovery is read-only and binds the original intent to the frozen source Registrar and sealed migration commitments. It never rewrites the intent to a successor Registry or treats an unavailable receipt as permission to submit again. Deployment migration and package publication are separate; check the release status for the active addresses.
+
+
+## Namespace sponsorship
+
+This package supports on-chain funding and sponsored actions on Stellar testnet.
+`SoranFunding` manages an owner's deposit, spending limits, pause controls and withdrawals.
+`SoranSponsorship` builds and checks an exact sponsored action, while `FundingServiceClient`
+requests quotes and recovers transaction outcomes from a compatible service.
+
+The Soran service uses fixed quotes based on live Stellar fee estimates. A successful action
+charges the agreed amount; Soran retains any difference from the actual network fee.
+There is no separate refund transaction or later debit. Failed actions do not debit the
+namespace's funding position. A separate username price remains payable by the claimant.
+
+User authorization remains required. A wallet must support Soroban authorization-entry
+signing; a transaction-only wallet cannot silently switch to a user-paid transaction.
+Always preserve the canonical quote before submission and recover its status after a timeout.
+Funding balances and permissions are verified on chain, and terminal outcomes are checked
+against trusted Stellar RPC/history providers.

package/dist/funding-history.d.ts

@@ -0,0 +1,25 @@
+import { rpc } from "@stellar/stellar-sdk";
+import { type SponsorQuote } from "./funding-types.js";
+/** Receipt evidence is retained for audit; its bytes alone are not a chain-inclusion proof. */
+export type FundingReceipt = {
+    transactionHash: string;
+    envelopeHash: string;
+    envelopeXdr: string;
+    resultXdr: string;
+    ledger: number;
+    observedLedger: number;
+    status: "success" | "failed";
+    provider: "stellar-rpc" | "sdf-testnet-horizon";
+};
+export interface SponsorHistory {
+    find(hash: string, quote: SponsorQuote, latestLedger: number, passphrase: string): Promise<FundingReceipt | null>;
+}
+/** Input must come from the caller's trusted chain provider, never a pasted/API receipt. */
+export declare function verifySponsorHistory(value: unknown, quote: SponsorQuote, expectedHash: string, latestLedger: number, passphrase: string, provider?: FundingReceipt["provider"]): FundingReceipt | null;
+export declare function sponsorRpcReceipt(result: rpc.Api.GetSuccessfulTransactionResponse | rpc.Api.GetFailedTransactionResponse, quote: SponsorQuote, hash: string, passphrase: string): FundingReceipt;
+/** The fixed provider is trusted for canonical inclusion, just as Stellar RPC is. */
+export declare class TestnetSponsorHistory implements SponsorHistory {
+    private request;
+    constructor(request?: typeof fetch);
+    find(hash: string, quote: SponsorQuote, latestLedger: number, passphrase: string): Promise<FundingReceipt | null>;
+}

package/dist/funding-history.js

@@ -0,0 +1,124 @@
+import { Address, FeeBumpTransaction, Networks, Transaction, TransactionBuilder, xdr, hash, } from "@stellar/stellar-sdk";
+import { hex } from "./native-codec.js";
+import { FundingError, sponsorQuoteToScVal, } from "./funding-types.js";
+/** Input must come from the caller's trusted chain provider, never a pasted/API receipt. */
+export function verifySponsorHistory(value, quote, expectedHash, latestLedger, passphrase, provider = "sdf-testnet-horizon") {
+    const r = value;
+    if (passphrase !== Networks.TESTNET ||
+        quote.network !== hex(hash(new TextEncoder().encode(passphrase))) ||
+        !/^[a-f0-9]{64}$/.test(expectedHash) ||
+        !Number.isInteger(latestLedger) ||
+        latestLedger < 1 ||
+        latestLedger > 0xffff_ffff ||
+        !r ||
+        typeof r !== "object" ||
+        typeof r.hash !== "string" ||
+        !Number.isInteger(r.ledger) ||
+        r.ledger < quote.issuedLedger ||
+        r.ledger > latestLedger ||
+        typeof r.successful !== "boolean" ||
+        typeof r.envelope_xdr !== "string" ||
+        r.envelope_xdr.length > 200000 ||
+        typeof r.result_xdr !== "string" ||
+        r.result_xdr.length > 200000)
+        return null;
+    try {
+        const envelope = TransactionBuilder.fromXDR(r.envelope_xdr, passphrase);
+        const tx = envelope instanceof FeeBumpTransaction
+            ? envelope.innerTransaction
+            : envelope;
+        if (!(tx instanceof Transaction) ||
+            hex(envelope.hash()) !== r.hash ||
+            hex(tx.hash()) !== expectedHash)
+            return null;
+        const op = tx.operations[0];
+        if (tx.source !== quote.relayer ||
+            tx.operations.length !== 1 ||
+            op.type !== "invokeHostFunction" ||
+            (op.source && op.source !== quote.relayer) ||
+            op.func.type !== "hostFunctionTypeInvokeContract" ||
+            Address.fromScAddress(op.func.invokeContract.contractAddress).toString() !== quote.funding ||
+            op.func.invokeContract.functionName.toString() !==
+                "sponsor_" + quote.action ||
+            op.func.invokeContract.args[0]?.toXDR("base64") !==
+                sponsorQuoteToScVal(quote).toXDR("base64"))
+            return null;
+        const result = xdr.TransactionResult.fromXDR(r.result_xdr, "base64").result;
+        let outcome;
+        if (envelope instanceof FeeBumpTransaction) {
+            if (result.type !== "txFeeBumpInnerSuccess" &&
+                result.type !== "txFeeBumpInnerFailed")
+                return null;
+            if (hex(result.innerResultPair.transactionHash.value) !== expectedHash)
+                return null;
+            outcome = result.innerResultPair.result.result.type;
+            if ((result.type === "txFeeBumpInnerSuccess") !==
+                (outcome === "txSuccess"))
+                return null;
+        }
+        else
+            outcome = result.type;
+        if (!["txSuccess", "txFailed"].includes(outcome) ||
+            r.successful !== (outcome === "txSuccess"))
+            return null;
+        return {
+            transactionHash: expectedHash,
+            envelopeHash: r.hash,
+            envelopeXdr: r.envelope_xdr,
+            resultXdr: r.result_xdr,
+            ledger: r.ledger,
+            observedLedger: latestLedger,
+            status: r.successful ? "success" : "failed",
+            provider,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function sponsorRpcReceipt(result, quote, hash, passphrase) {
+    try {
+        const envelope = TransactionBuilder.fromXDR(result.envelopeXdr, passphrase);
+        if (![hash, hex(envelope.hash())].includes(result.txHash))
+            throw Error();
+        const receipt = verifySponsorHistory({
+            hash: hex(envelope.hash()),
+            ledger: result.ledger,
+            successful: result.status === "SUCCESS",
+            envelope_xdr: envelope.toXDR(),
+            result_xdr: result.resultXdr.toXDR("base64"),
+        }, quote, hash, result.latestLedger, passphrase, "stellar-rpc");
+        if (receipt)
+            return receipt;
+    }
+    catch {
+        /* malformed or unrelated terminal data stays uncertain */
+    }
+    throw new FundingError("Receipt does not prove the reviewed sponsorship transaction", "pending", hash);
+}
+/** The fixed provider is trusted for canonical inclusion, just as Stellar RPC is. */
+export class TestnetSponsorHistory {
+    request;
+    constructor(request = (input, init) => globalThis.fetch(input, init)) {
+        this.request = request;
+    }
+    async find(hash, quote, latestLedger, passphrase) {
+        if (passphrase !== Networks.TESTNET || !/^[a-f0-9]{64}$/.test(hash))
+            throw new FundingError("Invalid sponsorship history request", "unavailable");
+        const options = {
+            credentials: "omit",
+            redirect: "error",
+            cache: "no-store",
+            signal: AbortSignal.timeout(10000),
+        };
+        const response = await this.request(`https://horizon-testnet.stellar.org/transactions/${hash}`, options);
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            throw new FundingError("Sponsorship history unavailable; preserve the quote reference", "unavailable");
+        const body = await response.text();
+        if (body.length > 600000)
+            throw new FundingError("Sponsorship history response is too large", "unavailable");
+        return verifySponsorHistory(JSON.parse(body), quote, hash, latestLedger, passphrase);
+    }
+}

package/dist/funding-owner.d.ts

@@ -0,0 +1,45 @@
+import { FundingReader, type FundingOptions } from "./funding-reader.js";
+import { type SponsorPolicy } from "./funding-types.js";
+import { type NativeSigner, type NativeWriteOptions } from "./native-transport.js";
+/** Direct owner operations work even when the sponsorship service is offline. */
+export declare class SoranFunding extends FundingReader {
+    private context;
+    private tail;
+    constructor(options: FundingOptions & {
+        signer: NativeSigner;
+        maxNetworkFeeStroops: bigint;
+    });
+    private serialize;
+    private write;
+    open(namespace: string, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+    private controller;
+    deposit(id: string, amount: bigint, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+    setPolicy(id: string, policy: SponsorPolicy, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+    setPaused(id: string, paused: boolean, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+    withdraw(id: string, amount: bigint, recipient: string, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+    close(id: string, options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        value: unknown;
+    }>;
+}

package/dist/funding-owner.js

@@ -0,0 +1,97 @@
+import { Asset } from "@stellar/stellar-sdk";
+import { FundingReader } from "./funding-reader.js";
+import { FundingError, sponsorPolicyToScVal, } from "./funding-types.js";
+import { address, namespaceNode, sc, unhex } from "./native-codec.js";
+import { sendNative, } from "./native-transport.js";
+/** Direct owner operations work even when the sponsorship service is offline. */
+export class SoranFunding extends FundingReader {
+    context;
+    tail = Promise.resolve();
+    constructor(options) {
+        super(options);
+        if (options.maxNetworkFeeStroops <= 0n)
+            throw new FundingError("Choose a positive network fee limit");
+        const context = {
+            registryId: this.registryId,
+            passphrase: this.passphrase,
+            server: this.server,
+            signer: options.signer,
+            fee: "100",
+            timeoutSecs: 60,
+            maxFeeStroops: options.maxNetworkFeeStroops,
+            read: async (c, m, a) => (await this.read(c, m, a)).value,
+            readWithLedger: (c, m, a) => this.read(c, m, a),
+            serialize: (work) => this.serialize(work),
+        };
+        this.context = context;
+    }
+    serialize(work) {
+        const next = this.tail.then(work, work);
+        this.tail = next.catch(() => undefined);
+        return next;
+    }
+    async write(method, args, controller, options, children = []) {
+        const source = address(await this.context.signer.publicKey(), "account", "owner wallet");
+        if (source !== controller)
+            throw new FundingError("Connect the funding position's controller wallet", "authorization");
+        await this.configuration();
+        return this.serialize(() => sendNative(this.context, {
+            source,
+            contract: this.fundingId,
+            method,
+            args,
+            sourceInvocation: {
+                contract: this.fundingId,
+                method,
+                args,
+                children,
+            },
+            maxFeeStroops: this.context.maxFeeStroops,
+        }, options));
+    }
+    async open(namespace, options = {}) {
+        const node = sc.bytes(namespaceNode(namespace));
+        const owner = address((await this.read(this.registryId, "owner_of", [node])).value, "identity", "namespace owner");
+        return this.write("open_fund", [node], owner, options);
+    }
+    async controller(id) {
+        const f = await this.position(id);
+        if (!f)
+            throw new FundingError("Funding position does not exist");
+        return f.controller;
+    }
+    async deposit(id, amount, options = {}) {
+        if (amount <= 0n)
+            throw new FundingError("Deposit must be positive");
+        const controller = await this.controller(id);
+        return this.write("deposit", [sc.bytes(unhex(id)), sc.i128(amount)], controller, options, [
+            {
+                contract: Asset.native().contractId(this.passphrase),
+                method: "transfer",
+                args: [
+                    sc.address(controller),
+                    sc.address(this.fundingId),
+                    sc.i128(amount),
+                ],
+            },
+        ]);
+    }
+    async setPolicy(id, policy, options = {}) {
+        return this.write("set_policy", [sc.bytes(unhex(id)), sponsorPolicyToScVal(policy)], await this.controller(id), options);
+    }
+    async setPaused(id, paused, options = {}) {
+        return this.write("set_paused", [sc.bytes(unhex(id)), sc.bool(paused)], await this.controller(id), options);
+    }
+    async withdraw(id, amount, recipient, options = {}) {
+        if (amount <= 0n || recipient === this.fundingId)
+            throw new FundingError("Invalid withdrawal");
+        return this.write("withdraw", [
+            sc.bytes(unhex(id)),
+            sc.i128(amount),
+            sc.address(address(recipient, "identity", "withdrawal recipient")),
+        ], await this.controller(id), options);
+    }
+    async close(id, options = {}) {
+        return this.write("close_fund", [sc.bytes(unhex(id))], await this.controller(id), options);
+    }
+}

package/dist/funding-reader.d.ts

@@ -0,0 +1,43 @@
+import { rpc, xdr } from "@stellar/stellar-sdk";
+import { type SponsorQuote } from "./funding-types.js";
+export type FundingOptions = {
+    fundingId: string;
+    registryId: string;
+    lookupId: string;
+    primaryId: string;
+    rpcUrl?: string;
+    networkPassphrase?: string;
+    server?: rpc.Server;
+};
+export declare class FundingReader {
+    readonly fundingId: string;
+    readonly registryId: string;
+    readonly lookupId: string;
+    readonly primaryId: string;
+    readonly passphrase: string;
+    readonly server: rpc.Server;
+    readonly networkId: string;
+    constructor(options: FundingOptions);
+    read(contract: string, method: string, args: xdr.ScVal[], minimumLedger?: number): Promise<{
+        value: unknown;
+        ledger: number;
+    }>;
+    configuration(): Promise<{
+        ledger: number;
+        registry: string;
+        nativeAsset: string;
+        lookup: string;
+        primary: string;
+        governance: string;
+        paused: boolean;
+        revision: bigint;
+    }>;
+    currentPosition(namespace: string): Promise<{
+        id: string;
+        position: import("./funding-types.js").FundingPosition | null;
+    }>;
+    position(id: string): Promise<import("./funding-types.js").FundingPosition | null>;
+    policy(id: string): Promise<import("./funding-types.js").SponsorPolicy | null>;
+    actorState(id: string, actor: string): Promise<import("./funding-types.js").SponsorActorState>;
+    validateQuote(quote: SponsorQuote): Promise<void>;
+}

package/dist/funding-reader.js

@@ -0,0 +1,98 @@
+import { Account, Asset, Contract, Networks, StrKey, TransactionBuilder, hash, rpc, scValToNative, } from "@stellar/stellar-sdk";
+import { address, hex, namespaceNode, sc, unhex, utf8, } from "./native-codec.js";
+import { FundingError, fundingConfigurationFromNative, fundingPositionFromNative, fundingPositionId, sponsorActorFromNative, sponsorPolicyFromNative, sponsorQuoteToScVal, } from "./funding-types.js";
+export class FundingReader {
+    fundingId;
+    registryId;
+    lookupId;
+    primaryId;
+    passphrase;
+    server;
+    networkId;
+    constructor(options) {
+        this.fundingId = address(options.fundingId, "contract", "funding deployment");
+        this.registryId = address(options.registryId, "contract", "Registry");
+        this.lookupId = address(options.lookupId, "contract", "Lookup");
+        this.primaryId = address(options.primaryId, "contract", "Primary");
+        this.passphrase = options.networkPassphrase ?? Networks.TESTNET;
+        if (this.passphrase !== Networks.TESTNET)
+            throw new FundingError("Funding V1 is currently restricted to testnet");
+        this.networkId = hex(hash(utf8(this.passphrase)));
+        this.server =
+            options.server ??
+                new rpc.Server(options.rpcUrl ?? "https://soroban-testnet.stellar.org");
+    }
+    async read(contract, method, args, minimumLedger = 1) {
+        const source = new Account(StrKey.encodeEd25519PublicKey(new Uint8Array(32)), "0");
+        const tx = new TransactionBuilder(source, {
+            fee: "100",
+            networkPassphrase: this.passphrase,
+        })
+            .addOperation(new Contract(contract).call(method, ...args))
+            .setTimeout(30)
+            .build();
+        const result = await this.server.simulateTransaction(tx, undefined, undefined, false);
+        if (!rpc.Api.isSimulationSuccess(result) ||
+            !result.result ||
+            !Number.isSafeInteger(result.latestLedger) ||
+            result.latestLedger < minimumLedger)
+            throw new FundingError("Cannot verify funding contract state: " +
+                ("error" in result ? result.error : "missing or stale response"), "unavailable");
+        return {
+            value: scValToNative(result.result.retval),
+            ledger: result.latestLedger,
+        };
+    }
+    async configuration() {
+        const version = await this.read(this.fundingId, "version", []);
+        if (version.value !== 1)
+            throw new FundingError("Unsupported Funding contract version", "unavailable");
+        const r = await this.read(this.fundingId, "configuration", [], version.ledger);
+        const c = fundingConfigurationFromNative(r.value);
+        if (c.registry !== this.registryId ||
+            c.lookup !== this.lookupId ||
+            c.primary !== this.primaryId ||
+            c.nativeAsset !== Asset.native().contractId(this.passphrase))
+            throw new FundingError("Funding contract anchors differ from the configured deployment", "authorization");
+        return { ...c, ledger: r.ledger };
+    }
+    async currentPosition(namespace) {
+        await this.configuration();
+        const node = hex(namespaceNode(namespace));
+        const epoch = await this.read(this.registryId, "owner_epoch", [
+            sc.bytes(unhex(node)),
+        ]);
+        if (typeof epoch.value !== "bigint" || epoch.value < 1n)
+            throw new FundingError("Namespace ownership epoch unavailable", "unavailable");
+        const id = fundingPositionId(node, epoch.value);
+        return { id, position: await this.position(id) };
+    }
+    async position(id) {
+        const r = await this.read(this.fundingId, "fund", [sc.bytes(unhex(id))]);
+        if (r.value === null || r.value === undefined)
+            return null;
+        const position = fundingPositionFromNative(r.value);
+        if (fundingPositionId(position.namespace, position.ownerEpoch) !== id)
+            throw new FundingError("Returned funding position has a different namespace or ownership epoch", "unavailable");
+        return position;
+    }
+    async policy(id) {
+        const r = await this.read(this.fundingId, "policy", [sc.bytes(unhex(id))]);
+        return r.value === null || r.value === undefined
+            ? null
+            : sponsorPolicyFromNative(r.value);
+    }
+    async actorState(id, actor) {
+        const r = await this.read(this.fundingId, "actor_state", [
+            sc.bytes(unhex(id)),
+            sc.address(address(actor, "identity", "actor")),
+        ]);
+        return sponsorActorFromNative(r.value);
+    }
+    async validateQuote(quote) {
+        if (quote.funding !== this.fundingId || quote.network !== this.networkId)
+            throw new FundingError("Quote belongs to another deployment", "authorization");
+        await this.configuration();
+        await this.read(this.fundingId, "quote_status", [sponsorQuoteToScVal(quote)], quote.issuedLedger);
+    }
+}

package/dist/funding-service.d.ts

@@ -0,0 +1,33 @@
+import { type SponsorHistory } from "./funding-history.js";
+import { type ClaimIntent } from "./native-types.js";
+import { type SponsorQuote, type SponsoredAction, type SponsoredIdentityIntent } from "./funding-types.js";
+import { SoranSponsorship } from "./funding-user.js";
+/** HTTP transports offers and status. The contract/RPC checks still authorize spending. */
+export declare class FundingServiceClient {
+    private client;
+    private request;
+    private history;
+    private base;
+    constructor(baseUrl: string, client: SoranSponsorship, request?: typeof fetch, history?: SponsorHistory);
+    private call;
+    quote(action: SponsoredAction, intent: ClaimIntent | SponsoredIdentityIntent, maxSponsorCharge: bigint, proof?: readonly string[]): Promise<{
+        request: {
+            quote: SponsorQuote;
+            intent: ClaimIntent | SponsoredIdentityIntent;
+            proof: readonly string[];
+        };
+        transactionXdr: any;
+    }>;
+    submit(quote: SponsorQuote, authorizedTransactionXdr: string): Promise<{
+        id: string;
+        status: "quoted" | "dispatching" | "pending" | "unknown" | "success" | "failed" | "expired";
+        transactionHash: string | null;
+    }>;
+    status(quote: SponsorQuote): Promise<{
+        id: string;
+        status: "quoted" | "dispatching" | "pending" | "unknown" | "success" | "failed" | "expired";
+        transactionHash: string | null;
+    }>;
+    private id;
+    private result;
+}

package/dist/funding-service.js

@@ -0,0 +1,121 @@
+import { TestnetSponsorHistory, sponsorRpcReceipt, } from "./funding-history.js";
+import { claimIntentToScVal } from "./native-types.js";
+import { FundingError, decodeSponsorQuote, sponsoredIdentityToScVal, sponsorIntentHash, } from "./funding-types.js";
+/** HTTP transports offers and status. The contract/RPC checks still authorize spending. */
+export class FundingServiceClient {
+    client;
+    request;
+    history;
+    base;
+    constructor(baseUrl, client, request = (input, init) => globalThis.fetch(input, init), history = new TestnetSponsorHistory()) {
+        this.client = client;
+        this.request = request;
+        this.history = history;
+        const url = new URL(baseUrl);
+        if (url.username ||
+            url.password ||
+            url.hash ||
+            url.search ||
+            (url.protocol !== "https:" &&
+                !(url.protocol === "http:" &&
+                    ["localhost", "127.0.0.1"].includes(url.hostname))))
+            throw new FundingError("Sponsorship API must use HTTPS or a local development endpoint");
+        this.base = url.toString().replace(/\/$/, "");
+    }
+    async call(path, body) {
+        let r;
+        try {
+            r = await this.request(this.base + path, {
+                method: body === undefined ? "GET" : "POST",
+                headers: body === undefined
+                    ? undefined
+                    : { "content-type": "application/json" },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(30000),
+                redirect: "error",
+            });
+        }
+        catch {
+            throw new FundingError("Service response unavailable. Keep your quote reference and recover its status before submitting again.", "unavailable");
+        }
+        const value = (await r.json());
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new FundingError("Invalid service response", "unavailable");
+        if (!r.ok || value.error)
+            throw new FundingError(typeof value.detail === "string"
+                ? value.detail
+                : "Sponsorship request stopped", value.error === "pending" ? "pending" : "unavailable", typeof value.transactionHash === "string"
+                ? value.transactionHash
+                : null);
+        return value;
+    }
+    async quote(action, intent, maxSponsorCharge, proof = []) {
+        const encoded = action === "claim"
+            ? claimIntentToScVal(intent)
+            : sponsoredIdentityToScVal(intent);
+        const offer = await this.call("/v1/sponsorship/quote", {
+            action,
+            intentXdr: encoded.toXDR("base64"),
+            proof,
+        });
+        const quote = decodeSponsorQuote(offer.quoteXdr);
+        if (offer.id !== quote.quoteId ||
+            quote.action !== action ||
+            quote.intentHash !== sponsorIntentHash(action, intent) ||
+            quote.charge > maxSponsorCharge ||
+            typeof offer.transactionXdr !== "string" ||
+            offer.transactionXdr.length > 100000)
+            throw new FundingError("Sponsorship offer differs from the action or charge you reviewed", "authorization");
+        await this.client.validateQuote(quote);
+        return {
+            request: { quote, intent, proof },
+            transactionXdr: offer.transactionXdr,
+        };
+    }
+    async submit(quote, authorizedTransactionXdr) {
+        this.id(quote.quoteId);
+        const result = await this.call("/v1/sponsorship/submit", {
+            quoteId: quote.quoteId,
+            transactionXdr: authorizedTransactionXdr,
+        });
+        return this.result(quote, result);
+    }
+    async status(quote) {
+        this.id(quote.quoteId);
+        return this.result(quote, await this.call(`/v1/sponsorship/status/${quote.quoteId}`));
+    }
+    id(id) {
+        if (!/^[a-f0-9]{64}$/.test(id))
+            throw new FundingError("Invalid quote ID");
+    }
+    async result(quote, value) {
+        if (value.id !== quote.quoteId ||
+            quote.funding !== this.client.fundingId ||
+            quote.network !== this.client.networkId ||
+            ![
+                "quoted",
+                "dispatching",
+                "pending",
+                "unknown",
+                "success",
+                "failed",
+                "expired",
+            ].includes(value.status) ||
+            (value.transactionHash !== null &&
+                !/^[a-f0-9]{64}$/.test(value.transactionHash)))
+            throw new FundingError("Unverifiable sponsorship status; preserve the original quote reference", "unavailable");
+        if (value.status === "success" || value.status === "failed") {
+            if (!value.transactionHash)
+                throw new FundingError("Missing confirmed transaction hash", "unavailable");
+            const result = await this.client.server.getTransaction(value.transactionHash);
+            const receipt = result.status === "SUCCESS" || result.status === "FAILED"
+                ? sponsorRpcReceipt(result, quote, value.transactionHash, this.client.passphrase)
+                : await this.history.find(value.transactionHash, quote, (await this.client.server.getLatestLedger()).sequence, this.client.passphrase);
+            // Fetch independently from a trusted chain provider. API receipt bytes or
+            // a persisted status alone cannot establish canonical inclusion.
+            if (!receipt || receipt.status !== value.status)
+                throw new FundingError("Service outcome is not confirmed by chain history", "pending", value.transactionHash);
+        }
+        return value;
+    }
+}

package/dist/funding-types.d.ts

@@ -0,0 +1,102 @@
+import { xdr } from "@stellar/stellar-sdk";
+import { type PaymentDestination } from "./payment.js";
+import { type ClaimIntent } from "./native-types.js";
+export declare class FundingError extends Error {
+    readonly kind: "invalid" | "unavailable" | "authorization" | "pending" | "failed";
+    readonly transactionHash: string | null;
+    constructor(message: string, kind?: "invalid" | "unavailable" | "authorization" | "pending" | "failed", transactionHash?: string | null);
+}
+export type SponsoredAction = "claim" | "reverse" | "primary";
+export type FundingConfiguration = {
+    registry: string;
+    nativeAsset: string;
+    lookup: string;
+    primary: string;
+    governance: string;
+    paused: boolean;
+    revision: bigint;
+};
+export type FundingPosition = {
+    namespace: string;
+    ownerEpoch: bigint;
+    controller: string;
+    balance: bigint;
+    spentTotal: bigint;
+    utcDay: bigint;
+    spentToday: bigint;
+    policyRevision: bigint;
+    status: "paused" | "active" | "closed";
+};
+export type SponsorPolicy = {
+    claimCap: bigint;
+    reverseCap: bigint;
+    primaryCap: bigint;
+    dailyCap: bigint;
+    totalCap: bigint;
+    claimsPerWallet: bigint;
+    identityPerDay: number;
+    relayer: string;
+    quoteLifetime: number;
+    validUntil: bigint;
+};
+export type SponsorQuote = {
+    network: string;
+    funding: string;
+    configRevision: bigint;
+    fundId: string;
+    policyRevision: bigint;
+    action: SponsoredAction;
+    actor: string;
+    nonce: bigint;
+    quoteId: string;
+    intentHash: string;
+    registrar: string;
+    resolver: string;
+    relayer: string;
+    charge: bigint;
+    issuedLedger: number;
+    expiresLedger: number;
+};
+export type SponsoredIdentityIntent = {
+    name: string;
+    actor: string;
+    routingId: bigint | null;
+    generation: bigint;
+    destination: PaymentDestination;
+    previous: string | null;
+};
+export type SponsorReceipt = {
+    quoteId: string;
+    intentHash: string;
+    actor: string;
+    nonce: bigint;
+    action: SponsoredAction;
+    charge: bigint;
+    relayer: string;
+    balance: bigint;
+    ledger: number;
+};
+export type SponsorActorState = {
+    nonce: bigint;
+    claims: bigint;
+    utcDay: bigint;
+    identityToday: number;
+    lastReceipt: SponsorReceipt | null;
+};
+export declare const fundingConfigurationFromNative: (v: unknown) => FundingConfiguration;
+export declare const fundingPositionFromNative: (v: unknown) => FundingPosition;
+export declare const sponsorPolicyFromNative: (v: unknown) => SponsorPolicy;
+export declare const sponsorQuoteFromNative: (v: unknown) => SponsorQuote;
+export declare const sponsoredIdentityFromNative: (v: unknown) => SponsoredIdentityIntent;
+export declare const sponsorReceiptFromNative: (v: unknown) => SponsorReceipt;
+export declare const sponsorActorFromNative: (v: unknown) => SponsorActorState;
+export declare const sponsoredActionToScVal: (v: SponsoredAction) => xdr.ScVal;
+export declare function sponsorPolicyToScVal(v: SponsorPolicy): xdr.ScVal;
+export declare function sponsorQuoteToScVal(v: SponsorQuote): xdr.ScVal;
+export declare const sponsoredIdentityToScVal: (v: SponsoredIdentityIntent) => xdr.ScVal;
+export declare function sponsorIntentHash(action: SponsoredAction, intent: ClaimIntent | SponsoredIdentityIntent): string;
+export declare function fundingPositionId(namespace: string, ownerEpoch: bigint): string;
+/** Canonical XDR is used for transport; JSON bigint coercion is never accepted. */
+export declare const encodeSponsorQuote: (v: SponsorQuote) => string;
+export declare function decodeSponsorQuote(encoded: string): SponsorQuote;
+export declare const FUNDING_ERRORS: Record<number, string>;

package/dist/funding-types.js

@@ -0,0 +1,249 @@
+import { hash, nativeToScVal, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { address, amount, bool, bytes32, exactObject, hex, hex32, label, paymentDestinationToScVal, sc, struct, u32, u64, unhex, } from "./native-codec.js";
+import { destinationFromNative } from "./payment.js";
+import { claimIntentToScVal } from "./native-types.js";
+export class FundingError extends Error {
+    kind;
+    transactionHash;
+    constructor(message, kind = "invalid", transactionHash = null) {
+        super(message);
+        this.kind = kind;
+        this.transactionHash = transactionHash;
+        this.name = "FundingError";
+    }
+}
+const primitive = (validate, encode) => ({ encode: (v) => encode(validate(v)), decode: validate });
+const U64 = primitive((v) => u64(v, "funding u64"), sc.u64), U32 = primitive((v) => u32(v, "funding u32"), sc.u32);
+const MONEY = primitive((v) => amount(v, "funding amount"), sc.i128), BOOL = primitive((v) => bool(v, "funding boolean"), sc.bool);
+const G = primitive((v) => address(v, "account", "funding account"), sc.address), C = primitive((v) => address(v, "contract", "funding contract"), sc.address), ID = primitive((v) => address(v, "identity", "funding controller"), sc.address);
+const HEX = {
+    encode: (v) => sc.bytes(unhex(hex32(v, "funding hash"))),
+    decode: (v) => hex(bytes32(v, "funding hash")),
+};
+function fullName(v) {
+    if (typeof v !== "string")
+        throw new FundingError("name must be a string");
+    const parts = v.split(".");
+    if (parts.length !== 2)
+        throw new FundingError("name must include its namespace");
+    parts.forEach(label);
+    return v;
+}
+const NAME = primitive(fullName, (v) => nativeToScVal(v, { type: "string" }));
+const optional = (c) => ({
+    encode: (v) => (v === null ? xdr.ScVal.scvVoid() : c.encode(v)),
+    decode: (v) => (v === null || v === undefined ? null : c.decode(v)),
+});
+const enumeration = (tags) => ({
+    encode: (v) => {
+        if (typeof v !== "string" || !Object.hasOwn(tags, v))
+            throw new FundingError("unknown funding enum");
+        return xdr.ScVal.scvVec([sc.symbol(tags[v])]);
+    },
+    decode: (v) => {
+        if (!Array.isArray(v) || v.length !== 1)
+            throw new FundingError("malformed funding enum");
+        const pair = Object.entries(tags).find(([, tag]) => tag === v[0]);
+        if (!pair)
+            throw new FundingError("unknown funding enum");
+        return pair[0];
+    },
+});
+const ACTION = enumeration({
+    claim: "Claim",
+    reverse: "Reverse",
+    primary: "Primary",
+});
+const snake = (v) => v.replace(/[A-Z]/g, (c) => "_" + c.toLowerCase());
+function model(fields) {
+    return {
+        encode: (v) => {
+            const r = exactObject(v, Object.keys(fields), "funding input");
+            return struct(Object.fromEntries(Object.entries(fields).map(([k, c]) => [snake(k), c.encode(r[k])])));
+        },
+        decode: (v) => {
+            const r = exactObject(v, Object.keys(fields).map(snake), "funding result");
+            return Object.fromEntries(Object.entries(fields).map(([k, c]) => [k, c.decode(r[snake(k)])]));
+        },
+    };
+}
+const CONFIG = model({
+    registry: C,
+    nativeAsset: C,
+    lookup: C,
+    primary: C,
+    governance: ID,
+    paused: BOOL,
+    revision: U64,
+});
+const POSITION = model({
+    namespace: HEX,
+    ownerEpoch: U64,
+    controller: ID,
+    balance: MONEY,
+    spentTotal: MONEY,
+    utcDay: U64,
+    spentToday: MONEY,
+    policyRevision: U64,
+    status: enumeration({ paused: "Paused", active: "Active", closed: "Closed" }),
+});
+const POLICY = model({
+    claimCap: MONEY,
+    reverseCap: MONEY,
+    primaryCap: MONEY,
+    dailyCap: MONEY,
+    totalCap: MONEY,
+    claimsPerWallet: U64,
+    identityPerDay: U32,
+    relayer: G,
+    quoteLifetime: U32,
+    validUntil: U64,
+});
+const QUOTE = model({
+    network: HEX,
+    funding: C,
+    configRevision: U64,
+    fundId: HEX,
+    policyRevision: U64,
+    action: ACTION,
+    actor: ID,
+    nonce: U64,
+    quoteId: HEX,
+    intentHash: HEX,
+    registrar: C,
+    resolver: C,
+    relayer: G,
+    charge: MONEY,
+    issuedLedger: U32,
+    expiresLedger: U32,
+});
+const DEST = {
+    encode: (v) => paymentDestinationToScVal(v),
+    decode: destinationFromNative,
+};
+const IDENTITY = model({
+    name: NAME,
+    actor: ID,
+    routingId: optional(U64),
+    generation: U64,
+    destination: DEST,
+    previous: optional(NAME),
+});
+const RECEIPT = model({
+    quoteId: HEX,
+    intentHash: HEX,
+    actor: ID,
+    nonce: U64,
+    action: ACTION,
+    charge: MONEY,
+    relayer: G,
+    balance: MONEY,
+    ledger: U32,
+});
+const LAST_RECEIPT = {
+    encode: (v) => xdr.ScVal.scvVec(v === null
+        ? [sc.symbol("Empty")]
+        : [sc.symbol("Recorded"), RECEIPT.encode(v)]),
+    decode: (v) => {
+        if (Array.isArray(v) && v.length === 1 && v[0] === "Empty")
+            return null;
+        if (Array.isArray(v) && v.length === 2 && v[0] === "Recorded")
+            return RECEIPT.decode(v[1]);
+        throw new FundingError("malformed receipt state");
+    },
+};
+const ACTOR = model({
+    nonce: U64,
+    claims: U64,
+    utcDay: U64,
+    identityToday: U32,
+    lastReceipt: LAST_RECEIPT,
+});
+export const fundingConfigurationFromNative = (v) => CONFIG.decode(v);
+export const fundingPositionFromNative = (v) => POSITION.decode(v);
+export const sponsorPolicyFromNative = (v) => POLICY.decode(v);
+export const sponsorQuoteFromNative = (v) => QUOTE.decode(v);
+export const sponsoredIdentityFromNative = (v) => IDENTITY.decode(v);
+export const sponsorReceiptFromNative = (v) => RECEIPT.decode(v);
+export const sponsorActorFromNative = (v) => ACTOR.decode(v);
+export const sponsoredActionToScVal = (v) => ACTION.encode(v);
+export function sponsorPolicyToScVal(v) {
+    const value = POLICY.encode(v);
+    if (v.dailyCap === 0n ||
+        v.totalCap === 0n ||
+        v.dailyCap > v.totalCap ||
+        [v.claimCap, v.reverseCap, v.primaryCap].some((n) => n > v.dailyCap) ||
+        [v.claimCap, v.reverseCap, v.primaryCap].every((n) => n === 0n) ||
+        (v.claimCap > 0n && v.claimsPerWallet === 0n) ||
+        ((v.reverseCap > 0n || v.primaryCap > 0n) && v.identityPerDay === 0) ||
+        v.quoteLifetime < 1 ||
+        v.quoteLifetime > 120 ||
+        v.validUntil === 0n)
+        throw new FundingError("invalid coverage, spending limits or policy lifetime");
+    return value;
+}
+export function sponsorQuoteToScVal(v) {
+    const result = QUOTE.encode(v);
+    if (v.charge === 0n ||
+        v.actor === v.relayer ||
+        v.expiresLedger <= v.issuedLedger ||
+        v.expiresLedger - v.issuedLedger > 120)
+        throw new FundingError("invalid sponsor charge, actor or quote lifetime");
+    return result;
+}
+export const sponsoredIdentityToScVal = (v) => IDENTITY.encode(v);
+export function sponsorIntentHash(action, intent) {
+    const encoded = action === "claim"
+        ? claimIntentToScVal(intent)
+        : sponsoredIdentityToScVal(intent);
+    return hex(hash(xdr.ScVal.scvVec([sc.symbol("sponsor_" + action), encoded]).toXDR()));
+}
+export function fundingPositionId(namespace, ownerEpoch) {
+    return hex(hash(xdr.ScVal.scvVec([
+        sc.symbol("fund_v1"),
+        HEX.encode(namespace),
+        U64.encode(ownerEpoch),
+    ]).toXDR()));
+}
+/** Canonical XDR is used for transport; JSON bigint coercion is never accepted. */
+export const encodeSponsorQuote = (v) => sponsorQuoteToScVal(v).toXDR("base64");
+export function decodeSponsorQuote(encoded) {
+    if (typeof encoded !== "string" || encoded.length > 16_384)
+        throw new FundingError("invalid sponsor quote size");
+    const q = sponsorQuoteFromNative(scValToNative(xdr.ScVal.fromXDR(encoded, "base64")));
+    sponsorQuoteToScVal(q);
+    return q;
+}
+export const FUNDING_ERRORS = {
+    1: "Not initialized",
+    2: "Unsupported network",
+    3: "Invalid configuration",
+    4: "Funding position not found",
+    5: "Funding position already exists",
+    6: "Funding position closed",
+    7: "Namespace ownership changed",
+    8: "Contract state unavailable",
+    9: "Invalid amount",
+    10: "Insufficient sponsorship funds",
+    11: "Invalid spending policy",
+    12: "Spending policy not configured",
+    13: "Sponsorship paused",
+    14: "Quote is stale",
+    15: "Quote expired",
+    16: "Invalid quote",
+    17: "Spending limit reached",
+    18: "Wallet allowance reached",
+    19: "Request already used",
+    20: "Action is not sponsored",
+    21: "Namespace contract changed",
+    22: "Action differs from approval",
+    23: "Action already completed",
+    24: "Name operation failed",
+    25: "Sponsor payment failed",
+    26: "Amount or counter overflow",
+    27: "Re-entry refused",
+    28: "Invalid name",
+    29: "Name inactive",
+    30: "Name state changed",
+    31: "Upgrade does not match",
+};

package/dist/funding-user.d.ts

@@ -0,0 +1,38 @@
+import { Transaction, authorizeEntry, xdr } from "@stellar/stellar-sdk";
+import { FundingReader } from "./funding-reader.js";
+import { type SponsorQuote, type SponsoredIdentityIntent } from "./funding-types.js";
+import { type ClaimIntent } from "./native-types.js";
+import { type NativeInvocation } from "./native-auth.js";
+export type SponsorRequest = {
+    quote: SponsorQuote;
+    intent: ClaimIntent | SponsoredIdentityIntent;
+    proof?: readonly string[];
+};
+export type SponsorPlan = {
+    request: SponsorRequest;
+    method: string;
+    args: xdr.ScVal[];
+    actorInvocation: NativeInvocation;
+    relayerInvocation: NativeInvocation;
+    eligibility?: {
+        account: string;
+        invocation: NativeInvocation;
+        latestLedger: number;
+        maxExpirationLedger: number;
+    };
+    maxNetworkFee: bigint;
+};
+/** Build from the app's reviewed intent and pinned shared contracts, never a remote invocation tree. */
+export declare function sponsorPlan(request: SponsorRequest, lookup: string, primary: string, maxNetworkFee: bigint, eligibilityAccount?: string): SponsorPlan;
+export declare function validateSponsorTransaction(tx: Transaction, p: SponsorPlan, latestLedger: number, signed?: boolean): xdr.SorobanAuthorizationEntry;
+export declare function replaceSponsorAuth(tx: Transaction, auth: xdr.SorobanAuthorizationEntry[], passphrase: string): Transaction;
+export declare class SoranSponsorship extends FundingReader {
+    plan(request: SponsorRequest, maxNetworkFee: bigint): Promise<SponsorPlan>;
+    prepare(request: SponsorRequest, maxNetworkFee: bigint, inclusionFee?: bigint): Promise<{
+        transaction: Transaction;
+        plan: SponsorPlan;
+        ledger: number;
+    }>;
+    /** Sign only the caller's G authorization. Wallet adapters retain custody of keys. */
+    authorize(request: SponsorRequest, encoded: string, signer: Parameters<typeof authorizeEntry>[1], maxSponsorCharge: bigint, maxNetworkFee: bigint, eligibilityXdr?: string): Promise<string>;
+}

package/dist/funding-user.js

@@ -0,0 +1,250 @@
+import { Address, Contract, Operation, Transaction, TransactionBuilder, authorizeEntry, rpc, nativeToScVal, xdr, } from "@stellar/stellar-sdk";
+import { FundingReader } from "./funding-reader.js";
+import { FundingError, sponsorIntentHash, sponsorQuoteToScVal, sponsoredIdentityToScVal, } from "./funding-types.js";
+import { claimIntentToScVal, claimLabelToScVal, claimQuoteFromNative, } from "./native-types.js";
+import { address, paymentDestinationToScVal, sc, unhex, } from "./native-codec.js";
+import { authorizedInvocation, validateEligibilityAuthorization, } from "./native-auth.js";
+/** Build from the app's reviewed intent and pinned shared contracts, never a remote invocation tree. */
+export function sponsorPlan(request, lookup, primary, maxNetworkFee, eligibilityAccount) {
+    const { quote: q, intent } = request;
+    const method = "sponsor_" + q.action;
+    if (q.intentHash !== sponsorIntentHash(q.action, intent) ||
+        maxNetworkFee <= 0n)
+        throw new FundingError("Quote differs from the requested action", "authorization");
+    let args, target;
+    if (q.action === "claim") {
+        const i = intent, encoded = claimIntentToScVal(i), proof = request.proof ?? [];
+        if (i.claimant !== q.actor ||
+            i.resolver !== q.resolver ||
+            i.context.registrar !== q.registrar ||
+            i.context.network !== q.network ||
+            proof.length > 64)
+            throw new FundingError("Claim route or actor differs from quote", "authorization");
+        args = [
+            sponsorQuoteToScVal(q),
+            encoded,
+            xdr.ScVal.scvVec(proof.map((p) => sc.bytes(unhex(p)))),
+        ];
+        const children = [];
+        if (i.feeAmount > 0n)
+            children.push({
+                contract: i.feeToken,
+                method: "transfer",
+                args: [
+                    sc.address(i.claimant),
+                    sc.address(i.feeRecipient),
+                    sc.i128(i.feeAmount),
+                ],
+            });
+        children.push({
+            contract: i.resolver,
+            method: "initialize_destination",
+            args: [
+                claimLabelToScVal(i.label),
+                sc.address(i.claimant),
+                sc.u64(i.expectedGeneration === null ? 0n : i.expectedGeneration + 1n),
+                paymentDestinationToScVal(i.destination),
+            ],
+        });
+        target = {
+            contract: q.registrar,
+            method: "claim",
+            args: [encoded],
+            children,
+        };
+    }
+    else {
+        const i = intent;
+        if (i.actor !== q.actor || request.proof?.length)
+            throw new FundingError("Identity actor or proof differs from action");
+        args = [sponsorQuoteToScVal(q), sponsoredIdentityToScVal(i)];
+        const reverse = q.action === "reverse";
+        target =
+            i.routingId === null
+                ? {
+                    contract: reverse ? q.resolver : primary,
+                    method: reverse ? "set_reverse" : "set_primary",
+                    args: [
+                        sc.address(i.actor),
+                        nativeToScVal(i.name, { type: "string" }),
+                    ],
+                }
+                : {
+                    contract: lookup,
+                    method: reverse ? "set_reverse_muxed" : "set_primary_muxed",
+                    args: [
+                        sc.address(i.actor),
+                        sc.u64(i.routingId),
+                        nativeToScVal(i.name, { type: "string" }),
+                    ],
+                };
+    }
+    const plan = {
+        request,
+        method,
+        args,
+        actorInvocation: { contract: q.funding, method, args, children: [target] },
+        relayerInvocation: { contract: q.funding, method, args },
+        maxNetworkFee,
+    };
+    if (eligibilityAccount) {
+        if (q.action !== "claim" ||
+            eligibilityAccount === q.actor ||
+            eligibilityAccount === q.relayer)
+            throw new FundingError("Eligibility account must be separate from user and relayer");
+        plan.eligibility = {
+            account: address(eligibilityAccount, "account", "eligibility"),
+            invocation: {
+                contract: q.registrar,
+                method: "claim",
+                args: [claimIntentToScVal(intent)],
+            },
+            latestLedger: q.issuedLedger,
+            maxExpirationLedger: q.expiresLedger,
+        };
+    }
+    return plan;
+}
+function same(a, b) {
+    return a.toXDR("base64") === authorizedInvocation(b).toXDR("base64");
+}
+export function validateSponsorTransaction(tx, p, latestLedger, signed = false) {
+    const q = p.request.quote;
+    if (tx.source !== q.relayer ||
+        tx.operations.length !== 1 ||
+        tx.memo.type !== "none" ||
+        BigInt(tx.fee) > p.maxNetworkFee ||
+        tx.signatures.length ||
+        latestLedger < q.issuedLedger ||
+        latestLedger >= q.expiresLedger)
+        throw new FundingError("Unapproved source, operation, fee, signature or ledger", "authorization");
+    const op = tx.operations[0];
+    if (op.type !== "invokeHostFunction" ||
+        (op.source && op.source !== q.relayer) ||
+        op.func.type !== "hostFunctionTypeInvokeContract")
+        throw new FundingError("Unexpected sponsored operation");
+    const c = op.func.invokeContract;
+    if (Address.fromScAddress(c.contractAddress).toString() !== q.funding ||
+        c.functionName.toString() !== p.method ||
+        c.args.length !== p.args.length ||
+        c.args.some((v, n) => v.toXDR("base64") !== p.args[n].toXDR("base64")))
+        throw new FundingError("Transaction differs from approved request", "authorization");
+    const auth = op.auth ?? [];
+    if (auth.length !== (p.eligibility ? 3 : 2))
+        throw new FundingError("Unexpected sponsor authorization count", "authorization");
+    const sources = auth.filter((e) => e.credentials.type === "sorobanCredentialsSourceAccount");
+    if (sources.length !== 1 ||
+        !same(sources[0].rootInvocation, p.relayerInvocation))
+        throw new FundingError("Relayer authorization exceeds its approved role", "authorization");
+    const actors = auth.filter((e) => e.credentials.type === "sorobanCredentialsAddress" &&
+        Address.fromScAddress(e.credentials.address.address).toString() ===
+            q.actor);
+    if (actors.length !== 1 || !same(actors[0].rootInvocation, p.actorInvocation))
+        throw new FundingError("User authorization differs from approved action", "authorization");
+    const credential = actors[0].credentials;
+    if (credential.type !== "sorobanCredentialsAddress")
+        throw new FundingError("Missing actor credential");
+    if (signed) {
+        if (credential.address.signatureExpirationLedger <= latestLedger ||
+            credential.address.signatureExpirationLedger > q.expiresLedger ||
+            credential.address.signature.toXDR().length > 16384 ||
+            // G accounts use Stellar's native vector format. C accounts define their
+            // own ScVal signature; enforced simulation must run their __check_auth.
+            (q.actor.startsWith("G") &&
+                (credential.address.signature.type !== "scvVec" ||
+                    !credential.address.signature.vec?.length)))
+            throw new FundingError("User authorization missing or expired", "authorization");
+    }
+    else if (credential.address.signature.type !== "scvVoid" &&
+        !(credential.address.signature.type === "scvVec" &&
+            !credential.address.signature.vec?.length))
+        throw new FundingError("Refusing to re-sign an authorization");
+    if (p.eligibility) {
+        const entries = auth.filter((e) => e.credentials.type === "sorobanCredentialsAddress" &&
+            Address.fromScAddress(e.credentials.address.address).toString() ===
+                p.eligibility.account);
+        if (entries.length !== 1)
+            throw new FundingError("Missing eligibility authorization");
+        validateEligibilityAuthorization(entries[0], { ...p.eligibility, latestLedger }, signed);
+    }
+    return actors[0];
+}
+export function replaceSponsorAuth(tx, auth, passphrase) {
+    const op = tx.operations[0];
+    if (op.type !== "invokeHostFunction")
+        throw new FundingError("Unexpected operation");
+    return TransactionBuilder.cloneFrom(tx, { networkPassphrase: passphrase })
+        .clearOperations()
+        .addOperation(Operation.invokeHostFunction({ func: op.func, auth }))
+        .build();
+}
+export class SoranSponsorship extends FundingReader {
+    async plan(request, maxNetworkFee) {
+        await this.validateQuote(request.quote);
+        let eligibility;
+        if (request.quote.action === "claim") {
+            const i = request.intent;
+            if (i.context.registry !== this.registryId)
+                throw new FundingError("Claim Registry differs from deployment");
+            const r = await this.read(request.quote.registrar, "claim_quote", [claimLabelToScVal(i.label), sc.address(i.claimant)], request.quote.issuedLedger);
+            const admission = claimQuoteFromNative(r.value).config?.settings
+                .admission;
+            if (admission?.type === "approval")
+                eligibility = admission.account;
+        }
+        return sponsorPlan(request, this.lookupId, this.primaryId, maxNetworkFee, eligibility);
+    }
+    async prepare(request, maxNetworkFee, inclusionFee = 100n) {
+        if (inclusionFee < 100n || inclusionFee > maxNetworkFee || inclusionFee > 0xffffffffn)
+            throw new FundingError("Invalid network inclusion fee");
+        const plan = await this.plan(request, maxNetworkFee);
+        const raw = new TransactionBuilder(await this.server.getAccount(request.quote.relayer), { fee: inclusionFee.toString(), networkPassphrase: this.passphrase })
+            .addOperation(new Contract(this.fundingId).call(plan.method, ...plan.args))
+            .setTimeout(60)
+            .build();
+        const sim = await this.server.simulateTransaction(raw, undefined, undefined, false);
+        if (rpc.Api.isSimulationRestore(sim))
+            throw new FundingError("Separate storage restoration is required; sponsorship is unavailable", "unavailable");
+        if (!rpc.Api.isSimulationSuccess(sim) || !sim.result)
+            throw new FundingError("Sponsored simulation failed", "unavailable");
+        const transaction = rpc.assembleTransaction(raw, sim).build();
+        validateSponsorTransaction(transaction, plan, sim.latestLedger);
+        return { transaction, plan, ledger: sim.latestLedger };
+    }
+    /** Sign only the caller's G authorization. Wallet adapters retain custody of keys. */
+    async authorize(request, encoded, signer, maxSponsorCharge, maxNetworkFee, eligibilityXdr) {
+        if (request.quote.charge > maxSponsorCharge)
+            throw new FundingError("Sponsor charge exceeds the reviewed amount");
+        address(request.quote.actor, "account", "this adapter's signing wallet");
+        const plan = await this.plan(request, maxNetworkFee), parsed = TransactionBuilder.fromXDR(encoded, this.passphrase);
+        if (!(parsed instanceof Transaction))
+            throw new FundingError("Fee-bump envelopes are not supported by this transport");
+        const latest = await this.server.getLatestLedger();
+        const entry = validateSponsorTransaction(parsed, plan, latest.sequence);
+        const signed = await authorizeEntry(entry, signer, request.quote.expiresLedger, this.passphrase);
+        const op = parsed.operations[0];
+        if (op.type !== "invokeHostFunction")
+            throw new FundingError("Unexpected operation");
+        const auth = (op.auth ?? []).map((e) => e.credentials.type === "sorobanCredentialsAddress" &&
+            Address.fromScAddress(e.credentials.address.address).toString() ===
+                request.quote.actor
+            ? signed
+            : e);
+        if (plan.eligibility) {
+            if (!eligibilityXdr || eligibilityXdr.length > 32768)
+                throw new FundingError("This claim requires the app's eligibility authorization");
+            const approval = xdr.SorobanAuthorizationEntry.fromXDR(eligibilityXdr, "base64");
+            validateEligibilityAuthorization(approval, {
+                ...plan.eligibility,
+                latestLedger: latest.sequence,
+            });
+            const at = auth.findIndex((e) => e.credentials.type === "sorobanCredentialsAddress" &&
+                Address.fromScAddress(e.credentials.address.address).toString() ===
+                    plan.eligibility.account);
+            auth[at] = approval;
+        }
+        const tx = replaceSponsorAuth(parsed, auth, this.passphrase);
+        validateSponsorTransaction(tx, plan, latest.sequence, true);
+        return tx.toXDR();
+    }
+}

package/dist/index.d.ts

@@ -281,3 +281,9 @@ export declare class SoranOwner {
      */
     private decodeFailure;
 }
+export * from "./funding-types.js";
+export { FundingReader, type FundingOptions } from "./funding-reader.js";
+export { SoranFunding } from "./funding-owner.js";
+export { SoranSponsorship, sponsorPlan, validateSponsorTransaction, type SponsorRequest, type SponsorPlan } from "./funding-user.js";
+export { FundingServiceClient } from "./funding-service.js";
+export { TestnetSponsorHistory, type SponsorHistory, type FundingReceipt } from "./funding-history.js";

package/dist/index.js

@@ -970,3 +970,9 @@ export class SoranOwner {
         return new OwnerError(`${fn} failed at inclusion (${resultCode})`, contractId, fn, null, null, hash);
     }
 }
+export * from "./funding-types.js";
+export { FundingReader } from "./funding-reader.js";
+export { SoranFunding } from "./funding-owner.js";
+export { SoranSponsorship, sponsorPlan, validateSponsorTransaction } from "./funding-user.js";
+export { FundingServiceClient } from "./funding-service.js";
+export { TestnetSponsorHistory } from "./funding-history.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorandomains/owner",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Run your Soran namespace on Stellar: configure claims, issue names and manage namespace policies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "tsc",
     "check:browser": "esbuild dist/index.js --bundle --platform=browser --external:@stellar/stellar-sdk --outfile=browser-check.js --legal-comments=none --log-level=error && node -e \"const fs=require('fs');const s=fs.readFileSync('browser-check.js','utf8');fs.unlinkSync('browser-check.js');if(/\\bBuffer\\b/.test(s)){console.error('FAIL: bare Buffer reference in browser bundle');process.exit(1)}console.log('browser bundle clean')\"",
-    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/integration.test.mts test/native-*.test.mts"
+    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/integration.test.mts test/native-*.test.mts && node --import tsx --test test/funding.test.mts test/funding-history.test.mts"
   },
   "license": "MIT",
   "repository": {