@sorandomains/holder 0.3.1 → 0.5.0

package/dist/native-codec.d.ts

@@ -0,0 +1,38 @@
+/** Local successor-ABI helpers. No deployed defaults are changed by this module. */
+import { xdr } from "@stellar/stellar-sdk";
+import { type PaymentDestination } from "./payment.js";
+export declare const NATIVE_REGISTRAR_ERRORS: Record<number, string>;
+export declare class NativeClaimError extends Error {
+    readonly kind: "unsupported" | "unavailable" | "invalid" | "authorization" | "pending" | "failed";
+    readonly txHash: string | null;
+    readonly contractCode: number | null;
+    readonly contractError: string | null;
+    constructor(message: string, kind?: "unsupported" | "unavailable" | "invalid" | "authorization" | "pending" | "failed", txHash?: string | null);
+}
+export declare function exactObject(raw: unknown, keys: readonly string[], label: string): Record<string, unknown>;
+export declare function u64(value: unknown, label: string): bigint;
+export declare function u32(value: unknown, label: string): number;
+export declare function amount(value: unknown, label: string): bigint;
+export declare function bool(value: unknown, label: string): boolean;
+export declare function address(value: unknown, kind: "account" | "contract" | "identity", label: string): string;
+export declare function bytes32(value: unknown, label: string): Uint8Array;
+export declare function hex32(value: unknown, label: string): string;
+export declare const hex: (value: Uint8Array) => string;
+export declare const unhex: (value: string) => Uint8Array;
+export declare const utf8: (value: string) => Uint8Array;
+export declare function label(value: unknown): string;
+export declare function namespaceNode(namespace: string): Uint8Array;
+export declare const sc: {
+    address: (value: string) => xdr.ScVal;
+    bytes: (value: Uint8Array) => xdr.ScVal;
+    u64: (value: bigint) => xdr.ScVal;
+    u32: (value: number) => xdr.ScVal;
+    i128: (value: bigint) => xdr.ScVal;
+    bool: (value: boolean) => xdr.ScVal;
+    symbol: (value: string) => xdr.ScVal;
+    option: (value: xdr.ScVal | null) => xdr.ScVal;
+};
+/** Contract structs are canonical symbol-keyed maps, not generic JSON maps. */
+export declare function struct(fields: Record<string, xdr.ScVal>): xdr.ScVal;
+export declare function paymentDestinationToScVal(raw: PaymentDestination): xdr.ScVal;
+export declare function sameScVal(left: xdr.ScVal, right: xdr.ScVal): boolean;

package/dist/native-codec.js

@@ -0,0 +1,95 @@
+/** Local successor-ABI helpers. No deployed defaults are changed by this module. */
+import { Address, StrKey, hash, nativeToScVal, xdr } from "@stellar/stellar-sdk";
+import { decodeMuxedAddress, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
+export const NATIVE_REGISTRAR_ERRORS = { 21: "InvalidClaimConfig", 22: "ClaimsNotConfigured", 23: "ClaimsPaused", 24: "StaleClaimPolicy", 25: "ClaimIntentMismatch", 26: "ClaimIntentExpired", 27: "ReservedName", 28: "NameNotReserved", 29: "PublicIssuanceRequired", 30: "WalletClaimLimit", 31: "InvalidEligibility", 32: "ApprovalAllowanceReached", 33: "ApprovalRateReached", 34: "RequestIdConflict", 35: "CounterOverflow", 36: "InvalidNativeBinding", 37: "UnsupportedClaimant", 38: "DuplicateLabel", 39: "RenewalTooEarly", 40: "RenewalLeaseLimit", 41: "DestinationInitializationFailed", 42: "FeeSettlementFailed" };
+export class NativeClaimError extends Error {
+    kind;
+    txHash;
+    contractCode;
+    contractError;
+    constructor(message, kind = "invalid", txHash = null) {
+        super(message);
+        this.kind = kind;
+        this.txHash = txHash;
+        this.name = "NativeClaimError";
+        const match = /Error\(Contract, #(\d+)\)/.exec(message);
+        this.contractCode = match ? Number(match[1]) : null;
+        this.contractError = this.contractCode === null ? null : NATIVE_REGISTRAR_ERRORS[this.contractCode] ?? null;
+    }
+}
+export function exactObject(raw, keys, label) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).sort().join(",") !== [...keys].sort().join(","))
+        throw new NativeClaimError(`invalid ${label} fields`);
+    return raw;
+}
+export function u64(value, label) {
+    if (typeof value !== "bigint" || value < 0n || value > 18446744073709551615n)
+        throw new NativeClaimError(`${label} must be an unsigned 64-bit bigint`);
+    return value;
+}
+export function u32(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 4294967295)
+        throw new NativeClaimError(`${label} must be an unsigned 32-bit number`);
+    return value;
+}
+export function amount(value, label) {
+    if (typeof value !== "bigint" || value < 0n || value > (1n << 127n) - 1n)
+        throw new NativeClaimError(`${label} must be a nonnegative i128 bigint`);
+    return value;
+}
+export function bool(value, label) {
+    if (typeof value !== "boolean")
+        throw new NativeClaimError(`${label} must be boolean`);
+    return value;
+}
+export function address(value, kind, label) {
+    if (typeof value !== "string" || !(kind !== "contract" && StrKey.isValidEd25519PublicKey(value) || kind !== "account" && StrKey.isValidContract(value)))
+        throw new NativeClaimError(`${label} must be a valid ${kind === "identity" ? "G or C" : kind === "account" ? "G" : "C"} address`);
+    return value;
+}
+export function bytes32(value, label) {
+    if (!(value instanceof Uint8Array) || value.length !== 32)
+        throw new NativeClaimError(`${label} must contain exactly 32 bytes`);
+    return new Uint8Array(value);
+}
+export function hex32(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
+        throw new NativeClaimError(`${label} must be 64 lowercase hex characters`);
+    return value;
+}
+export const hex = (value) => Array.from(value, byte => byte.toString(16).padStart(2, "0")).join("");
+export const unhex = (value) => Uint8Array.from(hex32(value, "32-byte value").match(/../g), byte => parseInt(byte, 16));
+export const utf8 = (value) => new TextEncoder().encode(value);
+export function label(value) {
+    if (typeof value !== "string" || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(value))
+        throw new NativeClaimError("intent label must be canonical lowercase ASCII, 1–63 characters");
+    return value;
+}
+export function namespaceNode(namespace) {
+    const combined = new Uint8Array(64);
+    combined.set(hash(utf8(label(namespace))), 32);
+    return new Uint8Array(hash(combined));
+}
+export const sc = {
+    address: (value) => new Address(value).toScVal(),
+    bytes: (value) => nativeToScVal(value, { type: "bytes" }),
+    u64: (value) => nativeToScVal(value, { type: "u64" }),
+    u32: (value) => nativeToScVal(value, { type: "u32" }),
+    i128: (value) => nativeToScVal(value, { type: "i128" }),
+    bool: (value) => nativeToScVal(value, { type: "bool" }),
+    symbol: (value) => nativeToScVal(value, { type: "symbol" }),
+    option: (value) => value ?? xdr.ScVal.scvVoid(),
+};
+/** Contract structs are canonical symbol-keyed maps, not generic JSON maps. */
+export function struct(fields) {
+    return xdr.ScVal.scvMap(Object.keys(fields).sort().map(key => new xdr.ScMapEntry({ key: sc.symbol(key), val: fields[key] })));
+}
+export function paymentDestinationToScVal(raw) {
+    const payment = validatePaymentDestination(raw);
+    if (StrKey.isValidMed25519PublicKey(payment.address)) {
+        const value = decodeMuxedAddress(payment.address);
+        return xdr.ScVal.scvVec([sc.symbol("Muxed"), struct({ account: sc.address(value.account), id: sc.u64(BigInt(value.id)) })]);
+    }
+    return xdr.ScVal.scvVec([sc.symbol("Direct"), struct({ address: sc.address(payment.address), memo: paymentMemoToScVal(payment.memo) })]);
+}
+export function sameScVal(left, right) { return left.toXDR("base64") === right.toXDR("base64"); }

package/dist/native-holder.d.ts

@@ -0,0 +1,42 @@
+import { type NativeAuthorizationPlan } from "./native-auth.js";
+import { type NativeContext, type NativeWriteOptions, type NativePrepared } from "./native-transport.js";
+import { type ClaimIntent, type ClaimQuote, type ClaimReceipt, type ClaimResult, type TransferIntent, type RenewIntent, type DestinationPreview } from "./native-types.js";
+import { type PaymentDestination } from "./payment.js";
+export type ClaimRequestOptions = {
+    requestId: string;
+    deadline: bigint;
+    validAfter?: bigint;
+};
+export type ClaimSubmitOptions = NativeWriteOptions & {
+    proof?: readonly string[];
+};
+export type NativeClaimSubmission = ClaimResult & {
+    transaction: {
+        hash: string;
+        ledger: number;
+    } | null;
+};
+export type PreparedClaim = NativePrepared & {
+    intent: ClaimIntent;
+    plan: NativeAuthorizationPlan;
+};
+export declare function createClaimIntent(quote: ClaimQuote, destination: PaymentDestination, options: ClaimRequestOptions): ClaimIntent;
+export declare class NativeHolderClient {
+    private context;
+    constructor(context: NativeContext);
+    nativeClaimCapability(namespace: string): Promise<import("./native-transport.js").NativeCapability>;
+    private registrar;
+    private checkRegistrar;
+    claimQuote(name: string, claimant?: string): Promise<ClaimQuote>;
+    private checkQuote;
+    claimReceipt(namespace: string, claimant: string, requestId: string): Promise<ClaimReceipt | null>;
+    private receiptAt;
+    recoverClaim(intent: ClaimIntent): Promise<ClaimReceipt | null>;
+    private planClaim;
+    buildClaim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<PreparedClaim>;
+    claim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<NativeClaimSubmission>;
+    renewalPreview(name: string): Promise<DestinationPreview>;
+    acceptNameTransferWithDestination(input: TransferIntent, options?: NativeWriteOptions): Promise<NativeClaimSubmission>;
+    renewName(input: RenewIntent, options?: NativeWriteOptions): Promise<NativeClaimSubmission>;
+    private lifecycle;
+}

package/dist/native-holder.js

@@ -0,0 +1,221 @@
+import { hash, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, bytes32, exactObject, hex, hex32, label, namespaceNode, sc, u64, unhex, utf8 } from "./native-codec.js";
+import { nativeCapability, requireNative, verifyRegistrarProvenance, prepareNative, sendNative } from "./native-transport.js";
+import { claimIntentToScVal, claimIntentFromNative, claimQuoteFromNative, claimReceiptFromNative, claimResultFromNative, destinationPreviewFromNative, transferIntentToScVal, renewIntentToScVal, nativeIntentHash, claimLabelToScVal } from "./native-types.js";
+import { paymentDestinationToScVal } from "./native-codec.js";
+import { validatePaymentDestination } from "./payment.js";
+import { verifyClaimAllowlistProof } from "./native-allowlist.js";
+const canonicalNamespace = (value) => { if (typeof value !== "string" || /[^\x00-\x7f]/.test(value))
+    throw new NativeClaimError("namespace must contain ASCII characters only"); return label(value.toLowerCase()); };
+const names = (name) => { if (typeof name !== "string" || /[^\x00-\x7f]/.test(name))
+    throw new NativeClaimError("name must be ASCII"); const parts = name.toLowerCase().split("."); if (parts.length !== 2)
+    throw new NativeClaimError("expected label.namespace"); return { label: label(parts[0]), namespace: label(parts[1]) }; };
+const networkId = (passphrase) => hex(hash(utf8(passphrase)));
+function scoped(context, request) { if (request.registry !== context.registryId || request.network !== networkId(context.passphrase))
+    throw new NativeClaimError("intent targets a different network or Registry"); }
+function contextFromQuote(quote, opts) { return { network: quote.network, registry: quote.registry, registrar: quote.registrar, namespace: quote.namespace, requestId: hex32(opts.requestId, "request ID"), validAfter: opts.validAfter ?? quote.now, deadline: opts.deadline }; }
+export function createClaimIntent(quote, destination, options) {
+    if (!quote.config)
+        throw new NativeClaimError("namespace public claims are not configured", "unsupported");
+    const config = quote.config;
+    const settings = config.settings;
+    const result = { context: contextFromQuote(quote, options), label: quote.label, claimant: quote.claimant, destination: validatePaymentDestination(destination), resolver: quote.resolver, expectedGeneration: quote.generation, expectedExpiry: quote.expiresAt, termSecs: quote.termSecs, ownerEpoch: quote.ownerEpoch, policyVersion: quote.policyVersion, grantEpoch: config.grantEpoch, feeToken: settings.feeToken, feeAmount: settings.feeAmount, feeRecipient: settings.feeRecipient };
+    return claimIntentFromNative(scValToNative(claimIntentToScVal(result)));
+}
+function initialization(resolver, nameLabel, holder, generation, destination) { return { contract: resolver, method: "initialize_destination", args: [claimLabelToScVal(nameLabel), sc.address(holder), sc.u64(u64(generation, "new generation")), paymentDestinationToScVal(destination)] }; }
+function receiptMatches(receipt, method, intent, holder) {
+    if (receipt.intentHash !== nativeIntentHash(method, intent) || receipt.holder !== holder)
+        throw new NativeClaimError("request ID already belongs to a different immutable intent");
+    const raw = scValToNative(intent), expectedOperation = { claim: "claim", issue_reserved_with_destination: "reserved", accept_transfer_with_destination: "transfer", renew_holder: "renew" }[method];
+    const nodeBytes = new Uint8Array(64);
+    nodeBytes.set(raw.context.namespace);
+    nodeBytes.set(hash(raw.label), 32);
+    if (receipt.operation !== expectedOperation || receipt.node !== hex(hash(nodeBytes)))
+        throw new NativeClaimError("receipt operation/name differs from intent");
+    const generation = method === "renew_holder" ? raw.expected_generation : raw.expected_generation === null || raw.expected_generation === undefined ? 0n : raw.expected_generation + 1n;
+    if (receipt.generation !== generation)
+        throw new NativeClaimError("receipt generation differs from intent");
+    if (method === "claim") {
+        if (receipt.feeAmount !== raw.fee_amount || receipt.feeToken !== raw.fee_token || receipt.feeRecipient !== (raw.fee_amount > 0n ? raw.fee_recipient : null))
+            throw new NativeClaimError("receipt fee settlement differs from intent");
+        if (receipt.expiresAt !== (raw.term_secs === 0n ? 0n : receipt.timestamp + raw.term_secs))
+            throw new NativeClaimError("receipt lease differs from intent");
+    }
+    else {
+        if (receipt.feeAmount !== 0n || receipt.feeRecipient !== null)
+            throw new NativeClaimError("lifecycle receipt unexpectedly contains a username fee");
+        if (method === "accept_transfer_with_destination" && receipt.expiresAt !== raw.expected_expiry)
+            throw new NativeClaimError("transfer receipt changed the lease");
+        if (method === "renew_holder" && (receipt.expiresAt < raw.min_new_expiry || receipt.expiresAt > raw.max_new_expiry || receipt.expiresAt !== (receipt.timestamp > raw.expected_expiry ? receipt.timestamp : raw.expected_expiry) + raw.term_secs))
+            throw new NativeClaimError("renewal receipt differs from signed lease bounds");
+    }
+}
+function confirmedResult(result, method, encoded, holder) { try {
+    const decoded = claimResultFromNative(result.value);
+    receiptMatches(decoded.receipt, method, encoded, holder);
+    return { ...decoded, transaction: { hash: result.hash, ledger: result.ledger } };
+}
+catch (error) {
+    throw new NativeClaimError(`transaction confirmed but result could not be verified: ${String(error)}; recover the original request`, "pending", result.hash);
+} }
+export class NativeHolderClient {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async nativeClaimCapability(namespace) { return nativeCapability(this.context, canonicalNamespace(namespace)); }
+    async registrar(namespace) {
+        const node = namespaceNode(namespace);
+        const registrar = address(await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(node)]), "contract", "Registrar");
+        await this.checkRegistrar(registrar, hex(node));
+        return registrar;
+    }
+    async checkRegistrar(registrar, node) {
+        await verifyRegistrarProvenance(this.context, registrar, node);
+        const [anchors, version] = await Promise.all([this.context.read(registrar, "anchors", []), this.context.read(registrar, "claim_version", [])]);
+        const attested = await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(unhex(node))]);
+        if (attested !== registrar)
+            throw new NativeClaimError("intent Registrar is not the Registry attestation", "unavailable");
+        if (version !== 1)
+            throw new NativeClaimError("unsupported native claim version", "unsupported");
+        if (!Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== this.context.registryId || hex(bytes32(anchors[1], "namespace anchor")) !== node)
+            throw new NativeClaimError("Registrar anchors differ from intent", "unavailable");
+    }
+    async claimQuote(name, claimant) {
+        const parsed = names(name);
+        const cap = await requireNative(this.context, parsed.namespace);
+        const wallet = address(claimant ?? await this.context.signer.publicKey(), "account", "claimant");
+        const quote = claimQuoteFromNative(await this.context.read(cap.registrar, "claim_quote", [claimLabelToScVal(parsed.label), sc.address(wallet)]));
+        this.checkQuote(quote, cap.registrar, hex(namespaceNode(parsed.namespace)), parsed.label, wallet);
+        if (quote.resolver !== cap.resolver)
+            throw new NativeClaimError("quote Resolver differs from the selected native binding", "unavailable");
+        return quote;
+    }
+    checkQuote(quote, registrar, node, nameLabel, wallet) {
+        if (quote.network !== networkId(this.context.passphrase) || quote.registry !== this.context.registryId || quote.registrar !== registrar || quote.namespace !== node || quote.label !== nameLabel || quote.claimant !== wallet)
+            throw new NativeClaimError("claim quote differs from requested network, namespace or claimant", "unavailable");
+        const bytes = new Uint8Array(64);
+        bytes.set(unhex(node));
+        bytes.set(hash(utf8(nameLabel)), 32);
+        if (quote.node !== hex(hash(bytes)))
+            throw new NativeClaimError("quote name node is invalid", "unavailable");
+    }
+    async claimReceipt(namespace, claimant, requestId) { return this.receiptAt(await this.registrar(canonicalNamespace(namespace)), claimant, requestId); }
+    async receiptAt(registrar, claimant, requestId) {
+        const raw = await this.context.read(registrar, "claim_receipt", [sc.address(address(claimant, "identity", "receipt holder")), sc.bytes(unhex(requestId))]);
+        return raw === null ? null : claimReceiptFromNative(raw);
+    }
+    async recoverClaim(intent) { const encoded = claimIntentToScVal(intent); scoped(this.context, intent.context); await verifyRegistrarProvenance(this.context, intent.context.registrar, intent.context.namespace); if (await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(unhex(intent.context.namespace))]) !== intent.context.registrar)
+        throw new NativeClaimError("recovery Registrar is not the Registry attestation", "unavailable"); const receipt = await this.receiptAt(intent.context.registrar, intent.claimant, intent.context.requestId); if (receipt)
+        receiptMatches(receipt, "claim", encoded, intent.claimant); return receipt; }
+    async planClaim(input, proof = []) {
+        const encoded = claimIntentToScVal(input);
+        const intent = claimIntentFromNative(scValToNative(encoded));
+        scoped(this.context, intent.context);
+        const wallet = address(await this.context.signer.publicKey(), "account", "claimant");
+        if (intent.claimant !== wallet)
+            throw new NativeClaimError("intent claimant is not the connected wallet", "authorization");
+        await this.checkRegistrar(intent.context.registrar, intent.context.namespace);
+        const pair = await this.context.read(this.context.registryId, "native_contracts", [sc.bytes(unhex(intent.context.namespace))]);
+        if (!Array.isArray(pair) || pair.length !== 2 || pair[0] !== intent.context.registrar || pair[1] !== intent.resolver)
+            throw new NativeClaimError("intent differs from current clean native contract bindings", "unavailable");
+        const quote = claimQuoteFromNative(await this.context.read(intent.context.registrar, "claim_quote", [claimLabelToScVal(intent.label), sc.address(wallet)]));
+        this.checkQuote(quote, intent.context.registrar, intent.context.namespace, intent.label, wallet);
+        const config = quote.config;
+        if (!config || config.settings.mode !== "public" || !config.settings.enabled)
+            throw new NativeClaimError("public claiming is disabled", "unavailable");
+        if (!quote.available || quote.reserved)
+            throw new NativeClaimError(quote.reserved ? "username is reserved" : "username is unavailable");
+        if (quote.now < intent.context.validAfter || quote.now > intent.context.deadline)
+            throw new NativeClaimError("claim intent is outside its business deadline");
+        if (config.ownerEpoch !== quote.ownerEpoch || config.policyVersion !== quote.policyVersion || intent.ownerEpoch !== quote.ownerEpoch || intent.policyVersion !== quote.policyVersion || intent.grantEpoch !== config.grantEpoch || intent.resolver !== quote.resolver || intent.expectedGeneration !== quote.generation || intent.expectedExpiry !== quote.expiresAt || intent.termSecs !== quote.termSecs || intent.feeToken !== config.settings.feeToken || intent.feeAmount !== config.settings.feeAmount || intent.feeRecipient !== config.settings.feeRecipient)
+            throw new NativeClaimError("claim terms changed; reconcile the original request before reviewing a replacement");
+        const nativeToken = await this.context.read(intent.context.registrar, "native_fee_token", []);
+        if (nativeToken !== intent.feeToken)
+            throw new NativeClaimError("claim fee is not the canonical native token");
+        if (config.settings.walletLimit > 0n && quote.usage.publicClaims >= config.settings.walletLimit)
+            throw new NativeClaimError("lifetime wallet claim limit reached");
+        const admission = config.settings.admission;
+        if (!Array.isArray(proof) || proof.length > 32)
+            throw new NativeClaimError("allowlist proof exceeds 32 siblings");
+        if (admission.type === "allowlist") {
+            if (!verifyClaimAllowlistProof({ network: intent.context.network, registry: intent.context.registry, namespace: intent.context.namespace, registrar: intent.context.registrar }, wallet, proof, admission.root))
+                throw new NativeClaimError("wallet is not in the committed allowlist");
+        }
+        else if (proof.length)
+            throw new NativeClaimError("this admission mode does not accept an allowlist proof");
+        const children = [];
+        if (intent.feeAmount > 0n)
+            children.push({ contract: intent.feeToken, method: "transfer", args: [sc.address(wallet), sc.address(intent.feeRecipient), sc.i128(intent.feeAmount)] });
+        children.push(initialization(intent.resolver, intent.label, wallet, intent.expectedGeneration === null ? 0n : intent.expectedGeneration + 1n, intent.destination));
+        const plan = { source: wallet, contract: intent.context.registrar, method: "claim", args: [encoded, xdr.ScVal.scvVec(proof.map(value => sc.bytes(unhex(value))))], sourceInvocation: { contract: intent.context.registrar, method: "claim", args: [encoded], children }, maxFeeStroops: this.context.maxFeeStroops };
+        if (admission.type === "approval") {
+            if (admission.account === wallet || admission.account === intent.feeRecipient)
+                throw new NativeClaimError("eligibility account must be separate from claimant and treasury", "authorization");
+            if (intent.context.deadline - intent.context.validAfter > config.settings.approvalTtlSecs)
+                throw new NativeClaimError("claim lifetime exceeds the current approval lifetime");
+            if (quote.approvalUsage.total >= config.settings.approvalAllowance)
+                throw new NativeClaimError("cumulative approval allowance exhausted");
+            if (quote.now < quote.approvalUsage.windowEnds && quote.approvalUsage.windowUsed >= config.settings.approvalRateLimit)
+                throw new NativeClaimError("approval rate limit reached");
+            const latest = await this.context.server.getLatestLedger();
+            // Ledger credential TTL and timestamp business TTL are separate ceilings. At most 60 ledgers per SDK approval.
+            const remaining = intent.context.deadline - quote.now;
+            const ledgerSpan = Math.max(1, Math.min(60, Number(remaining)));
+            plan.eligibility = { account: admission.account, invocation: { contract: intent.context.registrar, method: "claim", args: [encoded] }, latestLedger: latest.sequence, maxExpirationLedger: latest.sequence + ledgerSpan };
+        }
+        return { intent, plan };
+    }
+    async buildClaim(intent, options = {}) {
+        if (await this.recoverClaim(intent))
+            throw new NativeClaimError("this request already completed; recover its receipt instead of building a transaction");
+        const built = await this.planClaim(intent, options.proof);
+        const { prepared } = await prepareNative(this.context, built.plan, options);
+        return { ...prepared, intent: built.intent, plan: built.plan };
+    }
+    async claim(intent, options = {}) {
+        // Snapshot before any awaits: callers cannot mutate reviewed destination/amount mid-flow.
+        const snapshot = claimIntentFromNative(scValToNative(claimIntentToScVal(intent)));
+        return this.context.serialize(async () => { const old = await this.recoverClaim(snapshot); if (old)
+            return { status: "replayed", receipt: old, transaction: null }; const { plan } = await this.planClaim(snapshot, options.proof); const result = await sendNative(this.context, plan, options); return confirmedResult(result, "claim", claimIntentToScVal(snapshot), snapshot.claimant); });
+    }
+    async renewalPreview(name) {
+        const parsed = names(name), registrar = await this.registrar(parsed.namespace);
+        const raw = exactObject(await this.context.read(registrar, "record_of", [claimLabelToScVal(parsed.label)]), ["holder", "address", "expires_at", "generation"], "name record");
+        const resolver = address(await this.context.read(this.context.registryId, "resolver_of", [sc.bytes(namespaceNode(parsed.namespace))]), "contract", "Resolver");
+        const result = destinationPreviewFromNative(await this.context.read(resolver, "preview_destination", [xdr.ScVal.scvString(`${parsed.label}.${parsed.namespace}`), sc.u64(u64(raw.generation, "name generation"))]));
+        if (result.holder !== raw.holder || result.generation !== raw.generation || result.expiresAt !== raw.expires_at)
+            throw new NativeClaimError("renewal preview no longer matches name state", "unavailable");
+        return result;
+    }
+    async acceptNameTransferWithDestination(input, options = {}) {
+        const encoded = transferIntentToScVal(input);
+        return this.lifecycle("accept_transfer_with_destination", input.context, input.to, encoded, input.label, initialization(input.resolver, input.label, input.to, input.expectedGeneration + 1n, input.destination), options);
+    }
+    async renewName(input, options = {}) { return this.lifecycle("renew_holder", input.context, input.holder, renewIntentToScVal(input), input.label, null, options); }
+    async lifecycle(method, request, holder, intent, nameLabel, child, options) {
+        request = { ...request };
+        scoped(this.context, request);
+        return this.context.serialize(async () => {
+            await verifyRegistrarProvenance(this.context, request.registrar, request.namespace);
+            if (await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(unhex(request.namespace))]) !== request.registrar)
+                throw new NativeClaimError("recovery Registrar is not the Registry attestation", "unavailable");
+            const old = await this.receiptAt(request.registrar, holder, request.requestId);
+            if (old) {
+                receiptMatches(old, method, intent, holder);
+                return { status: "replayed", receipt: old, transaction: null };
+            }
+            await this.checkRegistrar(request.registrar, request.namespace);
+            if (child) {
+                const pair = await this.context.read(this.context.registryId, "native_contracts", [sc.bytes(unhex(request.namespace))]);
+                if (!Array.isArray(pair) || pair.length !== 2 || pair[0] !== request.registrar || pair[1] !== child.contract)
+                    throw new NativeClaimError("transfer initializer differs from clean native bindings", "unavailable");
+            }
+            const source = address(await this.context.signer.publicKey(), "account", "holder source");
+            if (source !== holder)
+                throw new NativeClaimError("connected wallet is not the intended holder/recipient", "authorization");
+            const result = await sendNative(this.context, { source, contract: request.registrar, method, args: [intent], sourceInvocation: { contract: request.registrar, method, args: [intent], children: child ? [child] : [] }, maxFeeStroops: this.context.maxFeeStroops }, options);
+            return confirmedResult(result, method, intent, holder);
+        });
+    }
+}

package/dist/native-transport.d.ts

@@ -0,0 +1,66 @@
+import { Transaction, rpc, xdr } from "@stellar/stellar-sdk";
+import { type NativeAuthorizationPlan } from "./native-auth.js";
+export type NativeSigner = {
+    publicKey(): string | Promise<string>;
+    signTransaction(encoded: string, opts: {
+        networkPassphrase: string;
+    }): Promise<string | {
+        signedTxXdr: string;
+    }>;
+};
+export type NativeContext = {
+    registryId: string;
+    passphrase: string;
+    server: rpc.Server;
+    signer: NativeSigner;
+    fee: string;
+    timeoutSecs: number;
+    maxFeeStroops: bigint;
+    read(contract: string, method: string, args: xdr.ScVal[]): Promise<unknown>;
+    serialize<T>(work: () => Promise<T>): Promise<T>;
+};
+export type NativeCapability = {
+    supported: false;
+    registrar: string;
+    reason: "legacy-template" | "unsupported-version";
+} | {
+    supported: true;
+    version: 1;
+    registrar: string;
+    resolver: string;
+    registry: string;
+    namespace: string;
+    owner: string;
+    ownerEpoch: bigint;
+};
+/** Historical reads must not trust an upgraded Registrar that can fabricate receipts. Resolver changes do not block this Registrar-only check. */
+export declare function verifyRegistrarProvenance(context: NativeContext, registrar: string, namespace: string): Promise<void>;
+export declare function nativeCapability(context: NativeContext, namespace: string): Promise<NativeCapability>;
+export declare function requireNative(context: NativeContext, namespace: string): Promise<Extract<NativeCapability, {
+    supported: true;
+}>>;
+export type NativePrepared = {
+    transactionXdr: string;
+    hash: string;
+    networkPassphrase: string;
+    feeStroops: bigint;
+    eligibilityEntryXdr: string | null;
+};
+export type NativeWriteOptions = {
+    /** Exact native admission authorization from the app. This is not an owner transaction signature. */
+    eligibilityAuthorization?: string;
+    /** Persist the public recovery reference before wallet signing/broadcast. Rejecting stops submission. */
+    onPrepared?: (prepared: NativePrepared) => void | Promise<void>;
+};
+export declare function prepareNative(context: NativeContext, plan: NativeAuthorizationPlan, options?: NativeWriteOptions): Promise<{
+    transaction: Transaction;
+    prepared: NativePrepared;
+}>;
+/** No automatic transaction retry, implicit restoration or hash-losing error path. */
+export declare function sendNative(context: NativeContext, plan: NativeAuthorizationPlan, options?: NativeWriteOptions): Promise<{
+    hash: string;
+    ledger: number;
+    value: unknown;
+}>;
+/** Bind terminal RPC context before classifying success or failure. An incomplete response remains uncertain. */
+export declare function validateNativeTerminalReceipt(receipt: rpc.Api.GetSuccessfulTransactionResponse | rpc.Api.GetFailedTransactionResponse, expectedHash: string, passphrase: string): void;

package/dist/native-transport.js

@@ -0,0 +1,136 @@
+import { Contract, Operation, Transaction, TransactionBuilder, rpc, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, bytes32, hex, namespaceNode, sc, unhex } from "./native-codec.js";
+import { assertSignedBodyUnchanged, validateEligibilityAuthorization, validateNativeTransaction } from "./native-auth.js";
+/** This published legacy code has owner-only issuance. Missing RPC data is never legacy detection. */
+const LEGACY_REGISTRAR_HASH = "ed06b3374ff4342b4a2316fc546505132cd8fd35be6666571cf088710af9bbc6";
+/** Historical reads must not trust an upgraded Registrar that can fabricate receipts. Resolver changes do not block this Registrar-only check. */
+export async function verifyRegistrarProvenance(context, registrar, namespace) {
+    const node = sc.bytes(unhex(namespace));
+    const [attested, tainted, templates, instance] = await Promise.all([
+        context.read(context.registryId, "registrar_of", [node]), context.read(context.registryId, "registrar_tainted", [node]),
+        context.read(context.registryId, "template_hashes", []), context.server.getContractInstance(registrar),
+    ]);
+    if (attested !== registrar || tainted !== false || !Array.isArray(templates) || templates.length !== 2 || instance.executable.type !== "contractExecutableWasm")
+        throw new NativeClaimError("Registrar provenance is unavailable or tainted; refusing authoritative claim/receipt reads", "unavailable");
+    if (hex(bytes32(templates[0], "Registry Registrar template")) !== hex(instance.executable.wasmHash.value))
+        throw new NativeClaimError("Registrar executable differs from immutable Registry template", "unavailable");
+}
+export async function nativeCapability(context, namespace) {
+    const node = namespaceNode(namespace), nodeArg = sc.bytes(node);
+    const registrar = address(await context.read(context.registryId, "registrar_of", [nodeArg]), "contract", "namespace Registrar");
+    const instance = await context.server.getContractInstance(registrar);
+    if (instance.executable.type === "contractExecutableWasm" && hex(instance.executable.wasmHash.value) === LEGACY_REGISTRAR_HASH)
+        return { supported: false, registrar, reason: "legacy-template" };
+    await verifyRegistrarProvenance(context, registrar, hex(node));
+    const version = await context.read(registrar, "claim_version", []);
+    if (typeof version !== "number" || !Number.isInteger(version))
+        throw new NativeClaimError("malformed native claim capability", "unavailable");
+    if (version !== 1)
+        return { supported: false, registrar, reason: "unsupported-version" };
+    const [pair, epoch, owner, anchors] = await Promise.all([
+        context.read(context.registryId, "native_contracts", [nodeArg]), context.read(context.registryId, "owner_epoch", [nodeArg]),
+        context.read(context.registryId, "owner_of", [nodeArg]), context.read(registrar, "anchors", []),
+    ]);
+    if (!Array.isArray(pair) || pair.length !== 2 || pair[0] !== registrar)
+        throw new NativeClaimError("native contract binding does not match Registrar", "unavailable");
+    const resolver = address(pair[1], "contract", "native Resolver");
+    if (!Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== context.registryId || !(anchors[1] instanceof Uint8Array) || hex(anchors[1]) !== hex(node))
+        throw new NativeClaimError("Registrar anchors differ from selected namespace", "unavailable");
+    if (typeof epoch !== "bigint" || epoch < 1n)
+        throw new NativeClaimError("invalid namespace ownership epoch", "unavailable");
+    if (await context.read(resolver, "initialization_version", []) !== 1)
+        throw new NativeClaimError("unsupported native Resolver initializer", "unsupported");
+    return { supported: true, version: 1, registrar, resolver, registry: context.registryId, namespace, owner: address(owner, "identity", "namespace owner"), ownerEpoch: epoch };
+}
+export async function requireNative(context, namespace) {
+    const capability = await nativeCapability(context, namespace);
+    if (!capability.supported)
+        throw new NativeClaimError(`namespace has no supported native claim interface (${capability.reason})`, "unsupported");
+    return capability;
+}
+export async function prepareNative(context, plan, options = {}) {
+    const source = address(await context.signer.publicKey(), "account", "transaction signer");
+    if (source !== plan.source)
+        throw new NativeClaimError("wallet changed since the intent was reviewed", "authorization");
+    const raw = new TransactionBuilder(await context.server.getAccount(source), { fee: context.fee, networkPassphrase: context.passphrase })
+        .addOperation(new Contract(plan.contract).call(plan.method, ...plan.args)).setTimeout(context.timeoutSecs).build();
+    const simulate = async (tx) => {
+        const result = await context.server.simulateTransaction(tx, undefined, undefined, false);
+        if (rpc.Api.isSimulationRestore(result))
+            throw new NativeClaimError("native operation requires storage restoration; review and restore separately before resuming this intent", "unavailable");
+        if (rpc.Api.isSimulationError(result))
+            throw new NativeClaimError(`${plan.method}: ${result.error}`, "failed");
+        if (!rpc.Api.isSimulationSuccess(result) || !result.result)
+            throw new NativeClaimError("native simulation returned no result", "unavailable");
+        return result;
+    };
+    let transaction = rpc.assembleTransaction(raw, await simulate(raw)).build();
+    validateNativeTransaction(transaction, plan, false);
+    if (options.eligibilityAuthorization) {
+        if (options.eligibilityAuthorization.length > 32768)
+            throw new NativeClaimError("eligibility authorization is too large", "authorization");
+        if (!plan.eligibility)
+            throw new NativeClaimError("this native operation does not require an app approver", "authorization");
+        const signed = xdr.SorobanAuthorizationEntry.fromXDR(options.eligibilityAuthorization, "base64");
+        validateEligibilityAuthorization(signed, plan.eligibility);
+        const op = transaction.operations[0];
+        if (op.type !== "invokeHostFunction")
+            throw new NativeClaimError("unexpected prepared operation");
+        const auth = (op.auth ?? []).map(entry => entry.credentials.type === "sorobanCredentialsSourceAccount" ? entry : signed);
+        transaction = TransactionBuilder.cloneFrom(transaction, { networkPassphrase: context.passphrase }).clearOperations().addOperation(Operation.invokeHostFunction({ func: op.func, auth })).build();
+        transaction = rpc.assembleTransaction(transaction, await simulate(transaction)).build();
+        validateNativeTransaction(transaction, plan);
+    }
+    const op = transaction.operations[0];
+    if (op.type !== "invokeHostFunction")
+        throw new NativeClaimError("unexpected native operation");
+    const approval = (op.auth ?? []).find(entry => entry.credentials.type !== "sorobanCredentialsSourceAccount");
+    return { transaction, prepared: { transactionXdr: transaction.toXDR(), hash: hex(transaction.hash()), networkPassphrase: context.passphrase, feeStroops: BigInt(transaction.fee), eligibilityEntryXdr: approval?.toXDR("base64") ?? null } };
+}
+/** No automatic transaction retry, implicit restoration or hash-losing error path. */
+export async function sendNative(context, plan, options = {}) {
+    const { transaction, prepared } = await prepareNative(context, plan, options);
+    validateNativeTransaction(transaction, plan);
+    await options.onPrepared?.(prepared);
+    if (await context.signer.publicKey() !== plan.source)
+        throw new NativeClaimError("wallet changed before signing", "authorization");
+    const result = await context.signer.signTransaction(prepared.transactionXdr, { networkPassphrase: context.passphrase });
+    const signed = assertSignedBodyUnchanged(transaction, typeof result === "string" ? result : result.signedTxXdr, context.passphrase);
+    try {
+        const sent = await context.server.sendTransaction(signed);
+        if (sent.hash !== prepared.hash)
+            throw new NativeClaimError("RPC returned a different transaction hash", "pending", prepared.hash);
+        if (sent.status === "ERROR" || sent.status === "TRY_AGAIN_LATER")
+            throw new NativeClaimError(`transaction was not accepted (${sent.status}); reconcile the original receipt and hash`, "pending", prepared.hash);
+        for (let attempt = 0; attempt < context.timeoutSecs + 5; attempt++) {
+            const receipt = await context.server.getTransaction(prepared.hash);
+            if (receipt.status === "SUCCESS" || receipt.status === "FAILED") {
+                // Status alone cannot identify the reviewed transaction or establish inclusion.
+                validateNativeTerminalReceipt(receipt, prepared.hash, context.passphrase);
+                if (receipt.status === "SUCCESS")
+                    return { hash: prepared.hash, ledger: receipt.ledger, value: receipt.returnValue ? scValToNative(receipt.returnValue) : null };
+                throw new NativeClaimError("native transaction failed on chain", "failed", prepared.hash);
+            }
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+        throw new NativeClaimError("transaction outcome is unknown; recover the original receipt and hash before replacing the request", "pending", prepared.hash);
+    }
+    catch (error) {
+        if (error instanceof NativeClaimError && error.txHash)
+            throw error;
+        throw new NativeClaimError(`submission/confirmation interrupted: ${String(error)}; reconcile the original receipt`, "pending", prepared.hash);
+    }
+}
+/** Bind terminal RPC context before classifying success or failure. An incomplete response remains uncertain. */
+export function validateNativeTerminalReceipt(receipt, expectedHash, passphrase) {
+    try {
+        if (receipt.txHash !== expectedHash || !Number.isInteger(receipt.ledger) || receipt.ledger <= 0 || receipt.ledger > 0xffff_ffff || !receipt.envelopeXdr)
+            throw new Error("missing or mismatched hash/ledger/envelope");
+        const included = TransactionBuilder.fromXDR(receipt.envelopeXdr, passphrase);
+        if (!(included instanceof Transaction) || hex(included.hash()) !== expectedHash)
+            throw new Error("different included envelope");
+    }
+    catch {
+        throw new NativeClaimError("terminal RPC response does not prove inclusion of the original reviewed transaction; reconcile its hash", "pending", expectedHash);
+    }
+}