@sorandomains/owner 0.6.0 → 0.7.0

package/README.md

@@ -1,14 +1,14 @@
 # @sorandomains/owner
 
-> Native muxed release. The testnet deployment below was verified on chain at
-> ledger 4521644 on 5 September 2026 (18:10 UTC). See the
+
+> Native claim testnet deployment verified at ledger 4534629 on 6 September 2026 (12:12 UTC). See the
 > [release status](https://docs.soran.domains/reference/release-status) for package and service availability.
 
 
-Version 0.6.0 targets Stellar SDK17 (`>=17 <18`). ASCII names
+Version 0.7.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.6.0.
+Lookup is the read entry point in `@sorandomains/lookup` 0.7.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
@@ -83,13 +83,20 @@ code at all.
 
 Docs: <https://github.com/SoranDomains/docs> · License: MIT
 
+
+## Native username claiming
+
+`claimPolicy` and `nativeClaimCapability` read the current on-chain setup. Configure it with `configureClaims`, `setClaimsEnabled`/`pauseClaims`, `reserveNames`, `releaseReservations` and `assignReserved`. Manual mode retains ordinary owner issuance; Public mode routes ordinary issuance through the public claim rules, while explicit reserved assignment remains an owner power. The default disabled policy is not an open registration service.
+
+Read the [native claim APIs, security boundaries and complete signup flow](https://github.com/SoranDomains/sdk/blob/main/NATIVE-CLAIMS.md). G/no memo, G with ID/Text/Hash, full M/no separate memo and C/no memo remain supported payment destinations. Current transaction-signing adapters use classic G accounts.
+
 ## Verified testnet deployment
 
-Verified on 5 September 2026 at ledger **4521644** (18:10 UTC). Network passphrase: `Test SDF Network ; September 2015`.
+Verified on 6 September 2026 at ledger **4534629** (12:12 UTC). Network passphrase: `Test SDF Network ; September 2015`.
 
 | Contract | Address |
 |---|---|
-| Registry | `CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H` |
+| Registry | `CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK` |
 
 Mainnet has no deployment preset. Custom networks must supply their own verified
 addresses. Universal Lookup upgrades remain immediately executable; an address

package/dist/index.d.ts

@@ -35,9 +35,24 @@
  * that one only. The few reads here (policy, pending transfers, records) exist
  * to support write flows.
  */
+import { type NativeWriteOptions, type NativeCapability } from "./native-transport.js";
+import { type ClaimSettings, type ClaimConfig, type ClaimUsage, type ApprovalUsage } from "./native-types.js";
+export * from "./native-types.js";
+export * from "./native-allowlist.js";
+export { NativeClaimError, namespaceNode as nativeNamespaceNode, paymentDestinationToScVal } from "./native-codec.js";
+export { validateNativeTransaction, authorizedInvocation, type NativeAuthorizationPlan } from "./native-auth.js";
+export type { NativeCapability, NativePrepared, NativeWriteOptions } from "./native-transport.js";
 /** Known public deployments. Pass explicit options for anything else. */
 export declare const DEPLOYMENTS: {
     readonly testnet: {
+        readonly rpcUrl: "https://soroban-testnet.stellar.org";
+        readonly passphrase: string;
+        readonly registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK";
+    };
+};
+/** Explicit historical deployment access. Names in different Registries are separate identities; never a fallback. */
+export declare const LEGACY_DEPLOYMENTS: {
+    readonly testnet20260905: {
         readonly rpcUrl: "https://soroban-testnet.stellar.org";
         readonly passphrase: string;
         readonly registryId: "CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H";
@@ -130,6 +145,8 @@ export type NameState = {
     generation: bigint;
 };
 export type OwnerOptions = {
+    /** Upper total network fee for successor native operations; default 5 XLM. */
+    maxNativeFeeStroops?: bigint;
     /** Signs every transaction. The namespace owner's account — or, for
      *  `acceptNamespaceTransfer`, the proposed new owner's. */
     signer: TxSigner;
@@ -150,6 +167,7 @@ export type OwnerOptions = {
     fee?: string;
 };
 export declare class SoranOwner {
+    private maxNativeFeeStroops;
     private server;
     private passphrase;
     private registryId;
@@ -161,6 +179,38 @@ export declare class SoranOwner {
     private static REGISTRAR_TTL_MS;
     constructor(opts: OwnerOptions);
     /** The namespace's on-chain attested Registrar id. Cached per instance. */
+    private nativeConfirmed;
+    private nativeContext;
+    /** Native successor capability. A failed RPC read never means open or legacy. */
+    nativeClaimCapability(namespace: string): Promise<NativeCapability>;
+    claimPolicy(namespace: string): Promise<ClaimConfig | null>;
+    nativeClaimFeeToken(namespace: string): Promise<string>;
+    private nativeOwnerWrite;
+    configureClaims(namespace: string, settings: ClaimSettings, options?: NativeWriteOptions): Promise<Submitted & {
+        config: ClaimConfig;
+    }>;
+    setClaimsEnabled(namespace: string, enabled: boolean, options?: NativeWriteOptions): Promise<Submitted & {
+        config: ClaimConfig;
+    }>;
+    pauseClaims(namespace: string, options?: NativeWriteOptions): Promise<Submitted & {
+        config: ClaimConfig;
+    }>;
+    private updateReservations;
+    reserveNames(namespace: string, labels: readonly string[], options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        updated: number;
+    }>;
+    releaseReservations(namespace: string, labels: readonly string[], options?: NativeWriteOptions): Promise<{
+        hash: string;
+        ledger: number;
+        updated: number;
+    }>;
+    isReserved(namespace: string, label: string): Promise<boolean>;
+    /** Privileged reserved assignment publishes the holder's default route; no custom destination is implied. */
+    assignReserved(namespace: string, label: string, holder: string, options?: NativeWriteOptions): Promise<IssueResult>;
+    nativeClaimUsage(namespace: string, holder: string): Promise<ClaimUsage>;
+    nativeApprovalUsage(namespace: string): Promise<ApprovalUsage>;
     registrarOf(namespace: string): Promise<string>;
     /** The namespace's current owner on the Registry, or null if unallocated. */
     namespaceOwner(namespace: string): Promise<string | null>;

package/dist/index.js

@@ -84,12 +84,29 @@ function decodeIssuedEvents(events, registrarId) {
     }
     return out;
 }
+import { NativeClaimError, address as nativeAddress, bool as nativeBool, bytes32 as nativeBytes32, hex as nativeHex, sc as nativeSc } from "./native-codec.js";
+import { requireNative, nativeCapability, sendNative } from "./native-transport.js";
+import { claimSettingsToScVal, claimConfigFromNative, claimLabelToScVal, claimUsageFromNative, approvalUsageFromNative } from "./native-types.js";
+export * from "./native-types.js";
+export * from "./native-allowlist.js";
+export { NativeClaimError, namespaceNode as nativeNamespaceNode, paymentDestinationToScVal } from "./native-codec.js";
+export { validateNativeTransaction, authorizedInvocation } from "./native-auth.js";
 // ---------------------------------------------------------------------------
 // Deployments
 // ---------------------------------------------------------------------------
 /** Known public deployments. Pass explicit options for anything else. */
 export const DEPLOYMENTS = {
     testnet: {
+        rpcUrl: "https://soroban-testnet.stellar.org",
+        passphrase: Networks.TESTNET,
+        // The immutable Registry. The Registrar for a namespace is discovered on
+        // chain via `registrar_of(node)` — never configured by hand.
+        registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK",
+    },
+};
+/** Explicit historical deployment access. Names in different Registries are separate identities; never a fallback. */
+export const LEGACY_DEPLOYMENTS = {
+    testnet20260905: {
         rpcUrl: "https://soroban-testnet.stellar.org",
         passphrase: Networks.TESTNET,
         // The immutable Registry. The Registrar for a namespace is discovered on
@@ -134,6 +151,7 @@ const REGISTRAR_ERRORS = {
     18: "InvalidPolicy",
     19: "ExpiryOverflow",
     20: "InvalidRegistry",
+    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",
 };
 /** Registry contract error codes, by number. */
 const REGISTRY_ERRORS = {
@@ -256,6 +274,7 @@ export const MAX_BATCH = 23;
 // The client
 // ---------------------------------------------------------------------------
 export class SoranOwner {
+    maxNativeFeeStroops;
     server;
     passphrase;
     registryId;
@@ -271,6 +290,9 @@ export class SoranOwner {
     registrars = new Map();
     static REGISTRAR_TTL_MS = 30_000;
     constructor(opts) {
+        this.maxNativeFeeStroops = opts?.maxNativeFeeStroops ?? 50000000n;
+        if (typeof this.maxNativeFeeStroops !== "bigint" || this.maxNativeFeeStroops <= 0n || this.maxNativeFeeStroops > 4294967295n)
+            throw new NativeClaimError("maximum native network fee must be positive");
         if (!opts?.signer)
             throw new OwnerError("OwnerOptions.signer is required");
         const d = DEPLOYMENTS[opts.network ?? "testnet"];
@@ -290,6 +312,85 @@ export class SoranOwner {
     }
     // ---- discovery -----------------------------------------------------------
     /** The namespace's on-chain attested Registrar id. Cached per instance. */
+    nativeConfirmed(result, decode) {
+        try {
+            return decode(result.value);
+        }
+        catch (error) {
+            throw new NativeClaimError(`transaction confirmed but its result could not be verified: ${String(error)}`, "pending", result.hash);
+        }
+    }
+    nativeContext() {
+        return { registryId: this.registryId, passphrase: this.passphrase, server: this.server, signer: this.signer, fee: this.fee, timeoutSecs: this.timeoutSecs, maxFeeStroops: this.maxNativeFeeStroops,
+            read: (id, method, args) => this.read(id, method, args), serialize: work => this.serialize(work) };
+    }
+    /** Native successor capability. A failed RPC read never means open or legacy. */
+    nativeClaimCapability(namespace) { return nativeCapability(this.nativeContext(), normalizeLabel(namespace)); }
+    async claimPolicy(namespace) {
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        const raw = await this.read(cap.registrar, "claim_config", []);
+        return raw === null ? null : claimConfigFromNative(raw);
+    }
+    async nativeClaimFeeToken(namespace) {
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        return nativeAddress(await this.read(cap.registrar, "native_fee_token", []), "contract", "native XLM token");
+    }
+    async nativeOwnerWrite(namespace, method, args, options = {}) {
+        return this.serialize(async () => {
+            const context = this.nativeContext();
+            const cap = await requireNative(context, normalizeLabel(namespace));
+            const source = nativeAddress(await this.signer.publicKey(), "account", "owner transaction source");
+            if (cap.owner !== source)
+                throw new NativeClaimError("the current namespace owner must authorize this change", "authorization");
+            return sendNative(context, { source, contract: cap.registrar, method, args, sourceInvocation: { contract: cap.registrar, method, args }, maxFeeStroops: context.maxFeeStroops }, options);
+        });
+    }
+    async configureClaims(namespace, settings, options = {}) {
+        const encoded = claimSettingsToScVal(settings);
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        const token = nativeAddress(await this.read(cap.registrar, "native_fee_token", []), "contract", "native fee token");
+        if (settings.feeToken !== token)
+            throw new NativeClaimError("username fee must use this network's canonical XLM token");
+        if (settings.admission.type === "approval" && settings.admission.account === cap.owner)
+            throw new NativeClaimError("eligibility account must be separate from namespace owner");
+        const result = await this.nativeOwnerWrite(namespace, "configure_claims", [encoded], options);
+        return { hash: result.hash, ledger: result.ledger, config: this.nativeConfirmed(result, claimConfigFromNative) };
+    }
+    async setClaimsEnabled(namespace, enabled, options = {}) {
+        const result = await this.nativeOwnerWrite(namespace, "set_claim_enabled", [nativeSc.bool(nativeBool(enabled, "claim enabled"))], options);
+        return { hash: result.hash, ledger: result.ledger, config: this.nativeConfirmed(result, claimConfigFromNative) };
+    }
+    pauseClaims(namespace, options = {}) { return this.setClaimsEnabled(namespace, false, options); }
+    async updateReservations(namespace, labels, reserved, options) {
+        if (!Array.isArray(labels) || labels.length < 1 || labels.length > 23)
+            throw new NativeClaimError("reservation batches must contain 1–23 labels");
+        const normalized = labels.map(normalizeLabel);
+        if (new Set(normalized).size !== normalized.length)
+            throw new NativeClaimError("duplicate reservation label");
+        const result = await this.nativeOwnerWrite(namespace, "set_reserved", [xdr.ScVal.scvVec(normalized.map(claimLabelToScVal)), nativeSc.bool(reserved)], options);
+        if (typeof result.value !== "number" || result.value !== normalized.length)
+            throw new NativeClaimError("confirmed reservation result differs from batch; inspect the transaction before retrying", "pending", result.hash);
+        return { hash: result.hash, ledger: result.ledger, updated: result.value };
+    }
+    reserveNames(namespace, labels, options = {}) { return this.updateReservations(namespace, labels, true, options); }
+    releaseReservations(namespace, labels, options = {}) { return this.updateReservations(namespace, labels, false, options); }
+    async isReserved(namespace, label) {
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        return nativeBool(await this.read(cap.registrar, "is_reserved", [claimLabelToScVal(normalizeLabel(label))]), "reservation");
+    }
+    /** Privileged reserved assignment publishes the holder's default route; no custom destination is implied. */
+    async assignReserved(namespace, label, holder, options = {}) {
+        const result = await this.nativeOwnerWrite(namespace, "issue_reserved", [claimLabelToScVal(normalizeLabel(label)), nativeSc.address(nativeAddress(holder, "identity", "reserved holder"))], options);
+        return { hash: result.hash, ledger: result.ledger, node: this.nativeConfirmed(result, raw => nativeHex(nativeBytes32(raw, "issued name node"))) };
+    }
+    async nativeClaimUsage(namespace, holder) {
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        return claimUsageFromNative(await this.read(cap.registrar, "claim_usage", [nativeSc.address(nativeAddress(holder, "identity", "holder"))]));
+    }
+    async nativeApprovalUsage(namespace) {
+        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
+        return approvalUsageFromNative(await this.read(cap.registrar, "approval_usage", []));
+    }
     async registrarOf(namespace) {
         namespace = normalizeLabel(namespace);
         const hit = this.registrars.get(namespace);
@@ -561,7 +662,7 @@ export class SoranOwner {
             throw new OwnerError(`${fn}: the on-chain entry is archived (rent lapsed) — any write operation restores it automatically, or restore/touch it first`, contractId, fn);
         }
         if (!rpc.Api.isSimulationSuccess(sim) || !sim.result?.retval)
-            return null;
+            throw new OwnerError(`${fn}: missing simulation return value`, contractId, fn);
         const v = scValToNative(sim.result.retval);
         return v === undefined ? null : v;
     }

package/dist/native-allowlist.d.ts

@@ -0,0 +1,21 @@
+export type ClaimAllowlistContext = {
+    network: string;
+    registry: string;
+    namespace: string;
+    registrar: string;
+};
+export type ClaimAllowlistBundle = {
+    version: 1;
+    context: ClaimAllowlistContext;
+    root: string;
+    entries: Array<{
+        account: string;
+        leaf: string;
+        proof: string[];
+    }>;
+};
+export declare function claimAllowlistLeaf(context: ClaimAllowlistContext, account: string): string;
+export declare function claimAllowlistParent(left: string, right: string): string;
+/** A complete list is required to generate a replacement root. Keep/distribute the returned proof bundle. */
+export declare function buildClaimAllowlist(context: ClaimAllowlistContext, accounts: readonly string[]): ClaimAllowlistBundle;
+export declare function verifyClaimAllowlistProof(context: ClaimAllowlistContext, account: string, proof: readonly string[], root: string): boolean;

package/dist/native-allowlist.js

@@ -0,0 +1,34 @@
+import { hash, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, hex, hex32, sc, unhex } from "./native-codec.js";
+export function claimAllowlistLeaf(context, account) {
+    return hex(hash(xdr.ScVal.scvVec([sc.symbol("allow_v1"), sc.bytes(unhex(context.network)), sc.address(address(context.registry, "contract", "Registry")), sc.bytes(unhex(context.namespace)), sc.address(address(context.registrar, "contract", "Registrar")), sc.address(address(account, "account", "allowlisted claimant"))]).toXDR()));
+}
+export function claimAllowlistParent(left, right) { hex32(left, "left leaf"); hex32(right, "right leaf"); const [first, second] = left < right ? [left, right] : [right, left]; const bytes = new Uint8Array(65); bytes[0] = 1; bytes.set(unhex(first), 1); bytes.set(unhex(second), 33); return hex(hash(bytes)); }
+/** A complete list is required to generate a replacement root. Keep/distribute the returned proof bundle. */
+export function buildClaimAllowlist(context, accounts) {
+    if (!Array.isArray(accounts) || accounts.length === 0 || accounts.length > 65536)
+        throw new NativeClaimError("allowlist requires 1–65536 distinct G accounts");
+    const unique = new Set();
+    const entries = accounts.map(account => { address(account, "account", "allowlisted claimant"); if (unique.has(account))
+        throw new NativeClaimError("duplicate allowlist account"); unique.add(account); return { account, leaf: claimAllowlistLeaf(context, account), proof: [] }; }).sort((a, b) => a.leaf.localeCompare(b.leaf));
+    let layer = entries.map((entry, index) => ({ hash: entry.leaf, indices: [index] }));
+    while (layer.length > 1) {
+        const next = [];
+        for (let i = 0; i < layer.length; i += 2) {
+            const left = layer[i], right = layer[i + 1];
+            if (!right) {
+                next.push(left);
+                continue;
+            }
+            for (const index of left.indices)
+                entries[index].proof.push(right.hash);
+            for (const index of right.indices)
+                entries[index].proof.push(left.hash);
+            next.push({ hash: claimAllowlistParent(left.hash, right.hash), indices: [...left.indices, ...right.indices] });
+        }
+        layer = next;
+    }
+    return { version: 1, context: { ...context }, root: layer[0].hash, entries };
+}
+export function verifyClaimAllowlistProof(context, account, proof, root) { hex32(root, "allowlist root"); if (!Array.isArray(proof) || proof.length > 32)
+    throw new NativeClaimError("allowlist proof exceeds 32 siblings"); return proof.reduce(claimAllowlistParent, claimAllowlistLeaf(context, account)) === root; }

package/dist/native-auth.d.ts

@@ -0,0 +1,31 @@
+import { Transaction, authorizeEntry, xdr } from "@stellar/stellar-sdk";
+export type NativeInvocation = {
+    contract: string;
+    method: string;
+    args: xdr.ScVal[];
+    children?: NativeInvocation[];
+};
+/** Derive this plan locally from a validated intent, never from a remote envelope. */
+export type NativeAuthorizationPlan = {
+    source: string;
+    contract: string;
+    method: string;
+    args: xdr.ScVal[];
+    sourceInvocation: NativeInvocation;
+    eligibility?: {
+        account: string;
+        invocation: NativeInvocation;
+        latestLedger: number;
+        maxExpirationLedger: number;
+    };
+    maxFeeStroops: bigint;
+};
+export declare function authorizedInvocation(value: NativeInvocation): xdr.SorobanAuthorizedInvocation;
+export declare function validateEligibilityAuthorization(entry: xdr.SorobanAuthorizationEntry, expected: NonNullable<NativeAuthorizationPlan["eligibility"]>, requireSigned?: boolean): void;
+/** Native account signing callback; hardware/custody integration keeps keys outside the SDK. */
+export type EligibilitySigner = Parameters<typeof authorizeEntry>[1];
+/** Signs only the expected admission entry. This helper never signs a transaction. */
+export declare function signEligibilityAuthorization(unsignedEntry: xdr.SorobanAuthorizationEntry, expected: NonNullable<NativeAuthorizationPlan["eligibility"]>, signer: EligibilitySigner, expirationLedger: number, networkPassphrase: string): Promise<xdr.SorobanAuthorizationEntry>;
+/** Exact local intent and native role scope; does not relax ordinary SDK authorization. */
+export declare function validateNativeTransaction(tx: Transaction, plan: NativeAuthorizationPlan, requireEligibilitySigned?: boolean): void;
+export declare function assertSignedBodyUnchanged(prepared: Transaction, signedXdr: string, passphrase: string): Transaction;

package/dist/native-auth.js

@@ -0,0 +1,85 @@
+import { Address, Transaction, TransactionBuilder, authorizeEntry, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, hex, u32 } from "./native-codec.js";
+export function authorizedInvocation(value) {
+    return new xdr.SorobanAuthorizedInvocation({
+        function: xdr.SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(new xdr.InvokeContractArgs({
+            contractAddress: new Address(address(value.contract, "contract", "invocation contract")).toScAddress(), functionName: value.method, args: value.args,
+        })), subInvocations: (value.children ?? []).map(authorizedInvocation),
+    });
+}
+function sameInvocation(actual, expected) {
+    return actual.toXDR("base64") === authorizedInvocation(expected).toXDR("base64");
+}
+export function validateEligibilityAuthorization(entry, expected, requireSigned = true) {
+    if (expected.invocation.method !== "claim" || expected.invocation.args.length !== 1 || (expected.invocation.children?.length ?? 0) !== 0)
+        throw new NativeClaimError("eligibility may authorize only one exact native claim intent", "authorization");
+    address(expected.account, "account", "eligibility account");
+    u32(expected.latestLedger, "latest ledger");
+    u32(expected.maxExpirationLedger, "maximum auth expiration ledger");
+    if (entry.credentials.type !== "sorobanCredentialsAddress")
+        throw new NativeClaimError("eligibility requires the supported native G address credential", "authorization");
+    const credential = entry.credentials.address;
+    if (Address.fromScAddress(credential.address).toString() !== expected.account || !sameInvocation(entry.rootInvocation, expected.invocation) || entry.rootInvocation.subInvocations.length !== 0)
+        throw new NativeClaimError("eligibility authorization differs from the exact claim intent", "authorization");
+    if (requireSigned) {
+        if (credential.signatureExpirationLedger <= expected.latestLedger || credential.signatureExpirationLedger > expected.maxExpirationLedger)
+            throw new NativeClaimError("eligibility authorization expiry is outside the approved ledger bound", "authorization");
+        if (credential.signature.type !== "scvVec" || !credential.signature.vec?.length)
+            throw new NativeClaimError("eligibility authorization has no native account signatures", "authorization");
+    }
+    else if (credential.signature.type !== "scvVoid" && !(credential.signature.type === "scvVec" && credential.signature.vec?.length === 0)) {
+        throw new NativeClaimError("refusing to sign an already signed eligibility credential", "authorization");
+    }
+}
+/** Signs only the expected admission entry. This helper never signs a transaction. */
+export async function signEligibilityAuthorization(unsignedEntry, expected, signer, expirationLedger, networkPassphrase) {
+    validateEligibilityAuthorization(unsignedEntry, expected, false);
+    u32(expirationLedger, "expiration ledger");
+    if (expirationLedger <= expected.latestLedger || expirationLedger > expected.maxExpirationLedger)
+        throw new NativeClaimError("eligibility expiration is outside the approved range", "authorization");
+    if (!networkPassphrase)
+        throw new NativeClaimError("network passphrase is required");
+    const signed = await authorizeEntry(unsignedEntry, signer, expirationLedger, networkPassphrase);
+    validateEligibilityAuthorization(signed, expected);
+    return signed;
+}
+/** Exact local intent and native role scope; does not relax ordinary SDK authorization. */
+export function validateNativeTransaction(tx, plan, requireEligibilitySigned = true) {
+    address(plan.source, "account", "claim transaction source");
+    if (tx.source !== plan.source)
+        throw new NativeClaimError(`native transaction source ${tx.source} differs from reviewed source ${plan.source}`, "authorization");
+    if (tx.operations.length !== 1)
+        throw new NativeClaimError(`native transaction has ${tx.operations.length} operations; exactly one was reviewed`, "authorization");
+    if (tx.memo.type !== "none")
+        throw new NativeClaimError(`native transaction memo type ${tx.memo.type} differs from reviewed none`, "authorization");
+    if (BigInt(tx.fee) > plan.maxFeeStroops)
+        throw new NativeClaimError(`native transaction network fee ${tx.fee} stroops exceeds the configured maximum ${plan.maxFeeStroops} stroops`, "authorization");
+    const op = tx.operations[0];
+    if (op.type !== "invokeHostFunction" || op.source && op.source !== plan.source || op.func.type !== "hostFunctionTypeInvokeContract")
+        throw new NativeClaimError("unexpected native operation", "authorization");
+    const call = op.func.invokeContract;
+    if (Address.fromScAddress(call.contractAddress).toString() !== plan.contract || call.functionName.toString() !== plan.method || call.args.length !== plan.args.length || call.args.some((arg, i) => arg.toXDR("base64") !== plan.args[i].toXDR("base64")))
+        throw new NativeClaimError("native operation differs from the exact reviewed intent", "authorization");
+    const entries = op.auth ?? [];
+    if (entries.length !== (plan.eligibility ? 2 : 1))
+        throw new NativeClaimError("unexpected native authorization count", "authorization");
+    const sources = entries.filter(entry => entry.credentials.type === "sorobanCredentialsSourceAccount");
+    if (sources.length !== 1 || !sameInvocation(sources[0].rootInvocation, plan.sourceInvocation))
+        throw new NativeClaimError("holder or owner authorization differs from exact reviewed intent", "authorization");
+    if (plan.eligibility) {
+        if (plan.eligibility.account === plan.source)
+            throw new NativeClaimError("eligibility account must be separate from claimant", "authorization");
+        const separate = entries.filter(entry => entry.credentials.type !== "sorobanCredentialsSourceAccount");
+        if (separate.length !== 1)
+            throw new NativeClaimError("unexpected second authorizer", "authorization");
+        validateEligibilityAuthorization(separate[0], plan.eligibility, requireEligibilitySigned);
+    }
+}
+export function assertSignedBodyUnchanged(prepared, signedXdr, passphrase) {
+    const signed = TransactionBuilder.fromXDR(signedXdr, passphrase);
+    if (!(signed instanceof Transaction) || hex(signed.hash()) !== hex(prepared.hash()))
+        throw new NativeClaimError("wallet changed the reviewed native transaction body", "authorization");
+    if (!signed.signatures.length)
+        throw new NativeClaimError("wallet returned an unsigned transaction", "authorization");
+    return signed;
+}

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-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);
+    }
+}

package/dist/native-types.d.ts

@@ -0,0 +1,166 @@
+import { xdr } from "@stellar/stellar-sdk";
+import { type PaymentDestination } from "./payment.js";
+export type ClaimAdmission = {
+    type: "open";
+} | {
+    type: "allowlist";
+    root: string;
+} | {
+    type: "approval";
+    account: string;
+};
+export type ClaimSettings = {
+    mode: "manual" | "public";
+    enabled: boolean;
+    admission: ClaimAdmission;
+    feeToken: string;
+    feeAmount: bigint;
+    feeRecipient: string;
+    walletLimit: bigint;
+    approvalAllowance: bigint;
+    approvalRateLimit: bigint;
+    approvalWindowSecs: bigint;
+    approvalTtlSecs: bigint;
+};
+export type ClaimConfig = {
+    settings: ClaimSettings;
+    ownerEpoch: bigint;
+    policyVersion: bigint;
+    grantEpoch: bigint;
+};
+export type RequestContext = {
+    network: string;
+    registry: string;
+    registrar: string;
+    namespace: string;
+    requestId: string;
+    validAfter: bigint;
+    deadline: bigint;
+};
+export type ClaimIntent = {
+    context: RequestContext;
+    label: string;
+    claimant: string;
+    destination: PaymentDestination;
+    resolver: string;
+    expectedGeneration: bigint | null;
+    expectedExpiry: bigint | null;
+    termSecs: bigint;
+    ownerEpoch: bigint;
+    policyVersion: bigint;
+    grantEpoch: bigint;
+    feeToken: string;
+    feeAmount: bigint;
+    feeRecipient: string;
+};
+export type ReservedIntent = {
+    context: RequestContext;
+    label: string;
+    holder: string;
+    destination: PaymentDestination;
+    resolver: string;
+    expectedGeneration: bigint | null;
+    expectedExpiry: bigint | null;
+    termSecs: bigint;
+    ownerEpoch: bigint;
+    policyVersion: bigint;
+};
+export type TransferIntent = {
+    context: RequestContext;
+    label: string;
+    from: string;
+    to: string;
+    expectedGeneration: bigint;
+    expectedExpiry: bigint;
+    proposalExpires: bigint;
+    destination: PaymentDestination;
+    resolver: string;
+};
+export type RenewIntent = {
+    context: RequestContext;
+    label: string;
+    holder: string;
+    expectedGeneration: bigint;
+    expectedExpiry: bigint;
+    termSecs: bigint;
+    minNewExpiry: bigint;
+    maxNewExpiry: bigint;
+};
+export type ClaimReceipt = {
+    operation: "claim" | "reserved" | "transfer" | "renew";
+    intentHash: string;
+    node: string;
+    holder: string;
+    generation: bigint;
+    expiresAt: bigint;
+    feeAmount: bigint;
+    feeToken: string;
+    feeRecipient: string | null;
+    ledger: number;
+    timestamp: bigint;
+};
+export type ClaimResult = {
+    status: "fresh" | "replayed";
+    receipt: ClaimReceipt;
+};
+export type ClaimUsage = {
+    publicClaims: bigint;
+    reservedIssues: bigint;
+};
+export type ApprovalUsage = {
+    total: bigint;
+    windowUsed: bigint;
+    windowEnds: bigint;
+};
+export type ClaimQuote = {
+    network: string;
+    registry: string;
+    registrar: string;
+    namespace: string;
+    resolver: string;
+    label: string;
+    node: string;
+    claimant: string;
+    config: ClaimConfig | null;
+    ownerEpoch: bigint;
+    policyVersion: bigint;
+    available: boolean;
+    reserved: boolean;
+    generation: bigint | null;
+    expiresAt: bigint | null;
+    termSecs: bigint;
+    now: bigint;
+    usage: ClaimUsage;
+    approvalUsage: ApprovalUsage;
+};
+export type DestinationPreview = {
+    node: string;
+    holder: string;
+    generation: bigint;
+    expiresAt: bigint;
+    active: boolean;
+    destination: PaymentDestination;
+};
+export declare function claimSettingsToScVal(value: ClaimSettings): xdr.ScVal;
+export declare const claimPolicyInputToScVal: typeof claimSettingsToScVal;
+export declare const claimLabelToScVal: (value: string) => xdr.ScVal;
+export declare const claimConfigFromNative: (value: unknown) => ClaimConfig;
+export declare const claimQuoteFromNative: (value: unknown) => ClaimQuote;
+export declare const claimUsageFromNative: (value: unknown) => ClaimUsage;
+export declare const approvalUsageFromNative: (value: unknown) => ApprovalUsage;
+export declare const destinationPreviewFromNative: (value: unknown) => DestinationPreview;
+export declare const claimReceiptFromNative: (value: unknown) => ClaimReceipt;
+export declare function claimIntentToScVal(value: ClaimIntent): xdr.ScVal;
+export declare function reservedIntentToScVal(value: ReservedIntent): xdr.ScVal;
+export declare function transferIntentToScVal(value: TransferIntent): xdr.ScVal;
+export declare function renewIntentToScVal(value: RenewIntent): xdr.ScVal;
+export declare const claimIntentFromNative: (value: unknown) => ClaimIntent;
+export declare const transferIntentFromNative: (value: unknown) => TransferIntent;
+export declare const renewIntentFromNative: (value: unknown) => RenewIntent;
+export declare function claimResultFromNative(value: unknown): ClaimResult;
+export declare function nativeIntentHash(method: "claim" | "issue_reserved_with_destination" | "accept_transfer_with_destination" | "renew_holder", value: xdr.ScVal): string;
+/** Lossless public recovery JSON; only declared bigint fields receive the tagged encoding. */
+export declare function stringifyNativeIntent(value: ClaimIntent | TransferIntent | RenewIntent | ReservedIntent): string;
+export declare function parseNativeClaimIntent(json: string): ClaimIntent;
+export declare function parseNativeTransferIntent(json: string): TransferIntent;
+export declare function parseNativeRenewIntent(json: string): RenewIntent;

package/dist/native-types.js

@@ -0,0 +1,98 @@
+import { hash, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { destinationFromNative } from "./payment.js";
+import { NativeClaimError, address, amount, bool, bytes32, exactObject, hex, hex32, label, paymentDestinationToScVal, sc, struct, u32, u64, unhex, utf8 } from "./native-codec.js";
+const primitive = (validate, encode) => ({ encode: v => encode(validate(v)), decode: validate });
+const U64 = primitive(v => u64(v, "u64 field"), sc.u64), U32 = primitive(v => u32(v, "u32 field"), sc.u32), AMOUNT = primitive(v => amount(v, "fee amount"), sc.i128), BOOL = primitive(v => bool(v, "boolean field"), sc.bool);
+const ACCOUNT = primitive(v => address(v, "account", "account"), sc.address), CONTRACT = primitive(v => address(v, "contract", "contract"), sc.address), IDENTITY = primitive(v => address(v, "identity", "identity"), sc.address);
+const HEX = { encode: v => sc.bytes(unhex(hex32(v, "bytes32 field"))), decode: v => hex(bytes32(v, "bytes32 field")) };
+const LABEL = { encode: v => sc.bytes(utf8(label(v))), decode: v => { if (!(v instanceof Uint8Array))
+        throw new NativeClaimError("label must be on-chain Bytes"); return label(new TextDecoder("utf-8", { fatal: true }).decode(v)); } };
+const DESTINATION = { encode: v => paymentDestinationToScVal(v), decode: destinationFromNative };
+const optional = (inner) => ({ encode: v => v === null ? sc.option(null) : inner.encode(v), decode: v => v === null || v === undefined ? null : inner.decode(v) });
+const enumeration = (mapping) => ({ encode: v => { if (typeof v !== "string" || !Object.hasOwn(mapping, v))
+        throw new NativeClaimError("unsupported enum value"); return xdr.ScVal.scvVec([sc.symbol(mapping[v])]); }, decode: v => { if (!Array.isArray(v) || v.length !== 1)
+        throw new NativeClaimError("invalid enum result"); const entry = Object.entries(mapping).find(([, tag]) => tag === v[0]); if (!entry)
+        throw new NativeClaimError("unknown enum tag"); return entry[0]; } });
+const ADMISSION = { encode: v => { if (!v || typeof v !== "object")
+        throw new NativeClaimError("invalid admission"); const a = v; if (a.type === "open") {
+        exactObject(a, ["type"], "open admission");
+        return xdr.ScVal.scvVec([sc.symbol("Open")]);
+    } if (a.type === "allowlist") {
+        exactObject(a, ["type", "root"], "allowlist admission");
+        return xdr.ScVal.scvVec([sc.symbol("Allowlist"), HEX.encode(a.root)]);
+    } if (a.type === "approval") {
+        exactObject(a, ["type", "account"], "approval admission");
+        return xdr.ScVal.scvVec([sc.symbol("Approval"), ACCOUNT.encode(a.account)]);
+    } throw new NativeClaimError("unsupported admission"); }, decode: v => { if (!Array.isArray(v))
+        throw new NativeClaimError("invalid admission enum"); if (v.length === 1 && v[0] === "Open")
+        return { type: "open" }; if (v.length === 2 && v[0] === "Allowlist")
+        return { type: "allowlist", root: HEX.decode(v[1]) }; if (v.length === 2 && v[0] === "Approval")
+        return { type: "approval", account: ACCOUNT.decode(v[1]) }; throw new NativeClaimError("unknown admission enum"); } };
+const snake = (s) => s.replace(/[A-Z]/g, c => "_" + c.toLowerCase());
+function model(fields) { return { encode: v => { const value = exactObject(v, Object.keys(fields), "native input"); return struct(Object.fromEntries(Object.entries(fields).map(([name, codec]) => [snake(name), codec.encode(value[name])]))); }, decode: v => { const value = exactObject(v, Object.keys(fields).map(snake), "native result"); return Object.fromEntries(Object.entries(fields).map(([name, codec]) => [name, codec.decode(value[snake(name)])])); } }; }
+const SETTINGS = model({ mode: enumeration({ manual: "Manual", public: "Public" }), enabled: BOOL, admission: ADMISSION, feeToken: CONTRACT, feeAmount: AMOUNT, feeRecipient: ACCOUNT, walletLimit: U64, approvalAllowance: U64, approvalRateLimit: U64, approvalWindowSecs: U64, approvalTtlSecs: U64 });
+const CONFIG = model({ settings: SETTINGS, ownerEpoch: U64, policyVersion: U64, grantEpoch: U64 });
+const CONTEXT = model({ network: HEX, registry: CONTRACT, registrar: CONTRACT, namespace: HEX, requestId: HEX, validAfter: U64, deadline: U64 });
+const CLAIM = model({ context: CONTEXT, label: LABEL, claimant: ACCOUNT, destination: DESTINATION, resolver: CONTRACT, expectedGeneration: optional(U64), expectedExpiry: optional(U64), termSecs: U64, ownerEpoch: U64, policyVersion: U64, grantEpoch: U64, feeToken: CONTRACT, feeAmount: AMOUNT, feeRecipient: ACCOUNT });
+const RESERVED = model({ context: CONTEXT, label: LABEL, holder: ACCOUNT, destination: DESTINATION, resolver: CONTRACT, expectedGeneration: optional(U64), expectedExpiry: optional(U64), termSecs: U64, ownerEpoch: U64, policyVersion: U64 });
+const TRANSFER = model({ context: CONTEXT, label: LABEL, from: IDENTITY, to: ACCOUNT, expectedGeneration: U64, expectedExpiry: U64, proposalExpires: U64, destination: DESTINATION, resolver: CONTRACT });
+const RENEW = model({ context: CONTEXT, label: LABEL, holder: ACCOUNT, expectedGeneration: U64, expectedExpiry: U64, termSecs: U64, minNewExpiry: U64, maxNewExpiry: U64 });
+const USAGE = model({ publicClaims: U64, reservedIssues: U64 }), APPROVAL_USAGE = model({ total: U64, windowUsed: U64, windowEnds: U64 });
+const CONFIG_STATE = { encode: v => v === null ? xdr.ScVal.scvVec([sc.symbol("Unconfigured")]) : xdr.ScVal.scvVec([sc.symbol("Configured"), CONFIG.encode(v)]), decode: v => { if (!Array.isArray(v))
+        throw new NativeClaimError("invalid claim config state"); if (v.length === 1 && v[0] === "Unconfigured")
+        return null; if (v.length === 2 && v[0] === "Configured")
+        return CONFIG.decode(v[1]); throw new NativeClaimError("invalid claim config state"); } };
+const QUOTE = model({ network: HEX, registry: CONTRACT, registrar: CONTRACT, namespace: HEX, resolver: CONTRACT, label: LABEL, node: HEX, claimant: ACCOUNT, config: CONFIG_STATE, ownerEpoch: U64, policyVersion: U64, available: BOOL, reserved: BOOL, generation: optional(U64), expiresAt: optional(U64), termSecs: U64, now: U64, usage: USAGE, approvalUsage: APPROVAL_USAGE });
+const RECEIPT = model({ operation: enumeration({ claim: "Claim", reserved: "Reserved", transfer: "Transfer", renew: "Renew" }), intentHash: HEX, node: HEX, holder: IDENTITY, generation: U64, expiresAt: U64, feeAmount: AMOUNT, feeToken: CONTRACT, feeRecipient: optional(ACCOUNT), ledger: U32, timestamp: U64 });
+const PREVIEW = model({ node: HEX, holder: IDENTITY, generation: U64, expiresAt: U64, active: BOOL, destination: DESTINATION });
+export function claimSettingsToScVal(value) {
+    const encoded = SETTINGS.encode(value);
+    if (value.admission.type === "approval") {
+        if (value.approvalAllowance === 0n || value.approvalRateLimit === 0n || value.approvalWindowSecs === 0n || value.approvalWindowSecs > 31536000n || value.approvalTtlSecs === 0n || value.approvalTtlSecs > 3600n)
+            throw new NativeClaimError("approval mode requires explicit bounded admission budgets, window and lifetime");
+        if (value.admission.account === value.feeRecipient)
+            throw new NativeClaimError("eligibility account must differ from fee treasury");
+    }
+    else if (value.approvalAllowance !== 0n || value.approvalRateLimit !== 0n || value.approvalWindowSecs !== 0n || value.approvalTtlSecs !== 0n)
+        throw new NativeClaimError("approval settings must be zero outside approval mode");
+    return encoded;
+}
+export const claimPolicyInputToScVal = claimSettingsToScVal;
+export const claimLabelToScVal = (value) => LABEL.encode(value);
+export const claimConfigFromNative = (value) => CONFIG.decode(value);
+export const claimQuoteFromNative = (value) => QUOTE.decode(value);
+export const claimUsageFromNative = (value) => USAGE.decode(value);
+export const approvalUsageFromNative = (value) => APPROVAL_USAGE.decode(value);
+export const destinationPreviewFromNative = (value) => PREVIEW.decode(value);
+export const claimReceiptFromNative = (value) => RECEIPT.decode(value);
+function validContext(c) { if (c.deadline <= c.validAfter || c.deadline - c.validAfter > 3600n)
+    throw new NativeClaimError("business intent lifetime must be positive and at most 3600 seconds"); }
+export function claimIntentToScVal(value) { const result = CLAIM.encode(value); validContext(value.context); if ((value.expectedGeneration === null) !== (value.expectedExpiry === null))
+    throw new NativeClaimError("generation and expiry expectations must both be present or absent"); return result; }
+export function reservedIntentToScVal(value) { const result = RESERVED.encode(value); validContext(value.context); if ((value.expectedGeneration === null) !== (value.expectedExpiry === null))
+    throw new NativeClaimError("generation and expiry expectations must both be present or absent"); return result; }
+export function transferIntentToScVal(value) { const result = TRANSFER.encode(value); validContext(value.context); return result; }
+export function renewIntentToScVal(value) { const result = RENEW.encode(value); validContext(value.context); if (value.termSecs === 0n || value.maxNewExpiry < value.minNewExpiry)
+    throw new NativeClaimError("invalid renewal bounds"); return result; }
+export const claimIntentFromNative = (value) => CLAIM.decode(value);
+export const transferIntentFromNative = (value) => TRANSFER.decode(value);
+export const renewIntentFromNative = (value) => RENEW.decode(value);
+export function claimResultFromNative(value) { if (!Array.isArray(value) || value.length !== 2 || !["Fresh", "Replayed"].includes(value[0]))
+    throw new NativeClaimError("invalid claim result"); return { status: value[0] === "Fresh" ? "fresh" : "replayed", receipt: claimReceiptFromNative(value[1]) }; }
+export function nativeIntentHash(method, value) { return hex(hash(xdr.ScVal.scvVec([sc.symbol(method), value]).toXDR())); }
+/** Lossless public recovery JSON; only declared bigint fields receive the tagged encoding. */
+export function stringifyNativeIntent(value) { return JSON.stringify(value, (_key, v) => typeof v === "bigint" ? { $u64: v.toString() } : v); }
+export function parseNativeClaimIntent(json) { if (json.length > 16384)
+    throw new NativeClaimError("claim recovery reference is too large"); const raw = JSON.parse(json, (_key, v) => { if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).join(",") === "$u64") {
+    if (typeof v.$u64 !== "string" || !/^(0|[1-9][0-9]*)$/.test(v.$u64))
+        throw new NativeClaimError("invalid recovery integer");
+    return BigInt(v.$u64);
+} return v; }); return claimIntentFromNative(scValToNative(claimIntentToScVal(raw))); }
+export function parseNativeTransferIntent(json) { return parseLifecycleIntent(json, TRANSFER, transferIntentToScVal); }
+export function parseNativeRenewIntent(json) { return parseLifecycleIntent(json, RENEW, renewIntentToScVal); }
+function parseLifecycleIntent(json, codec, encode) { if (json.length > 16384)
+    throw new NativeClaimError("lifecycle intent is too large"); const raw = JSON.parse(json, (_key, v) => { if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).join(",") === "$u64") {
+    if (typeof v.$u64 !== "string" || !/^(0|[1-9][0-9]*)$/.test(v.$u64))
+        throw new NativeClaimError("invalid recovery integer");
+    return BigInt(v.$u64);
+} return v; }); return codec.decode(scValToNative(encode(raw))); }

package/dist/payment.d.ts

@@ -0,0 +1,37 @@
+/** Direct v1 and muxed v2 payment records. Kept identical in the independently published lookup
+ * and holder packages; the conformance tests exercise both copies. */
+import { xdr } from "@stellar/stellar-sdk";
+export declare const PAYMENT_RECORD_KEY = "payment";
+export type PaymentMemo = {
+    type: "none";
+} | {
+    type: "id";
+    value: string;
+} | {
+    type: "text";
+    value: string;
+} | {
+    type: "hash";
+    value: string;
+};
+export type PaymentDestination = {
+    address: string;
+    memo: PaymentMemo;
+};
+/** Reject invalid data without normalizing meaningful memo bytes. */
+export declare function validatePaymentDestination(value: unknown): PaymentDestination;
+export declare function encodePaymentRecord(value: PaymentDestination): string;
+/** Empty/missing records are not explicit payment instructions. */
+export declare function parsePaymentRecord(raw: string): PaymentDestination;
+export declare function paymentMemoToScVal(memo: PaymentMemo): xdr.ScVal;
+/** Decode Soroban contract enum values, checking arity and native types. */
+export declare function paymentFromNative(raw: unknown): PaymentDestination;
+/** Decode a full muxed destination without treating its operation ID as a memo. */
+export declare function decodeMuxedAddress(address: string): {
+    account: string;
+    id: string;
+};
+/** Encode only canonical G + exact decimal u64; numbers are never accepted. */
+export declare function encodeMuxedAddress(account: string, id: string): string;
+/** Strict additive on-chain destination enum; v1 payment structs stay separate. */
+export declare function destinationFromNative(raw: unknown): PaymentDestination;

package/dist/payment.js

@@ -0,0 +1,148 @@
+/** Direct v1 and muxed v2 payment records. Kept identical in the independently published lookup
+ * and holder packages; the conformance tests exercise both copies. */
+import { StrKey, nativeToScVal, xdr } from "@stellar/stellar-sdk";
+export const PAYMENT_RECORD_KEY = "payment";
+const MAX_U64 = 18446744073709551615n;
+const utf8 = (value) => new TextEncoder().encode(value);
+/** Reject invalid data without normalizing meaningful memo bytes. */
+export function validatePaymentDestination(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid payment destination");
+    const p = value;
+    if (Object.keys(p).sort().join(",") !== "address,memo")
+        throw new Error("unexpected payment fields");
+    if (typeof p.address !== "string" || (!StrKey.isValidEd25519PublicKey(p.address) && !StrKey.isValidContract(p.address) && !StrKey.isValidMed25519PublicKey(p.address)))
+        throw new Error("payment address must be a valid G, C or M address");
+    if (!p.memo || typeof p.memo !== "object" || Array.isArray(p.memo))
+        throw new Error("invalid memo");
+    const m = p.memo;
+    if (m.type === "none") {
+        if (Object.keys(m).join(",") !== "type")
+            throw new Error("none memo cannot have a value");
+        if (StrKey.isValidMed25519PublicKey(p.address))
+            decodeMuxedAddress(p.address);
+        return { address: p.address, memo: { type: "none" } };
+    }
+    if (!StrKey.isValidEd25519PublicKey(p.address))
+        throw new Error("memos require a classic G address");
+    if (Object.keys(m).sort().join(",") !== "type,value" || typeof m.value !== "string")
+        throw new Error("memo value must be a string");
+    switch (m.type) {
+        case "id":
+            if (!/^(0|[1-9][0-9]{0,19})$/.test(m.value) || BigInt(m.value) > MAX_U64)
+                throw new Error("memo ID must be canonical decimal u64");
+            return { address: p.address, memo: { type: "id", value: m.value } };
+        case "text": {
+            const bytes = utf8(m.value);
+            if (!bytes.length || bytes.length > 28 || new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) !== m.value)
+                throw new Error("memo text must be valid UTF-8, 1–28 bytes");
+            return { address: p.address, memo: { type: "text", value: m.value } };
+        }
+        case "hash":
+            if (!/^[0-9a-f]{64}$/.test(m.value))
+                throw new Error("memo hash must be 32 bytes as lowercase hex");
+            return { address: p.address, memo: { type: "hash", value: m.value } };
+        default: throw new Error("unsupported memo type");
+    }
+}
+export function encodePaymentRecord(value) {
+    const p = validatePaymentDestination(value);
+    if (StrKey.isValidMed25519PublicKey(p.address)) {
+        const muxed = decodeMuxedAddress(p.address);
+        return `2|${muxed.account}|muxed|${muxed.id}`;
+    }
+    return `1|${p.address}|${p.memo.type}|${p.memo.type === "none" ? "" : p.memo.value}`;
+}
+/** Empty/missing records are not explicit payment instructions. */
+export function parsePaymentRecord(raw) {
+    if (typeof raw !== "string" || utf8(raw).length > 128)
+        throw new Error("invalid payment record length");
+    const first = raw.indexOf("|");
+    const second = raw.indexOf("|", first + 1);
+    const third = raw.indexOf("|", second + 1);
+    if (first < 0 || second < 0 || third < 0)
+        throw new Error("unsupported payment record");
+    const version = raw.slice(0, first);
+    const address = raw.slice(first + 1, second);
+    const type = raw.slice(second + 1, third);
+    const value = raw.slice(third + 1);
+    if (version === "2" && type === "muxed")
+        return { address: encodeMuxedAddress(address, value), memo: { type: "none" } };
+    if (version !== "1" || (!StrKey.isValidEd25519PublicKey(address) && !StrKey.isValidContract(address)))
+        throw new Error("unsupported payment record");
+    if (type === "none" && value !== "")
+        throw new Error("none memo cannot have a value");
+    return validatePaymentDestination({ address, memo: type === "none" ? { type } : { type, value } });
+}
+export function paymentMemoToScVal(memo) {
+    const symbol = (s) => nativeToScVal(s, { type: "symbol" });
+    switch (memo.type) {
+        case "none": return xdr.ScVal.scvVec([symbol("None")]);
+        case "id": return xdr.ScVal.scvVec([symbol("Id"), nativeToScVal(BigInt(memo.value), { type: "u64" })]);
+        case "text": return xdr.ScVal.scvVec([symbol("Text"), nativeToScVal(memo.value, { type: "string" })]);
+        case "hash": return xdr.ScVal.scvVec([symbol("Hash"), nativeToScVal(Uint8Array.from(memo.value.match(/../g), (b) => parseInt(b, 16)), { type: "bytes" })]);
+    }
+}
+/** Decode Soroban contract enum values, checking arity and native types. */
+export function paymentFromNative(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("invalid payment result");
+    const p = raw;
+    if (Object.keys(p).sort().join(",") !== "address,memo" || !Array.isArray(p.memo))
+        throw new Error("invalid payment result fields");
+    if (typeof p.address !== "string" || (!StrKey.isValidEd25519PublicKey(p.address) && !StrKey.isValidContract(p.address)))
+        throw new Error("direct payment must contain a G or C address");
+    const m = p.memo;
+    let memo;
+    if (m.length === 1 && m[0] === "None")
+        memo = { type: "none" };
+    else if (m.length === 2 && m[0] === "Id" && typeof m[1] === "bigint")
+        memo = { type: "id", value: m[1].toString() };
+    else if (m.length === 2 && m[0] === "Text" && typeof m[1] === "string")
+        memo = { type: "text", value: m[1] };
+    else if (m.length === 2 && m[0] === "Hash" && m[1] instanceof Uint8Array && m[1].length === 32)
+        memo = { type: "hash", value: Array.from(m[1], (b) => b.toString(16).padStart(2, "0")).join("") };
+    else
+        throw new Error("invalid payment memo result");
+    return validatePaymentDestination({ address: p.address, memo });
+}
+/** Decode a full muxed destination without treating its operation ID as a memo. */
+export function decodeMuxedAddress(address) {
+    if (typeof address !== "string" || !StrKey.isValidMed25519PublicKey(address))
+        throw new Error("invalid muxed M address");
+    const raw = StrKey.decodeMed25519PublicKey(address);
+    if (raw.length !== 40 || StrKey.encodeMed25519PublicKey(raw) !== address)
+        throw new Error("noncanonical muxed address");
+    let id = 0n;
+    for (const byte of raw.subarray(32))
+        id = (id << 8n) | BigInt(byte);
+    return { account: StrKey.encodeEd25519PublicKey(raw.subarray(0, 32)), id: id.toString() };
+}
+/** Encode only canonical G + exact decimal u64; numbers are never accepted. */
+export function encodeMuxedAddress(account, id) {
+    if (typeof account !== "string" || !StrKey.isValidEd25519PublicKey(account))
+        throw new Error("muxed base must be a G account");
+    if (typeof id !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(id) || BigInt(id) > MAX_U64)
+        throw new Error("muxed ID must be canonical decimal u64");
+    const raw = new Uint8Array(40);
+    raw.set(StrKey.decodeEd25519PublicKey(account));
+    let value = BigInt(id);
+    for (let i = 39; i >= 32; i--) {
+        raw[i] = Number(value & 255n);
+        value >>= 8n;
+    }
+    return StrKey.encodeMed25519PublicKey(raw);
+}
+/** Strict additive on-chain destination enum; v1 payment structs stay separate. */
+export function destinationFromNative(raw) {
+    if (!Array.isArray(raw) || raw.length !== 2)
+        throw new Error("invalid destination enum");
+    if (raw[0] === "Direct")
+        return paymentFromNative(raw[1]);
+    if (raw[0] !== "Muxed" || !raw[1] || typeof raw[1] !== "object" || Array.isArray(raw[1]))
+        throw new Error("invalid destination variant");
+    const value = raw[1];
+    if (Object.keys(value).sort().join(",") !== "account,id" || typeof value.account !== "string" || typeof value.id !== "bigint")
+        throw new Error("invalid muxed destination fields");
+    return { address: encodeMuxedAddress(value.account, value.id.toString()), memo: { type: "none" } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorandomains/owner",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Run your Soran namespace on Stellar \u2014 issue names, manage lifecycle, transfer, and walk the one-way permanence door.",
   "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": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/integration.test.mts test/native-*.test.mts"
   },
   "license": "MIT",
   "repository": {