@sorandomains/owner 0.8.0 → 0.10.0

package/dist/funding-service.js

@@ -0,0 +1,133 @@
+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,
+        });
+        return this.reviewOffer(offer, action, intent, maxSponsorCharge, proof);
+    }
+    /** Re-estimate with the previous, valid wallet authorization. This never
+     * submits; review the new charge and call authorize again before submit. */
+    async refreshQuote(request, authorizedTransactionXdr, maxSponsorCharge) {
+        this.id(request.quote.quoteId);
+        const offer = await this.call("/v1/sponsorship/requote", {
+            quoteId: request.quote.quoteId, transactionXdr: authorizedTransactionXdr,
+        });
+        return this.reviewOffer(offer, request.quote.action, request.intent, maxSponsorCharge, request.proof ?? []);
+    }
+    async reviewOffer(offer, action, intent, maxSponsorCharge, 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,40 @@
+import { Transaction, authorizeEntry, xdr } from "@stellar/stellar-sdk";
+import { FundingReader } from "./funding-reader.js";
+import { type ContractWallet } from "./contract-wallet.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 authorization. C wallets supply their own signature
+     * format; the service enforces __check_auth before the relayer signs. */
+    authorize(request: SponsorRequest, encoded: string, signer: Parameters<typeof authorizeEntry>[1] | ContractWallet, maxSponsorCharge: bigint, maxNetworkFee: bigint, eligibilityXdr?: string): Promise<string>;
+}