@sorandomains/owner 0.7.0 → 0.8.0

package/README.md

@@ -5,18 +5,17 @@
 > [release status](https://docs.soran.domains/reference/release-status) for package and service availability.
 
 
-Version 0.7.0 targets Stellar SDK17 (`>=17 <18`). ASCII names
+Version 0.8.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.7.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 |
@@ -101,3 +100,24 @@ Verified on 6 September 2026 at ledger **4534629** (12:12 UTC). Network passphra
 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,40 +1,6 @@
-/**
- * @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";
@@ -47,7 +13,7 @@ export declare const DEPLOYMENTS: {
     readonly testnet: {
         readonly rpcUrl: "https://soroban-testnet.stellar.org";
         readonly passphrase: string;
-        readonly registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK";
+        readonly registryId: "CCSORANDPQINYOYB5SVO45WJP2LBBYKC72HHUIRVXB4J6RUZKDAUW7G4";
     };
 };
 /** Explicit historical deployment access. Names in different Registries are separate identities; never a fallback. */
@@ -145,7 +111,10 @@ export type NameState = {
     generation: bigint;
 };
 export type OwnerOptions = {
-    /** Upper total network fee for successor native operations; default 5 XLM. */
+    /** 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. */
@@ -168,6 +137,7 @@ export type OwnerOptions = {
 };
 export declare class SoranOwner {
     private maxNativeFeeStroops;
+    private maxNetworkFeeStroops;
     private server;
     private passphrase;
     private registryId;
@@ -181,6 +151,8 @@ export declare class SoranOwner {
     /** 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>;
@@ -282,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) {
@@ -99,9 +100,9 @@ export const DEPLOYMENTS = {
     testnet: {
         rpcUrl: "https://soroban-testnet.stellar.org",
         passphrase: Networks.TESTNET,
-        // The immutable Registry. The Registrar for a namespace is discovered on
+        // The governed Registry. The Registrar for a namespace is discovered on
         // chain via `registrar_of(node)` — never configured by hand.
-        registryId: "CBSORANPM664QXYMYRZKLQDQE2TXFSK4GBMC6EIRSRTAUZRZCRZRFNMK",
+        registryId: "CCSORANDPQINYOYB5SVO45WJP2LBBYKC72HHUIRVXB4J6RUZKDAUW7G4",
     },
 };
 /** Explicit historical deployment access. Names in different Registries are separate identities; never a fallback. */
@@ -151,7 +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",
+    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 = {
@@ -183,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,
@@ -275,6 +319,7 @@ export const MAX_BATCH = 23;
 // ---------------------------------------------------------------------------
 export class SoranOwner {
     maxNativeFeeStroops;
+    maxNetworkFeeStroops;
     server;
     passphrase;
     registryId;
@@ -290,9 +335,13 @@ export class SoranOwner {
     registrars = new Map();
     static REGISTRAR_TTL_MS = 30_000;
     constructor(opts) {
-        this.maxNativeFeeStroops = opts?.maxNativeFeeStroops ?? 50000000n;
-        if (typeof this.maxNativeFeeStroops !== "bigint" || this.maxNativeFeeStroops <= 0n || this.maxNativeFeeStroops > 4294967295n)
-            throw new NativeClaimError("maximum native network fee must be positive");
+        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"];
@@ -309,6 +358,8 @@ 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. */
@@ -324,6 +375,11 @@ export class SoranOwner {
         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) {
@@ -645,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,
@@ -664,7 +727,11 @@ export class SoranOwner {
         if (!rpc.Api.isSimulationSuccess(sim) || !sim.result?.retval)
             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, {
@@ -695,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;
@@ -754,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);
@@ -787,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-code-policy.d.ts

@@ -0,0 +1,14 @@
+import { xdr, type rpc } from '@stellar/stellar-sdk';
+type Context = {
+    registryId: string;
+    server: Pick<rpc.Server, 'getLedgerEntries'>;
+    read(contract: string, method: string, args: xdr.ScVal[]): Promise<unknown>;
+    readWithLedger?(contract: string, method: string, args: xdr.ScVal[]): Promise<{
+        value: unknown;
+        ledger: number;
+    }>;
+};
+/** Select policy from an exact Registry instance proof. Failed RPC/method reads
+ * never downgrade governed verification to the historical template rule. */
+export declare function expectedRegistrarCode(context: Context, namespace: string, minimumLedger?: number): Promise<string>;
+export {};

package/dist/native-code-policy.js

@@ -0,0 +1,53 @@
+import { Contract, scValToNative, xdr } from '@stellar/stellar-sdk';
+import { NativeClaimError, address, bytes32, exactObject, hex, sc, u32, unhex } from './native-codec.js';
+function fail(message) { throw new NativeClaimError(`Registry code policy: ${message}`, 'unavailable'); }
+function ledger(value, minimum) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum || value < 1 || value > 0xffffffff)
+        fail('missing or stale ledger context');
+    return value;
+}
+/** Select policy from an exact Registry instance proof. Failed RPC/method reads
+ * never downgrade governed verification to the historical template rule. */
+export async function expectedRegistrarCode(context, namespace, minimumLedger) {
+    const key = new Contract(context.registryId).getFootprint();
+    const proof = await context.server.getLedgerEntries(key);
+    const observed = ledger(proof?.latestLedger, minimumLedger ?? 1);
+    const entry = proof.entries?.[0];
+    if (proof.entries?.length !== 1 || !entry || entry.key.toXDR('base64') !== key.toXDR('base64') || entry.val.type !== 'contractData')
+        fail('missing or mismatched instance');
+    const data = entry.val.value;
+    if (data.contract.toXDR('base64') !== new Contract(context.registryId).address().toScAddress().toXDR('base64') || data.key.type !== 'scvLedgerKeyContractInstance' || data.durability !== xdr.ContractDataDurability.persistent || data.val.type !== 'scvContractInstance' || data.val.value.executable.type !== 'contractExecutableWasm')
+        fail('invalid Registry Wasm instance');
+    const storage = data.val.value.storage;
+    if (storage !== null && !Array.isArray(storage))
+        fail('malformed instance storage');
+    const authorityKey = xdr.ScVal.scvVec([xdr.ScVal.scvSymbol('AuthorityV1')]).toXDR('base64');
+    const authorities = (storage ?? []).filter(row => row.key.toXDR('base64') === authorityKey);
+    if (authorities.length > 1)
+        fail('duplicate authority');
+    const read = async (method, args = []) => {
+        if (minimumLedger === undefined)
+            return context.read(context.registryId, method, args);
+        if (!context.readWithLedger)
+            fail('fresh policy reader unavailable');
+        const result = await context.readWithLedger(context.registryId, method, args);
+        ledger(result?.ledger, Math.max(observed, minimumLedger));
+        return result.value;
+    };
+    if (authorities.length === 0) {
+        const templates = await read('template_hashes');
+        if (!Array.isArray(templates) || templates.length !== 2)
+            fail('malformed historical templates');
+        return hex(bytes32(templates[0], 'Registry Registrar template'));
+    }
+    if (authorities[0].val.type !== 'scvAddress')
+        fail('malformed upgrade authority');
+    address(scValToNative(authorities[0].val), 'identity', 'Registry upgrade authority');
+    if (await read('upgrade_policy_version') !== 1)
+        fail('unsupported governed policy');
+    const code = exactObject(await read('native_code', [sc.bytes(unhex(namespace))]), ['registrar', 'resolver', 'registrar_updates', 'resolver_updates'], 'native code');
+    u32(code.registrar_updates, 'Registrar upgrade count');
+    u32(code.resolver_updates, 'Resolver upgrade count');
+    bytes32(code.resolver, 'Registry Resolver code');
+    return hex(bytes32(code.registrar, 'Registry Registrar code'));
+}

package/dist/native-history.d.ts

@@ -0,0 +1,26 @@
+import { xdr, type rpc } from "@stellar/stellar-sdk";
+import { type ClaimIntent, type ClaimReceipt } from "./native-types.js";
+/** Use a deployment's trusted stable Lookup, never a value supplied by a claim. */
+export type HistoricalRecoveryOptions = {
+    lookupId: string;
+};
+export type HistoricalRead = {
+    value: unknown;
+    ledger: number;
+};
+export type HistoricalContext = {
+    registryId: string;
+    passphrase: string;
+    server: Pick<rpc.Server, "getLedgerEntries">;
+    readWithLedger(contract: string, method: string, args: xdr.ScVal[]): Promise<HistoricalRead>;
+};
+export declare function historicalReadLedger(value: unknown, minimum?: number): number;
+/**
+ * Read a completed claim from its original frozen Registrar after cutover.
+ * The canonical Lookup's governance-approved sealed migration is an explicit
+ * trust anchor for source history before freeze. Current code hashes cannot
+ * independently prove that no malicious upgrade occurred before that review.
+ * This function never signs, submits, rewrites an intent or enables a replay.
+ * A verified null is historical absence, not permission to submit an old intent.
+ */
+export declare function recoverFrozenClaim(context: HistoricalContext, input: ClaimIntent, options: HistoricalRecoveryOptions): Promise<ClaimReceipt | null>;

package/dist/native-history.js

@@ -0,0 +1,162 @@
+import { Contract, hash, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, bool, bytes32, exactObject, hex, namespaceNode, sc, struct, u32, u64, unhex, utf8 } from "./native-codec.js";
+import { claimIntentFromNative, claimIntentToScVal, claimReceiptFromNative, nativeIntentHash } from "./native-types.js";
+// A tainted Registrar is not generally trusted. Only this reviewed export
+// implementation is eligible, after canonical Lookup confirms sealed migration.
+const REVIEWED_SOURCE_HASH = "26e03cd1d7fbfa46fe442406fb1b88022ec8cd8bd9123bed570f971fce596a14";
+const PLAN_FIELDS = ["source_registry", "source_registry_hash", "namespace_root", "namespace_count", "ownership_sequence", "primary_source", "primary_source_hash", "primary_target", "primary_target_hash", "primary_root", "primary_count"];
+const LEAF_FIELDS = ["label", "owner", "owner_epoch", "source_registrar", "source_registrar_hash", "source_resolver", "source_resolver_hash", "treasury", "policy", "pending_transfer", "registrar_root", "registrar_count", "resolver_root", "resolver_count"];
+function fail(message) { throw new NativeClaimError(`historical recovery: ${message}`, "unavailable"); }
+export function historicalReadLedger(value, minimum = 1) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value < 1 || value > 0xffff_ffff)
+        return fail("RPC read has missing, invalid or stale ledger context");
+    return value;
+}
+function sameBytes(value, expected, what) {
+    if (hex(bytes32(value, what)) !== expected)
+        fail(`${what} differs from the saved intent or migration commitment`);
+}
+function listOfOne(value, namespace, what) {
+    if (!Array.isArray(value) || value.length !== 1)
+        fail(`${what} is incomplete`);
+    sameBytes(value[0], namespace, what);
+}
+function leafScVal(raw) {
+    const policy = exactObject(raw.policy, ["reclaimable", "transferable", "tradeable", "default_term_secs", "trade_fee_bps"], "migration policy");
+    if (!(raw.label instanceof Uint8Array) || !Array.isArray(raw.pending_transfer) || raw.pending_transfer.length !== 0)
+        return fail("invalid namespace label or pending transfer in migration commitment");
+    const fields = {
+        label: sc.bytes(new Uint8Array(raw.label)), pending_transfer: xdr.ScVal.scvVec([]),
+        policy: struct({ reclaimable: sc.bool(bool(policy.reclaimable, "reclaimable")), transferable: sc.bool(bool(policy.transferable, "transferable")), tradeable: sc.bool(bool(policy.tradeable, "tradeable")), default_term_secs: sc.u64(u64(policy.default_term_secs, "default term")), trade_fee_bps: sc.u32(u32(policy.trade_fee_bps, "trade fee")) }),
+        owner_epoch: sc.u64(u64(raw.owner_epoch, "owner epoch")),
+    };
+    for (const key of ["owner", "treasury"])
+        fields[key] = sc.address(address(raw[key], "identity", key));
+    for (const key of ["source_registrar", "source_resolver"])
+        fields[key] = sc.address(address(raw[key], "contract", key));
+    for (const key of ["source_registrar_hash", "source_resolver_hash", "registrar_root", "resolver_root"])
+        fields[key] = sc.bytes(bytes32(raw[key], key));
+    for (const key of ["registrar_count", "resolver_count"]) {
+        const count = u32(raw[key], key);
+        if (count < 1 || count > 1024)
+            fail("invalid migration record count");
+        fields[key] = sc.u32(count);
+    }
+    return struct(fields);
+}
+function namespaceLeafHash(network, source, target, leaf) {
+    const pieces = [utf8("soran:registry-migration:v1\0"), unhex(network), sc.address(source).toXDR(), sc.address(target).toXDR(), leaf.toXDR()];
+    const bytes = new Uint8Array(pieces.reduce((n, piece) => n + piece.length, 0));
+    let offset = 0;
+    for (const piece of pieces) {
+        bytes.set(piece, offset);
+        offset += piece.length;
+    }
+    return hex(hash(bytes));
+}
+async function executableHash(context, contract, minimumLedger) {
+    const key = new Contract(contract).getFootprint();
+    const proof = await context.server.getLedgerEntries(key);
+    historicalReadLedger(proof?.latestLedger, minimumLedger);
+    const entry = proof.entries?.[0];
+    if (proof.entries?.length !== 1 || !entry || entry.key.toXDR("base64") !== key.toXDR("base64") || entry.val.type !== "contractData")
+        return fail("executable proof is missing or for another contract");
+    const data = entry.val.value;
+    if (data.contract.toXDR("base64") !== new Contract(contract).address().toScAddress().toXDR("base64") || data.key.type !== "scvLedgerKeyContractInstance" || data.durability !== xdr.ContractDataDurability.persistent || data.val.type !== "scvContractInstance" || data.val.value.executable.type !== "contractExecutableWasm")
+        return fail("executable proof is not the requested persistent Wasm instance");
+    return hex(data.val.value.executable.wasmHash.value);
+}
+/**
+ * Read a completed claim from its original frozen Registrar after cutover.
+ * The canonical Lookup's governance-approved sealed migration is an explicit
+ * trust anchor for source history before freeze. Current code hashes cannot
+ * independently prove that no malicious upgrade occurred before that review.
+ * This function never signs, submits, rewrites an intent or enables a replay.
+ * A verified null is historical absence, not permission to submit an old intent.
+ */
+export async function recoverFrozenClaim(context, input, options) {
+    // Snapshot all inputs before the first await, including the trust anchor.
+    const encoded = claimIntentToScVal(input), intent = claimIntentFromNative(scValToNative(encoded));
+    const lookup = address(exactObject(options, ["lookupId"], "historical recovery options").lookupId, "contract", "trusted Lookup");
+    const target = address(context.registryId, "contract", "successor Registry");
+    const network = hex(hash(utf8(context.passphrase)));
+    if (intent.context.network !== network || intent.context.registry === target)
+        fail("requires the saved original network and a different successor Registry");
+    // The rollout is deliberately bounded to the reviewed single-Nova migration.
+    if (intent.context.namespace !== hex(namespaceNode("nova")))
+        fail("unsupported migration namespace");
+    const request = intent.context, node = sc.bytes(unhex(request.namespace));
+    // Establish completed cutover and freeze BEFORE observing receipt absence.
+    // A later freeze cannot make an earlier null snapshot authoritative.
+    let frozenLedger = 1;
+    const beforeReceipt = async (contract, method) => {
+        const result = await context.readWithLedger(contract, method, []);
+        frozenLedger = historicalReadLedger(result?.ledger, frozenLedger);
+        return result.value;
+    };
+    if (await beforeReceipt(lookup, "registry") !== target)
+        fail("canonical Lookup has not completed the successor cutover");
+    const beforeState = exactObject(await beforeReceipt(target, "migration_status"), ["plan", "imported", "completed", "sealed", "primary_initialized"], "migration status");
+    if (beforeState.sealed !== true || beforeState.primary_initialized !== true)
+        fail("successor migration is not fully sealed");
+    if (await beforeReceipt(request.registrar, "migration_export_frozen") !== true)
+        fail("source Registrar is not frozen before receipt observation");
+    const snapshot = await context.readWithLedger(request.registrar, "claim_receipt", [sc.address(intent.claimant), sc.bytes(unhex(request.requestId))]);
+    const observed = historicalReadLedger(snapshot?.ledger, frozenLedger);
+    const read = async (contract, method, args = []) => {
+        const result = await context.readWithLedger(contract, method, args);
+        historicalReadLedger(result?.ledger, observed);
+        return result.value;
+    };
+    const [lookupRegistry, lookupVersion, version, active, stateRaw, leafRaw, frozen, exportVersion, exportTarget, anchors, attested, sourceHash, sourceRegistryHash] = await Promise.all([
+        read(lookup, "registry"), read(lookup, "registry_migration_version"), read(target, "migration_version"), read(target, "migration_active"),
+        read(target, "migration_status"), read(target, "migration_namespace", [node]),
+        read(request.registrar, "migration_export_frozen"), read(request.registrar, "migration_export_version"), read(request.registrar, "migration_export_target"),
+        read(request.registrar, "anchors"), read(request.registry, "registrar_of", [node]),
+        executableHash(context, request.registrar, observed), executableHash(context, request.registry, observed),
+    ]);
+    if (lookupRegistry !== target || lookupVersion !== 1 || version !== 1 || active !== false)
+        fail("canonical Lookup has not completed the supported successor cutover");
+    const state = exactObject(stateRaw, ["plan", "imported", "completed", "sealed", "primary_initialized"], "migration status");
+    if (state.sealed !== true || state.primary_initialized !== true)
+        fail("successor migration is not fully sealed");
+    const plan = exactObject(state.plan, PLAN_FIELDS, "migration plan");
+    if (plan.source_registry !== request.registry || plan.namespace_count !== 1)
+        fail("migration plan targets another source or namespace set");
+    sameBytes(plan.source_registry_hash, sourceRegistryHash, "source Registry executable");
+    u64(plan.ownership_sequence, "ownership sequence");
+    for (const key of ["primary_source", "primary_target"])
+        address(plan[key], "contract", key);
+    for (const key of ["primary_source_hash", "primary_target_hash", "primary_root"])
+        bytes32(plan[key], key);
+    u32(plan.primary_count, "primary count");
+    listOfOne(state.imported, request.namespace, "imported namespaces");
+    listOfOne(state.completed, request.namespace, "completed namespaces");
+    const leaf = exactObject(leafRaw, LEAF_FIELDS, "migration namespace");
+    const epoch = u64(leaf.owner_epoch, "migration owner epoch");
+    if (epoch === 0n || epoch > plan.ownership_sequence)
+        fail("migration ownership sequence is inconsistent");
+    if (leaf.source_registrar !== request.registrar || !(leaf.label instanceof Uint8Array) || hex(leaf.label) !== hex(utf8("nova")))
+        fail("namespace commitment differs from the saved source contracts");
+    // Historical Resolver/policy/owner settings need not equal current migration
+    // settings: the complete original receipt hash binds their original values.
+    if (sourceHash !== REVIEWED_SOURCE_HASH)
+        fail("source Registrar is not the reviewed frozen export implementation");
+    sameBytes(leaf.source_registrar_hash, sourceHash, "source Registrar executable");
+    sameBytes(plan.namespace_root, namespaceLeafHash(network, request.registry, target, leafScVal(leaf)), "namespace Merkle root");
+    if (frozen !== true || exportVersion !== 1 || exportTarget !== target || attested !== request.registrar || !Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== request.registry)
+        fail("source Registrar is not irreversibly frozen for this exact successor");
+    sameBytes(anchors[1], request.namespace, "source namespace anchor");
+    if (snapshot.value === null)
+        return null;
+    const receipt = claimReceiptFromNative(snapshot.value);
+    historicalReadLedger(receipt.ledger);
+    const name = new Uint8Array(64);
+    name.set(unhex(request.namespace));
+    name.set(hash(utf8(intent.label)), 32);
+    const generation = intent.expectedGeneration === null ? 0n : intent.expectedGeneration + 1n;
+    const expiry = intent.termSecs === 0n ? 0n : receipt.timestamp + intent.termSecs;
+    if (receipt.operation !== "claim" || receipt.intentHash !== nativeIntentHash("claim", encoded) || receipt.holder !== intent.claimant || receipt.node !== hex(hash(name)) || receipt.generation !== generation || receipt.expiresAt !== expiry || receipt.feeToken !== intent.feeToken || receipt.feeAmount !== intent.feeAmount || receipt.feeRecipient !== (intent.feeAmount > 0n ? intent.feeRecipient : null) || receipt.ledger > observed || receipt.timestamp < request.validAfter || receipt.timestamp > request.deadline)
+        fail("source receipt differs from the complete original immutable claim intent");
+    return receipt;
+}

package/dist/native-transport.js

@@ -1,5 +1,6 @@
+import { expectedRegistrarCode } from "./native-code-policy.js";
 import { Contract, Operation, Transaction, TransactionBuilder, rpc, scValToNative, xdr } from "@stellar/stellar-sdk";
-import { NativeClaimError, address, bytes32, hex, namespaceNode, sc, unhex } from "./native-codec.js";
+import { NativeClaimError, address, hex, namespaceNode, sc, unhex } from "./native-codec.js";
 import { assertSignedBodyUnchanged, validateEligibilityAuthorization, validateNativeTransaction } from "./native-auth.js";
 /** This published legacy code has owner-only issuance. Missing RPC data is never legacy detection. */
 const LEGACY_REGISTRAR_HASH = "ed06b3374ff4342b4a2316fc546505132cd8fd35be6666571cf088710af9bbc6";
@@ -8,12 +9,12 @@ export async function verifyRegistrarProvenance(context, registrar, namespace) {
     const node = sc.bytes(unhex(namespace));
     const [attested, tainted, templates, instance] = await Promise.all([
         context.read(context.registryId, "registrar_of", [node]), context.read(context.registryId, "registrar_tainted", [node]),
-        context.read(context.registryId, "template_hashes", []), context.server.getContractInstance(registrar),
+        expectedRegistrarCode(context, namespace), context.server.getContractInstance(registrar),
     ]);
-    if (attested !== registrar || tainted !== false || !Array.isArray(templates) || templates.length !== 2 || instance.executable.type !== "contractExecutableWasm")
+    if (attested !== registrar || tainted !== false || instance.executable.type !== "contractExecutableWasm")
         throw new NativeClaimError("Registrar provenance is unavailable or tainted; refusing authoritative claim/receipt reads", "unavailable");
-    if (hex(bytes32(templates[0], "Registry Registrar template")) !== hex(instance.executable.wasmHash.value))
-        throw new NativeClaimError("Registrar executable differs from immutable Registry template", "unavailable");
+    if (templates !== hex(instance.executable.wasmHash.value))
+        throw new NativeClaimError("Registrar executable differs from Registry-approved code", "unavailable");
 }
 export async function nativeCapability(context, namespace) {
     const node = namespaceNode(namespace), nodeArg = sc.bytes(node);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sorandomains/owner",
-  "version": "0.7.0",
-  "description": "Run your Soran namespace on Stellar \u2014 issue names, manage lifecycle, transfer, and walk the one-way permanence door.",
+  "version": "0.8.0",
+  "description": "Run your Soran namespace on Stellar: configure claims, issue names and manage namespace policies.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",