@sorandomains/holder 0.4.0 → 0.5.1

package/README.md

@@ -1,14 +1,14 @@
 # @sorandomains/holder
 
-> 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.4.0 targets Stellar SDK17 (`>=17 <18`). ASCII names
+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.6.0.
+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)
@@ -140,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. Receipt reads, receipt absence and confirmed transaction results are accepted only after a clean Registrar attestation and executable check with RPC ledger context at least as recent as the receipt read or transaction inclusion. Missing or older context stops recovery; retain the original request and transaction hash. This check trusts the configured RPC to report its state and ledger honestly. Later namespace-owner, claim-policy or Resolver changes alone do not invalidate a historical receipt, while a tainted or upgraded Registrar cannot supply authoritative history. `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 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` |
-| Primary | `CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ` |
+| 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:
@@ -32,9 +33,28 @@
  */
 import { 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: "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";
@@ -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
@@ -211,6 +244,8 @@ export declare class SoranHolder {
     private paymentResolverOf;
     private assertMemoFree;
     private read;
+    private readWithLedger;
+    private simulateRead;
     private signEnvelope;
     private serialize;
     private sourceAccount;

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:
@@ -33,12 +34,30 @@
 import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, StrKey, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, } from "@stellar/stellar-sdk";
 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";
+import { requireReadLedger } 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 } from "./native-holder.js";
+export { signEligibilityAuthorization, validateEligibilityAuthorization, 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,
+        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",
@@ -81,6 +100,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",
@@ -223,6 +243,7 @@ export const PROFILE_KEYS = [
 // The client
 // ---------------------------------------------------------------------------
 export class SoranHolder {
+    maxNativeFeeStroops;
     server;
     passphrase;
     registryId;
@@ -235,6 +256,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"];
@@ -255,6 +279,20 @@ 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),
+            readWithLedger: (id, method, args) => this.readWithLedger(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.
@@ -567,6 +605,13 @@ export class SoranHolder {
         return registrar;
     }
     async read(contractId, fn, args) {
+        return (await this.simulateRead(contractId, fn, args)).value;
+    }
+    async readWithLedger(contractId, fn, args) {
+        const result = await this.simulateRead(contractId, fn, args);
+        return { value: result.value, ledger: requireReadLedger(result.ledger) };
+    }
+    async simulateRead(contractId, fn, args) {
         const tx = new TransactionBuilder(new Account(SIM_SOURCE, "0"), {
             fee: BASE_FEE,
             networkPassphrase: this.passphrase,
@@ -583,7 +628,7 @@ export class SoranHolder {
         if (!rpc.Api.isSimulationSuccess(sim) || !sim.result?.retval)
             throw new HolderError(`${fn}: missing simulation return value`, contractId, fn);
         const v = scValToNative(sim.result.retval);
-        return v === undefined ? null : v;
+        return { value: v === undefined ? null : v, ledger: sim.latestLedger };
     }
     async signEnvelope(xdrBase64) {
         const signed = await this.signer.signTransaction(xdrBase64, {

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

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