@sorandomains/owner 0.6.0 → 0.8.0-migration.0

package/README.md

@@ -1,22 +1,21 @@
 # @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
+Preview 0.8.0-migration.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.8.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
 actual G/C holder, then that holder can call Holder `setPayment` to publish M.
 
 Run your Soran namespace on Stellar, programmatically. Issue names to your
-users, manage their lifecycle, transfer the namespace, and — when you are
-ready — walk the one-way permanence door. Every operation is a transaction
+users, manage their lifecycle and transfer the namespace. Every operation is a transaction
 your own key signs and any Soroban RPC node submits: no Soran account, no
 hosted API in the path.
 
@@ -45,7 +44,7 @@ for (const o of batch.outcomes) if (!o.issued) console.warn(o.label, o.reason);
 | `reclaim` | Take a name back — only where the namespace policy allows it |
 | `renew` | Extend a finite-term name; returns the new expiry |
 | `setTreasury` | Route reclaim custody to a treasury address |
-| `makePermanent` | The one-way door — irreversible, guarded by `{ confirmIrreversible: true }` |
+| `makePermanent` | Legacy deployment operation; unavailable on governed testnet contracts |
 | `proposeNamespaceTransfer` / `acceptNamespaceTransfer` / `cancelNamespaceTransfer` | Two-step, accept-to-move namespace transfer |
 | `setResolver` | Point the namespace at a resolver (frozen once permanent) |
 | `policy` / `isPermanent` / `nameState` / `pendingNamespaceTransfer` / `namespaceOwner` / `registrarOf` / `assertOwner` | Reads that support the write flows |
@@ -83,14 +82,42 @@ 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
 and ABI version do not pin the code that will execute after a governance upgrade.
+
+## Network fee limits
+
+Available in 0.8.0.
+
+Every write and automatic restoration has a total network-fee limit, including the base and resource fees. The default is **5 XLM** (`50_000_000n` stroops). Set `maxNetworkFeeStroops` on the client only after reviewing a higher storage/rent estimate. This limits each transaction separately; it is not a daily or batch spending budget, and namespace/username prices are separate.
+
+```ts
+const client = new SoranOwner({
+  signer,
+  maxNetworkFeeStroops: 50_000_000n,
+});
+```
+
+The older `maxNativeFeeStroops` option remains supported: when the new option is omitted, it also supplies the total ceiling. If both are set, native operations use the lower value and other writes use `maxNetworkFeeStroops`. An excessive estimate is rejected before wallet approval. After a possible submission, errors retain the original transaction hash; reconcile it before creating a replacement transaction.
+
+## Governed testnet code and migration recovery
+
+On a governed Registry, native verification reads the exact per-namespace Registrar code pin and its upgrade history. Approved upgrades do not have to match the current factory default. Missing or malformed provenance still prevents signing and receipt confirmation; RPC failure never downgrades verification to a legacy rule.
+
+Historical claim recovery is read-only and binds the original intent to the frozen source Registrar and sealed migration commitments. It never rewrites the intent to a successor Registry or treats an unavailable receipt as permission to submit again. Deployment migration and package publication are separate; check the release status for the active addresses.

package/dist/index.d.ts

@@ -1,43 +1,24 @@
-/**
- * @sorandomains/owner — the write-side SDK for Soran namespace owners.
- *
- * Everything a namespace owner does after winning a namespace, programmatically:
- *
- *   import { SoranOwner, keypairSigner } from "@sorandomains/owner";
- *
- *   const owner = new SoranOwner({ signer: keypairSigner(process.env.OWNER_SECRET!) });
- *   await owner.issue("acme", "alice", "GDHN…");          // alice.acme now resolves
- *   await owner.issueBatch("acme", csvRows);              // up to 23 per transaction
- *
- * TRUST MODEL. This SDK talks to the contracts directly over any Soroban RPC
- * node — no Soran account, no hosted API, no third party in the path. Every
- * operation here is authorized on chain: the Registrar and Registry check
- * `require_auth` against the namespace owner's address, so the only credential
- * that matters is the signer you supply. Soran's servers cannot perform any of
- * these operations for you or against you.
- *
- * WHO CAN CALL WHAT. All operations below are namespace-OWNER powers except
- * `acceptNamespaceTransfer`, which the proposed NEW owner signs. Name-holder
- * powers (transferring an individual name, pointing it at a new address,
- * electing a primary name) are the holder's alone — they live in the contracts'
- * holder-authorized entry points and live in `@sorandomains/holder`; this
- * package deliberately cannot exercise them.
- *
- * SIGNING. Supply a `TxSigner`: `keypairSigner(secret)` for backends, or wrap a
- * browser wallet (Freighter / Stellar Wallets Kit expose exactly this
- * `signTransaction(xdr, { networkPassphrase })` shape). The SDK builds and
- * simulates each transaction, hands you the envelope to sign, and submits it.
- * Operations on one SoranOwner instance are serialized so concurrent calls
- * cannot race the account sequence number.
- *
- * READS. For resolution, reverse lookup, and assurance checks use the read-only
- * companion package `@sorandomains/lookup` — wallets and apps should depend on
- * that one only. The few reads here (policy, pending transfers, records) exist
- * to support write flows.
- */
+import { type HistoricalRecoveryOptions } from "./native-history.js";
+import type { ClaimIntent } from "./native-types.js";
+export type { HistoricalRecoveryOptions } from "./native-history.js";
+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 +111,11 @@ export type NameState = {
     generation: bigint;
 };
 export type OwnerOptions = {
+    /** Maximum total network fee per transaction, including restoration. Default 5 XLM.
+     * If omitted, an explicit maxNativeFeeStroops also supplies this ceiling. */
+    maxNetworkFeeStroops?: bigint;
+    /** Optional additional native-operation ceiling; the lower configured limit wins. */
+    maxNativeFeeStroops?: bigint;
     /** Signs every transaction. The namespace owner's account — or, for
      *  `acceptNamespaceTransfer`, the proposed new owner's. */
     signer: TxSigner;
@@ -150,6 +136,8 @@ export type OwnerOptions = {
     fee?: string;
 };
 export declare class SoranOwner {
+    private maxNativeFeeStroops;
+    private maxNetworkFeeStroops;
     private server;
     private passphrase;
     private registryId;
@@ -161,6 +149,40 @@ 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;
+    /** Read the original frozen-source receipt after a fully sealed migration. Never submits. */
+    recoverHistoricalClaim(intent: ClaimIntent, options: HistoricalRecoveryOptions): Promise<import("./native-types.js").ClaimReceipt | null>;
+    /** 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>;
@@ -232,6 +254,9 @@ export declare class SoranOwner {
     private readRecords;
     /** Simulation-only contract read — no signature, no fee, no state change. */
     private read;
+    private readWithLedger;
+    private simulateRead;
+    private assertNetworkFee;
     private signEnvelope;
     private serialize;
     /** The signer's live account (sequence source) — with an actionable error

package/dist/index.js

@@ -1,3 +1,4 @@
+import { recoverFrozenClaim, historicalReadLedger } from "./native-history.js";
 /**
  * @sorandomains/owner — the write-side SDK for Soran namespace owners.
  *
@@ -35,7 +36,7 @@
  * that one only. The few reads here (policy, pending transfers, records) exist
  * to support write flows.
  */
-import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, StrKey, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, xdr, } from "@stellar/stellar-sdk";
+import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, StrKey, SorobanDataBuilder, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, xdr, } from "@stellar/stellar-sdk";
 /** Contract events from a transaction's meta, across meta versions (v3 puts
  *  them on sorobanMeta; v4 nests them per-operation and in tx events). */
 function extractContractEvents(meta) {
@@ -84,12 +85,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 +152,37 @@ 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",
+    43: "MigrationInProgress",
+    44: "MigrationAlreadyStarted",
+    45: "MigrationNotActive",
+    46: "MigrationMismatch",
+    47: "MigrationDuplicate",
+    48: "MigrationIncomplete",
+    49: "MigrationUnavailable",
+    50: "MigrationUnsupported",
+    51: "PermanentLockDisabled",
 };
 /** Registry contract error codes, by number. */
 const REGISTRY_ERRORS = {
@@ -165,6 +214,19 @@ const REGISTRY_ERRORS = {
     26: "AnchorMismatch",
     27: "InvalidAllocator",
     28: "StaleEra",
+    29: "OwnershipEpochUnavailable",
+    30: "OwnershipEpochOverflow",
+    31: "MigrationInProgress",
+    32: "MigrationAlreadyStarted",
+    33: "MigrationNotActive",
+    34: "MigrationMismatch",
+    35: "MigrationIncomplete",
+    36: "MigrationDuplicate",
+    37: "MigrationUnsupported",
+    38: "MigrationUnavailable",
+    39: "UpgradePolicyMismatch",
+    40: "UpgradeNotApproved",
+    41: "PermanentLockDisabled",
 };
 /**
  * A failed owner operation. When the contract itself rejected the call,
@@ -256,6 +318,8 @@ export const MAX_BATCH = 23;
 // The client
 // ---------------------------------------------------------------------------
 export class SoranOwner {
+    maxNativeFeeStroops;
+    maxNetworkFeeStroops;
     server;
     passphrase;
     registryId;
@@ -271,6 +335,13 @@ export class SoranOwner {
     registrars = new Map();
     static REGISTRAR_TTL_MS = 30_000;
     constructor(opts) {
+        this.maxNetworkFeeStroops = opts?.maxNetworkFeeStroops ?? opts?.maxNativeFeeStroops ?? 50000000n;
+        const nativeLimit = opts?.maxNativeFeeStroops ?? this.maxNetworkFeeStroops;
+        for (const limit of [this.maxNetworkFeeStroops, nativeLimit]) {
+            if (typeof limit !== "bigint" || limit <= 0n || limit > 4294967295n)
+                throw new OwnerError("maximum network fee must be a bigint between 1 and 4294967295 stroops");
+        }
+        this.maxNativeFeeStroops = nativeLimit < this.maxNetworkFeeStroops ? nativeLimit : this.maxNetworkFeeStroops;
         if (!opts?.signer)
             throw new OwnerError("OwnerOptions.signer is required");
         const d = DEPLOYMENTS[opts.network ?? "testnet"];
@@ -287,9 +358,95 @@ export class SoranOwner {
         }
         this.timeoutSecs = t;
         this.fee = opts.fee ?? BASE_FEE;
+        if (!/^[1-9][0-9]*$/.test(this.fee) || BigInt(this.fee) > 4294967295n)
+            throw new OwnerError("base network fee must be canonical decimal stroops between 1 and 4294967295");
     }
     // ---- 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) };
+    }
+    /** Read the original frozen-source receipt after a fully sealed migration. Never submits. */
+    recoverHistoricalClaim(intent, options) {
+        return recoverFrozenClaim({ registryId: this.registryId, passphrase: this.passphrase, server: this.server,
+            readWithLedger: (id, method, args) => this.readWithLedger(id, method, args) }, intent, options);
+    }
+    /** 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);
@@ -544,6 +701,13 @@ export class SoranOwner {
     }
     /** Simulation-only contract read — no signature, no fee, no state change. */
     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: historicalReadLedger(result.ledger) };
+    }
+    async simulateRead(contractId, fn, args) {
         const tx = new TransactionBuilder(new Account(SIM_SOURCE, "0"), {
             fee: BASE_FEE,
             networkPassphrase: this.passphrase,
@@ -561,9 +725,13 @@ 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;
+        return { value: v === undefined ? null : v, ledger: sim.latestLedger };
+    }
+    assertNetworkFee(fee, fn) {
+        if (!/^[1-9][0-9]*$/.test(fee) || BigInt(fee) > this.maxNetworkFeeStroops)
+            throw new OwnerError(`${fn}: network fee ${fee} stroops exceeds the configured maximum ${this.maxNetworkFeeStroops} stroops`, null, fn);
     }
     async signEnvelope(xdrBase64) {
         const signed = await this.signer.signTransaction(xdrBase64, {
@@ -594,7 +762,7 @@ export class SoranOwner {
             catch (e) {
                 // A stale sequence (another process moved the account) is safe to
                 // retry once with a fresh sequence — nothing was included.
-                if (/txBadSeq|bad_seq/i.test(String(e))) {
+                if (!(e instanceof OwnerError && e.txHash) && /txBadSeq|bad_seq/i.test(String(e))) {
                     return await this.attempt(contractId, fn, args, errNames);
                 }
                 throw e;
@@ -653,12 +821,15 @@ export class SoranOwner {
             throw typedError(contractId, fn, sim.error, errNames);
         }
         const prepared = rpc.assembleTransaction(tx, sim).build();
+        this.assertNetworkFee(prepared.fee, fn);
         this.assertSatisfiableAuth(prepared, pub, contractId, fn);
         // The hash is fixed before signatures — compute it now so every failure
         // past this point can carry it (the "re-check before retrying" contract).
         const txHash = toHex(prepared.hash()); // (SDK17) hash() is Uint8Array
         const signed = await this.signEnvelope(prepared.toXDR());
         const envelope = TransactionBuilder.fromXDR(signed, this.passphrase);
+        if (toHex(envelope.hash()) !== txHash)
+            throw new OwnerError("signer changed the reviewed transaction body", contractId, fn);
         let sent;
         try {
             sent = await this.server.sendTransaction(envelope);
@@ -686,21 +857,48 @@ export class SoranOwner {
     }
     async restore(sim, pub) {
         const pre = sim.restorePreamble;
-        const fee = (Number(this.fee) + Number(pre.minResourceFee)).toString();
+        if (!/^(0|[1-9][0-9]*)$/.test(pre.minResourceFee))
+            throw new OwnerError("invalid restoration resource fee", null, "restore_footprint");
+        const quoted = BigInt(pre.minResourceFee);
+        const data = pre.transactionData.build();
+        const encoded = BigInt(data.resourceFee.toString());
+        if (encoded < 0n)
+            throw new OwnerError("invalid encoded restoration resource fee", null, "restore_footprint");
+        const resourceFee = quoted > encoded ? quoted : encoded;
+        this.assertNetworkFee((BigInt(this.fee) + resourceFee).toString(), "restore_footprint");
         const tx = new TransactionBuilder(await this.sourceAccount(pub, "restore_footprint"), {
-            fee,
+            // SDK 17 adds Soroban resourceFee itself; supply the base only once.
+            fee: this.fee,
             networkPassphrase: this.passphrase,
         })
-            .setSorobanData(pre.transactionData.build())
+            .setSorobanData(new SorobanDataBuilder(data).setResourceFee(resourceFee.toString()).build())
             .addOperation(Operation.restoreFootprint({}))
             .setTimeout(this.timeoutSecs)
             .build();
+        this.assertNetworkFee(tx.fee, "restore_footprint");
+        const txHash = toHex(tx.hash());
         const signed = await this.signEnvelope(tx.toXDR());
-        const sent = await this.server.sendTransaction(TransactionBuilder.fromXDR(signed, this.passphrase));
-        if (sent.status === "ERROR") {
-            throw new OwnerError(`restore_footprint: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, null, "restore_footprint", null, null, sent.hash);
+        const envelope = TransactionBuilder.fromXDR(signed, this.passphrase);
+        if (toHex(envelope.hash()) !== txHash)
+            throw new OwnerError("signer changed the reviewed restoration body", null, "restore_footprint");
+        let sent;
+        try {
+            sent = await this.server.sendTransaction(envelope);
+        }
+        catch (error) {
+            throw new OwnerError(`restoration submission is uncertain (${String(error)}); check ${txHash} before retrying`, null, "restore_footprint", null, null, txHash);
+        }
+        if (sent.status === "ERROR" || sent.status === "TRY_AGAIN_LATER") {
+            throw new OwnerError(`restore_footprint: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, null, "restore_footprint", null, null, txHash);
+        }
+        try {
+            await this.confirm(txHash, "", "restore_footprint", {});
+        }
+        catch (error) {
+            if (error instanceof OwnerError)
+                throw error;
+            throw new OwnerError(`restoration confirmation is uncertain (${String(error)}); check ${txHash} before retrying`, null, "restore_footprint", null, null, txHash);
         }
-        await this.confirm(sent.hash, "", "restore_footprint", {});
     }
     // Poll past the tx time bound (timeoutSecs) so we never declare failure
     // while the transaction is still valid and pending inclusion.

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;