@sorandomains/holder 0.3.1 → 0.5.0

package/README.md

@@ -1,9 +1,14 @@
 # @sorandomains/holder
 
-Version 0.3.1 targets Stellar SDK17 (`>=17 <18`). ASCII names
+
+> 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.5.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.5.1.
+Lookup is the read entry point in `@sorandomains/lookup` 0.7.0.
 
 Your Soran name, managed with your own key. The third piece of the SDK
 trilogy: [`@sorandomains/lookup`](https://www.npmjs.com/package/@sorandomains/lookup)
@@ -45,7 +50,12 @@ await me.setPayment("alice.nova", { address: myAddress, memo: { type: "none" } }
 
 ID values are canonical unsigned 64-bit decimal strings; text is exact nonempty
 UTF-8 up to 28 bytes; hashes are 64 lowercase hex characters. Required memos work
-only with G addresses. C addresses permit `none`. The Resolver authorizes the
+only with G addresses. C addresses permit `none`. A full muxed M address also
+requires `none`: its embedded ID belongs to the operation destination, not a
+transaction memo. On native Resolver v2, `setPayment` decodes M and signs
+`set_muxed(name, holder, baseG, exactU64Id)`; G/C uses `set_payment` as before.
+The signed authorization must match the exact selected call, base account and ID.
+A signer returning a different transaction body is rejected before submission. The Resolver authorizes the
 current holder and updates its records atomically. Failures never retry as separate
 address and text writes. Old unsupported Resolvers fail closed; no payment-specific
 contract address is configured.
@@ -53,17 +63,34 @@ contract address is configured.
 `setText` and `clearText` reserve `payment` for `setPayment`. Configured missing or
 empty instructions remain errors. Remove a memo with explicit `none`.
 `setRecord` invokes native `set_addr`, which atomically permits ordinary names and
-updates an existing valid `none` tuple while rejecting required memos or broken
+updates an existing valid direct `none` tuple while rejecting muxed routes, required memos or broken
 state. A concurrently added memo cannot be replaced by a client-side None rewrite.
 `setAddress` retains its Registrar-only semantics and first requires a valid native
-`none` result. It changes only the built-in target; an explicit Resolver payment
+direct `none` result. It changes only the built-in target; an explicit Resolver payment
 record continues to take precedence. Failed preflight reads never permit a write.
 
 Resolver selection follows the namespace owner's Registry pointer. Compatibility
 and anchor checks do not prove custom/upgraded code is trustworthy. Upgraded
 Resolvers remain supported. Payment readers must use `resolvePayment` and preserve
 the returned memo; old deployed code and direct Registrar reads cannot be upgraded
-by installing this SDK. The verified deployment used by this release is listed below.
+by installing this SDK. The verified deployment for this release is listed below.
+
+### Publish a muxed destination
+
+```ts
+await me.setPayment("customer420.nova", {
+  address: "MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAAAAAABUTGI4",
+  memo: { type: "none" },
+});
+```
+
+This illustrative M address contains the G account shown in Stellar's examples
+and ID 420. Publish only the actual route supplied by the recipient. No separate
+ID/text/hash memo is permitted. V1 Resolvers cannot store M and fail before signing.
+Use `setPayment` to explicitly replace or remove muxed routing; `setAddress` and
+`setRecord` remain G/C account-address operations. Namespace/name ownership,
+operator and signer addresses remain G/C. Muxed payment destinations do not act
+as separate reverse/Primary identities.
 
 ## What's in the box
 
@@ -113,14 +140,21 @@ Primary writes verify the Primary contract's Registry anchor before signing.
 Custom Registry or passphrase settings do not inherit a Primary deployment pin;
 supply the matching `primaryId` explicitly.
 
+
+## Native username claiming
+
+Native username claiming uses `claimQuote`, `createClaimIntent`, `buildClaim` and `claim`. The current namespace owner must first enable the public policy. The claimant's G wallet authorizes the exact username, complete receiving destination, owner price, policy version and deadline. `recoverClaim` reads the original immutable receipt; it never silently retries an uncertain transaction. `acceptNameTransferWithDestination` and `renewName` cover separately authorized holder lifecycle actions.
+
+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 2026-09-05 at ledger 4520986. 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 | `CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE` |
-| Primary | `CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X` |
+| Registry | `CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK` |
+| Primary | `CASORAN755O3GCQTRAHKDXLLCSDLNKAQWAP6MWABRSFVSHLJOEKAC7AB` |
 
 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

@@ -17,8 +17,9 @@
  * checks you hold the name (generation-gated) before accepting records, the
  * reverse and primary claims are authorized by the ADDRESS itself, and name
  * transfers move only when the recipient accepts. Namespace-owner powers
- * (issue, reclaim, renew, permanence) live in `@sorandomains/owner` and this
- * package deliberately cannot exercise them.
+ * (issue, reclaim, owner renewal, permanence) live in `@sorandomains/owner` and this
+ * package deliberately cannot exercise them. Native successor holders can
+ * independently renew an eligible lease through the separately authorized renewName.
  *
  * SIGNING. Same `TxSigner` contract as the owner SDK: `keypairSigner(secret)`
  * for scripts, or wrap a browser wallet:
@@ -31,14 +32,33 @@
  * calls cannot race the account sequence number.
  */
 import { type PaymentDestination } from "./payment.js";
-export { PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination, type PaymentMemo, type PaymentDestination } from "./payment.js";
+export { encodeMuxedAddress, decodeMuxedAddress, PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination, type PaymentMemo, type PaymentDestination } from "./payment.js";
+import { type ClaimSubmitOptions } from "./native-holder.js";
+import type { ClaimIntent, TransferIntent, RenewIntent } from "./native-types.js";
+import type { NativeWriteOptions } from "./native-transport.js";
+export * from "./native-types.js";
+export * from "./native-allowlist.js";
+export * from "./native-approver.js";
+export { NativeClaimError, paymentDestinationToScVal, namespaceNode as nativeNamespaceNode } from "./native-codec.js";
+export { createClaimIntent, type ClaimRequestOptions, type ClaimSubmitOptions, type NativeClaimSubmission, type PreparedClaim } from "./native-holder.js";
+export { signEligibilityAuthorization, validateEligibilityAuthorization, validateNativeTransaction, authorizedInvocation, type NativeAuthorizationPlan, type EligibilitySigner } 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: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE";
-        readonly primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X";
+        readonly registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK";
+        readonly primaryId: "CASORAN755O3GCQTRAHKDXLLCSDLNKAQWAP6MWABRSFVSHLJOEKAC7AB";
+    };
+};
+/** 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";
+        readonly primaryId: "CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ";
     };
 };
 /** Same shape as the owner SDK's signer — wallet-kit compatible. */
@@ -82,6 +102,8 @@ export type Submitted = {
 /** The standard profile keys shared with @sorandomains/lookup's profile(). */
 export declare const PROFILE_KEYS: readonly ["org", "url", "email", "description", "avatar", "location", "twitter", "github"];
 export type HolderOptions = {
+    /** Upper total network fee for successor native operations; default 5 XLM. */
+    maxNativeFeeStroops?: bigint;
     /** Signs every transaction: the name HOLDER's account (or, for
      *  `acceptNameTransfer`, the proposed new holder's). */
     signer: TxSigner;
@@ -101,6 +123,7 @@ export type HolderOptions = {
     fee?: string;
 };
 export declare class SoranHolder {
+    private maxNativeFeeStroops;
     private server;
     private passphrase;
     private registryId;
@@ -113,6 +136,16 @@ export declare class SoranHolder {
     private resolvers;
     private static POINTER_TTL_MS;
     constructor(opts: HolderOptions);
+    private nativeClient;
+    nativeClaimCapability(namespace: string): Promise<import("./native-transport.js").NativeCapability>;
+    claimQuote(name: string, claimant?: string): Promise<import("./native-types.js").ClaimQuote>;
+    claimReceipt(namespace: string, claimant: string, requestId: string): Promise<import("./native-types.js").ClaimReceipt | null>;
+    recoverClaim(intent: ClaimIntent): Promise<import("./native-types.js").ClaimReceipt | null>;
+    buildClaim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<import("./native-holder.js").PreparedClaim>;
+    claim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<import("./native-holder.js").NativeClaimSubmission>;
+    renewalPreview(name: string): Promise<import("./native-types.js").DestinationPreview>;
+    acceptNameTransferWithDestination(intent: TransferIntent, options?: NativeWriteOptions): Promise<import("./native-holder.js").NativeClaimSubmission>;
+    renewName(intent: RenewIntent, options?: NativeWriteOptions): Promise<import("./native-holder.js").NativeClaimSubmission>;
     /** Atomically update the forward address and complete payment instruction.
      * Use memo {type:"none"} to explicitly publish a memo-free destination.
      * The native Resolver updates its own records atomically. This method never
@@ -215,6 +248,8 @@ export declare class SoranHolder {
     private serialize;
     private sourceAccount;
     private assertSatisfiableAuth;
+    /** Native payment writes authorize exactly the locally selected destination. */
+    private assertPaymentIntent;
     private invoke;
     private attempt;
     private restore;

package/dist/index.js

@@ -17,8 +17,9 @@
  * checks you hold the name (generation-gated) before accepting records, the
  * reverse and primary claims are authorized by the ADDRESS itself, and name
  * transfers move only when the recipient accepts. Namespace-owner powers
- * (issue, reclaim, renew, permanence) live in `@sorandomains/owner` and this
- * package deliberately cannot exercise them.
+ * (issue, reclaim, owner renewal, permanence) live in `@sorandomains/owner` and this
+ * package deliberately cannot exercise them. Native successor holders can
+ * independently renew an eligible lease through the separately authorized renewName.
  *
  * SIGNING. Same `TxSigner` contract as the owner SDK: `keypairSigner(secret)`
  * for scripts, or wrap a browser wallet:
@@ -31,8 +32,16 @@
  * calls cannot race the account sequence number.
  */
 import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, StrKey, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, } from "@stellar/stellar-sdk";
-import { paymentFromNative, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
-export { PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination } from "./payment.js";
+import { decodeMuxedAddress, destinationFromNative, paymentFromNative, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
+export { encodeMuxedAddress, decodeMuxedAddress, PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination } from "./payment.js";
+import { NativeHolderClient } from "./native-holder.js";
+import { NativeClaimError } from "./native-codec.js";
+export * from "./native-types.js";
+export * from "./native-allowlist.js";
+export * from "./native-approver.js";
+export { NativeClaimError, paymentDestinationToScVal, namespaceNode as nativeNamespaceNode } from "./native-codec.js";
+export { createClaimIntent } from "./native-holder.js";
+export { signEligibilityAuthorization, validateEligibilityAuthorization, validateNativeTransaction, authorizedInvocation } from "./native-auth.js";
 // ---------------------------------------------------------------------------
 // Deployments
 // ---------------------------------------------------------------------------
@@ -41,8 +50,17 @@ export const DEPLOYMENTS = {
     testnet: {
         rpcUrl: "https://soroban-testnet.stellar.org",
         passphrase: Networks.TESTNET,
-        registryId: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE",
-        primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X",
+        registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK",
+        primaryId: "CASORAN755O3GCQTRAHKDXLLCSDLNKAQWAP6MWABRSFVSHLJOEKAC7AB",
+    },
+};
+/** 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,
+        registryId: "CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H",
+        primaryId: "CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ",
     },
 };
 /** A TxSigner over a raw secret key — for scripts and backends. */
@@ -81,6 +99,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",
 };
 const RESOLVER_ERRORS = {
     1: "AlreadyInitialized",
@@ -103,6 +122,7 @@ const RESOLVER_ERRORS = {
     18: "UsePaymentMethod",
     19: "PaymentContextMismatch",
     20: "PaymentUnavailable",
+    21: "MuxedDestination",
 };
 const PRIMARY_ERRORS = {
     1: "MalformedName",
@@ -200,7 +220,11 @@ function nameNode(label, namespace) {
     return new Uint8Array(hash(concatBytes(namehash(namespace), labelHash)));
 }
 const labelArg = (label) => nativeToScVal(utf8(label), { type: "bytes" });
-const addrArg = (address) => nativeToScVal(address, { type: "address" });
+const addrArg = (address) => {
+    if (!StrKey.isValidEd25519PublicKey(address) && !StrKey.isValidContract(address))
+        throw new HolderError("this account/address operation requires G or C; use setPayment for muxed destinations");
+    return nativeToScVal(address, { type: "address" });
+};
 const bytesArg = (b) => nativeToScVal(b, { type: "bytes" });
 const SIM_SOURCE = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
 /** The standard profile keys shared with @sorandomains/lookup's profile(). */
@@ -218,6 +242,7 @@ export const PROFILE_KEYS = [
 // The client
 // ---------------------------------------------------------------------------
 export class SoranHolder {
+    maxNativeFeeStroops;
     server;
     passphrase;
     registryId;
@@ -230,6 +255,9 @@ export class SoranHolder {
     resolvers = new Map();
     static POINTER_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 HolderError("HolderOptions.signer is required");
         const d = DEPLOYMENTS[opts.network ?? "testnet"];
@@ -250,6 +278,19 @@ export class SoranHolder {
         this.timeoutSecs = t;
         this.fee = opts.fee ?? BASE_FEE;
     }
+    nativeClient() {
+        return new NativeHolderClient({ 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) });
+    }
+    nativeClaimCapability(namespace) { return this.nativeClient().nativeClaimCapability(namespace); }
+    claimQuote(name, claimant) { return this.nativeClient().claimQuote(name, claimant); }
+    claimReceipt(namespace, claimant, requestId) { return this.nativeClient().claimReceipt(namespace, claimant, requestId); }
+    recoverClaim(intent) { return this.nativeClient().recoverClaim(intent); }
+    buildClaim(intent, options = {}) { return this.nativeClient().buildClaim(intent, options); }
+    claim(intent, options = {}) { return this.nativeClient().claim(intent, options); }
+    renewalPreview(name) { return this.nativeClient().renewalPreview(name); }
+    acceptNameTransferWithDestination(intent, options = {}) { return this.nativeClient().acceptNameTransferWithDestination(intent, options); }
+    renewName(intent, options = {}) { return this.nativeClient().renewName(intent, options); }
     // ---- resolution targets --------------------------------------------------
     /** Atomically update the forward address and complete payment instruction.
      * Use memo {type:"none"} to explicitly publish a memo-free destination.
@@ -264,8 +305,18 @@ export class SoranHolder {
         catch (e) {
             throw new HolderError(String(e));
         }
-        const { resolver } = await this.paymentResolverOf(namespace);
+        const { resolver, version } = await this.paymentResolverOf(namespace);
         const holder = await this.signer.publicKey();
+        if (StrKey.isValidMed25519PublicKey(payment.address)) {
+            if (version !== 2)
+                throw new HolderError("muxed destinations require native Resolver v2", resolver, "payment_version");
+            const muxed = decodeMuxedAddress(payment.address);
+            const r = await this.invoke(resolver, "set_muxed", [
+                nativeToScVal(`${label}.${namespace}`, { type: "string" }), addrArg(holder),
+                addrArg(muxed.account), nativeToScVal(BigInt(muxed.id), { type: "u64" }),
+            ], RESOLVER_ERRORS);
+            return { hash: r.hash, ledger: r.ledger };
+        }
         const r = await this.invoke(resolver, "set_payment", [
             nativeToScVal(`${label}.${namespace}`, { type: "string" }), addrArg(holder),
             addrArg(payment.address), paymentMemoToScVal(payment.memo),
@@ -525,21 +576,26 @@ export class SoranHolder {
             !(anchors[1] instanceof Uint8Array) || anchors[1].length !== nsNode.length ||
             !nsNode.every((byte, index) => anchors[1][index] === byte))
             throw new HolderError("Registrar anchors do not match this Registry and namespace", registrar, "anchors");
-        if (version !== 1)
+        if (version !== 1 && version !== 2)
             throw new HolderError("unsupported native payment Resolver version", resolver, "payment_version");
-        return { resolver, registrar };
+        if (version === 2 && await this.read(resolver, "destination_version", []) !== 2)
+            throw new HolderError("unsupported Resolver destination version", resolver, "destination_version");
+        return { resolver, registrar, version };
     }
     async assertMemoFree(name) {
         const { label, namespace } = parseName(name);
-        const { resolver, registrar } = await this.paymentResolverOf(namespace);
-        const raw = await this.read(resolver, "resolve_payment", [nativeToScVal(`${label}.${namespace}`, { type: "string" })]);
+        const { resolver, registrar, version } = await this.paymentResolverOf(namespace);
+        const fn = version === 2 ? "resolve_destination" : "resolve_payment";
+        const raw = await this.read(resolver, fn, [nativeToScVal(`${label}.${namespace}`, { type: "string" })]);
         let payment;
         try {
-            payment = paymentFromNative(raw);
+            payment = version === 2 ? destinationFromNative(raw) : paymentFromNative(raw);
         }
         catch (e) {
-            throw new HolderError(`invalid payment result: ${String(e)}`, resolver, "resolve_payment");
+            throw new HolderError(`invalid payment result: ${String(e)}`, resolver, fn);
         }
+        if (StrKey.isValidMed25519PublicKey(payment.address))
+            throw new HolderError("this name has a muxed routing ID; use setPayment to explicitly update its destination");
         if (payment.memo.type !== "none")
             throw new HolderError("this name requires a memo; use setPayment to update address and memo together");
         // Registrar-only write below cannot alter a Resolver's explicit addr/memo.
@@ -602,6 +658,26 @@ export class SoranHolder {
                 : `${fn}: this operation must be authorized by ${required}, but the signer is ${pub} — use that account's signer`, contractId, fn);
         }
     }
+    /** Native payment writes authorize exactly the locally selected destination. */
+    assertPaymentIntent(prepared, pub, contractId, fn, args) {
+        if (fn !== "set_payment" && fn !== "set_muxed")
+            return;
+        if (prepared.source !== pub || prepared.operations.length !== 1)
+            throw new HolderError("unexpected payment transaction source or operation count", contractId, fn);
+        const op = prepared.operations[0];
+        if (op.type !== "invokeHostFunction" || (op.source !== undefined && op.source !== pub) || op.func.type !== "hostFunctionTypeInvokeContract")
+            throw new HolderError("unexpected payment operation", contractId, fn);
+        const call = op.func.invokeContract;
+        if (Address.fromScAddress(call.contractAddress).toString() !== contractId || call.functionName.toString() !== fn ||
+            call.args.length !== args.length || call.args.some((value, i) => value.toXDR("base64") !== args[i].toXDR("base64")))
+            throw new HolderError("payment operation differs from selected intent", contractId, fn);
+        if (!op.auth || op.auth.length !== 1 || op.auth[0].credentials.type !== "sorobanCredentialsSourceAccount")
+            throw new HolderError("payment requires exactly the source holder authorization", contractId, fn);
+        const root = op.auth[0].rootInvocation;
+        if (root.function.type !== "sorobanAuthorizedFunctionTypeContractFn" || root.subInvocations.length ||
+            root.function.contractFn.toXDR("base64") !== call.toXDR("base64"))
+            throw new HolderError("payment authorization differs from selected intent", contractId, fn);
+    }
     invoke(contractId, fn, args, errNames) {
         return this.serialize(async () => {
             try {
@@ -640,9 +716,12 @@ export class SoranHolder {
         }
         const prepared = rpc.assembleTransaction(tx, sim).build();
         this.assertSatisfiableAuth(prepared, pub, contractId, fn);
+        this.assertPaymentIntent(prepared, pub, contractId, fn, args);
         const txHash = toHex(prepared.hash()); // (SDK17) hash() is Uint8Array
         const signed = await this.signEnvelope(prepared.toXDR());
         const envelope = TransactionBuilder.fromXDR(signed, this.passphrase);
+        if ((fn === "set_payment" || fn === "set_muxed") && toHex(envelope.hash()) !== txHash)
+            throw new HolderError("signer changed the reviewed transaction body", contractId, fn);
         let sent;
         try {
             sent = await this.server.sendTransaction(envelope);

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-approver.d.ts

@@ -0,0 +1,21 @@
+import { type EligibilitySigner } from "./native-auth.js";
+import { type ClaimIntent, type ClaimConfig } from "./native-types.js";
+export type ClaimApprovalContext = {
+    /** Read this configuration and owner independently from the chain. Do not accept these from an applicant. */
+    config: ClaimConfig;
+    owner: string;
+    ownerEpoch: bigint;
+    networkPassphrase: string;
+    /** Independently pinned/read deployment, never copied from the applicant intent. network/namespace are hex32. */
+    network: string;
+    registry: string;
+    registrar: string;
+    namespace: string;
+    resolver: string;
+    latestLedger: number;
+    maxExpirationLedger: number;
+    expirationLedger: number;
+};
+/** Backend admission signing only. The application must first authenticate membership and the wallet binding.
+ * This function cannot turn an owner/treasury key into the configured admission account. */
+export declare function signClaimEligibility(intent: ClaimIntent, unsignedEntryXdr: string, context: ClaimApprovalContext, signer: EligibilitySigner): Promise<string>;

package/dist/native-approver.js

@@ -0,0 +1,36 @@
+import { hash, scValToNative, StrKey, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, hex, utf8 } from "./native-codec.js";
+import { signEligibilityAuthorization } from "./native-auth.js";
+import { claimIntentToScVal } from "./native-types.js";
+/** Backend admission signing only. The application must first authenticate membership and the wallet binding.
+ * This function cannot turn an owner/treasury key into the configured admission account. */
+export async function signClaimEligibility(intent, unsignedEntryXdr, context, signer) {
+    const encoded = claimIntentToScVal(intent), config = context.config, settings = config.settings;
+    if (context.network !== hex(hash(utf8(context.networkPassphrase))) || intent.context.network !== context.network || intent.context.registry !== context.registry || intent.context.registrar !== context.registrar || intent.context.namespace !== context.namespace || intent.resolver !== context.resolver || intent.ownerEpoch !== context.ownerEpoch || config.ownerEpoch !== context.ownerEpoch)
+        throw new NativeClaimError("approval intent differs from trusted deployment, namespace or current ownership epoch", "authorization");
+    address(context.owner, "identity", "namespace owner");
+    if (settings.mode !== "public" || !settings.enabled || settings.admission.type !== "approval")
+        throw new NativeClaimError("native app approval is not enabled", "authorization");
+    const account = settings.admission.account;
+    if (account === context.owner || account === settings.feeRecipient || account === intent.claimant)
+        throw new NativeClaimError("eligibility account must be separate from owner, treasury and claimant", "authorization");
+    if (intent.context.network !== hex(hash(utf8(context.networkPassphrase))) || intent.ownerEpoch !== config.ownerEpoch || intent.policyVersion !== config.policyVersion || intent.grantEpoch !== config.grantEpoch || intent.feeToken !== settings.feeToken || intent.feeAmount !== settings.feeAmount || intent.feeRecipient !== settings.feeRecipient)
+        throw new NativeClaimError("approval intent differs from independently read network/policy", "authorization");
+    if (intent.context.deadline - intent.context.validAfter > settings.approvalTtlSecs)
+        throw new NativeClaimError("approval exceeds the current business lifetime", "authorization");
+    const expected = { account, invocation: { contract: intent.context.registrar, method: "claim", args: [encoded] }, latestLedger: context.latestLedger, maxExpirationLedger: context.maxExpirationLedger };
+    const signed = await signEligibilityAuthorization(xdr.SorobanAuthorizationEntry.fromXDR(unsignedEntryXdr, "base64"), expected, signer, context.expirationLedger, context.networkPassphrase);
+    if (signed.credentials.type !== "sorobanCredentialsAddress")
+        throw new NativeClaimError("unsupported approval credential", "authorization");
+    const signatures = scValToNative(signed.credentials.address.signature);
+    if (!Array.isArray(signatures) || signatures.length === 0)
+        throw new NativeClaimError("approval is missing native account signatures", "authorization");
+    for (const signature of signatures) {
+        if (!(signature?.public_key instanceof Uint8Array) || signature.public_key.length !== 32)
+            throw new NativeClaimError("invalid native approval signer", "authorization");
+        const key = StrKey.encodeEd25519PublicKey(signature.public_key);
+        if ([context.owner, settings.feeRecipient, intent.claimant].includes(key))
+            throw new NativeClaimError("owner, treasury and claimant keys must never sign app eligibility", "authorization");
+    }
+    return signed.toXDR("base64");
+}

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