@sorandomains/owner 0.10.1 → 0.12.0

package/README.md

@@ -5,10 +5,12 @@
 > [release status](https://docs.soran.domains/reference/release-status) for package and service availability.
 
 
-Version 0.8.0 targets Stellar SDK17 (`>=17 <18`). ASCII names
+Version 0.12.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.10.0.
+Lookup is the read entry point in `@sorandomains/lookup` 0.10.0 or later.
+
+Releases older than 0.11.0 (and any built against Lookup 0.6.0 to 0.9.0) default to the retired 5 and 6 September 2026 testnet stacks; upgrade rather than pinning a retired Registry. See [Older versions and retired stacks](../../README.md#older-versions-and-retired-stacks).
 
 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
@@ -36,6 +38,30 @@ const batch = await owner.issueBatch("acme", rows);
 for (const o of batch.outcomes) if (!o.issued) console.warn(o.label, o.reason);
 ```
 
+## Network address policy (unreleased native extension)
+
+```ts
+await owner.setChainPolicy("solo", ["bitcoin", "ethereum", "base", "xrp"]);
+const enabled = await owner.chainPolicy("solo");
+await owner.setChainPolicy("solo", []); // disable all generic network records
+```
+
+The current namespace owner sets one live policy for every existing and future
+holder. The default policy is empty. Disabled records are hidden and cannot be
+updated, but remain stored for re-enablement or removal by their holder. Duplicate
+or unknown IDs are rejected. Each write freshly verifies the native route/version
+and current namespace owner before signing the exact policy transaction. The owner
+chooses available networks; holders choose their own destinations.
+
+All methods require `multichain_version() == 1`; the existing published deployment
+presets are not upgraded by installing this SDK. The source change does not deploy
+contracts or publish packages. See [network formats and integration rules](../multichain/README.md)
+for all 14 supported mainnets, binary formats, and shared codec exports. XRP Ledger
+`xrp` preserves full mainnet X-addresses and their destination tags; `xrpl-evm` is a
+separate EVM network. Never strip an X-address tag. For Stellar use the dedicated
+payment API.
+
+
 ## What's in the box
 
 | Operation | What it does |
@@ -91,7 +117,7 @@ Read the [native claim APIs, security boundaries and complete signup flow](https
 
 ## Verified testnet deployment
 
-See the [deployment manifest](../../deploy/testnet/deployment.json) for confirmed code hashes, transaction receipts and verification scope. Network passphrase: `Test SDF Network ; September 2015`.
+See the [deployment manifest](../../deployments/testnet.json) for confirmed code hashes, transaction receipts and verification scope. Network passphrase: `Test SDF Network ; September 2015`.
 
 | Contract | Address |
 |---|---|
@@ -121,3 +147,42 @@ The older `maxNativeFeeStroops` option remains supported: when the new option is
 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.
+
+## Namespace contract updates
+
+The current namespace owner can update each governed child contract separately:
+
+```ts
+const status = await client.contractUpgradeStatus("acme", "resolver", approvedResolverHash);
+// status: { owner, contractId, currentHash, approved, governed }
+const direction = contractUpgradeDirection("resolver", status.currentHash, approvedResolverHash);
+if (status.approved && status.governed && (direction === "forward" || direction === "unreviewed-target")) {
+  await client.upgradeResolver("acme", approvedResolverHash, {
+    onPrepared: ({ hash, feeStroops }) => savePendingUpdate({ hash, feeStroops }),
+  });
+}
+await client.upgradeRegistrar("acme", approvedRegistrarHash);
+```
+
+Registry approval says a hash may be installed on any namespace; it does not say the move is safe. Governance keeps superseded releases approved, so the chain itself accepts a downgrade (and a reinstall of the installed hash). The SDK therefore refuses, before preparing or signing anything: a reinstall of the installed hash, always; a **superseded** release (`CONTRACT_RELEASES[role].superseded`, a downgrade that drops later fixes); and the latest known release over installed code the SDK cannot place (it may be newer). `contractUpgradeDirection(role, currentHash, targetHash)` returns `"forward"`, `"same"`, `"backward"`, `"unrecognized-current"` or `"unreviewed-target"` (a release newer than this SDK, whose direction it cannot judge: only a reviewed hash from a trusted release record should reach it). A deliberate rollback passes `{ allowDowngrade: true }` to `upgradeRegistrar`/`upgradeResolver` after reviewing the older release for that namespace; it never overrides a reinstall. Keep an application-side allow-list of reviewed `from -> to` pairs, as the Soran console does; `CONTRACT_RELEASES` is a tested mirror of that catalog and lags any release newer than the SDK.
+
+Use exact lowercase 32-byte hex hashes from a reviewed release. Registry governance must approve the implementation for its Registrar or Resolver role first. Approval permits an update; it does not upgrade existing namespace contracts. Each owner-signed transaction changes code at the existing contract address, executes immediately, and pays its own simulated network fee. Storage compatibility is a property of the selected release, not a guarantee for every approved implementation.
+
+`contractUpgradeStatus` is read-only and checks both actual executables against the Registry's per-namespace code pins, clean attestations, Registrar anchors, and Resolver provenance/authority. It does not depend on claim configuration, claim-interface version or fee-token settings. A verified unsupported policy or revoked target is reported through `governed`/`approved`; missing or inconsistent evidence throws. This review is a snapshot: the write rechecks authorization and simulation before signing, and the contracts enforce current approval and ownership on chain.
+
+Both update methods require the current owner's account as the transaction source and use the native transaction's exact operation, authorization-tree and fee checks. They never fall back to the legacy tainting upgrade path or restore archived storage automatically. Active migrations and frozen exports must be resolved before updating. If submission is interrupted, reconcile the error's original `txHash` before retrying. Signature quorum is validated by the network; contract-wallet owner authorization is not supported by these account-source helpers.
+
+### Namespace-wide child-name policy
+
+On a Registrar with `subname_version() == 1`, the current namespace owner can
+call `setSubnamePolicy(namespace, policy)` with `enabled`, `creation-disabled`
+or `suspended`. The default is `creation-disabled`. Changes apply to all parent
+holders, including usernames claimed before the change. `creation-disabled`
+blocks new children while existing ones still work; `suspended` blocks child
+resolution and record edits, preserves records, and permits their removal.
+
+`subnamePolicy`, `subnameRecord` and `subnames(parent, { offset, limit })` provide
+strict on-chain reads. Raw child records and pages include inactive/stale rows;
+they do not establish payment readiness. The parent holder, not a separate
+child wallet, controls `mail.fred.solo`, and its expiry and ownership generation
+are tied to `fred.solo`. Child destinations may differ from the parent holder.

package/dist/funding-history.js

@@ -1,6 +1,6 @@
 import { Address, FeeBumpTransaction, Networks, Transaction, TransactionBuilder, xdr, hash, } from "@stellar/stellar-sdk";
 import { hex } from "./native-codec.js";
-import { FundingError, sponsorQuoteToScVal, } from "./funding-types.js";
+import { FundingError, readBoundedText, sponsorQuoteToScVal, } from "./funding-types.js";
 /** Input must come from the caller's trusted chain provider, never a pasted/API receipt. */
 export function verifySponsorHistory(value, quote, expectedHash, latestLedger, passphrase, provider = "sdf-testnet-horizon") {
     const r = value;
@@ -116,8 +116,8 @@ export class TestnetSponsorHistory {
             return null;
         if (!response.ok)
             throw new FundingError("Sponsorship history unavailable; preserve the quote reference", "unavailable");
-        const body = await response.text();
-        if (body.length > 600000)
+        const body = await readBoundedText(response, 600000);
+        if (body === null)
             throw new FundingError("Sponsorship history response is too large", "unavailable");
         return verifySponsorHistory(JSON.parse(body), quote, hash, latestLedger, passphrase);
     }

package/dist/funding-reader.js

@@ -32,6 +32,10 @@ export class FundingReader {
             .setTimeout(30)
             .build();
         const result = await this.server.simulateTransaction(tx, undefined, undefined, false);
+        // A simulation that needs a restore preamble still reports success, with the
+        // value computed as if the archived entry were live; it is not a live read.
+        if (rpc.Api.isSimulationRestore(result))
+            throw new FundingError("Cannot verify funding contract state: an archived entry needs restoring", "unavailable");
         if (!rpc.Api.isSimulationSuccess(result) ||
             !result.result ||
             !Number.isSafeInteger(result.latestLedger) ||

package/dist/funding-service.js

@@ -1,6 +1,8 @@
 import { TestnetSponsorHistory, sponsorRpcReceipt, } from "./funding-history.js";
 import { claimIntentToScVal } from "./native-types.js";
-import { FundingError, decodeSponsorQuote, sponsoredIdentityToScVal, sponsorIntentHash, } from "./funding-types.js";
+import { FundingError, decodeSponsorQuote, readBoundedText, sponsoredIdentityToScVal, sponsorIntentHash, } from "./funding-types.js";
+/** An offer carries at most a 100000 character transaction plus the quote XDR; nothing legitimate approaches this. */
+const MAX_SERVICE_BODY_BYTES = 262_144;
 /** HTTP transports offers and status. The contract/RPC checks still authorize spending. */
 export class FundingServiceClient {
     client;
@@ -39,8 +41,18 @@ export class FundingServiceClient {
             throw new FundingError("Service response unavailable. Keep your quote reference and recover its status before submitting again.", "unavailable");
         }
         let value;
+        let text;
         try {
-            value = (await r.json());
+            text = await readBoundedText(r, MAX_SERVICE_BODY_BYTES);
+        }
+        catch {
+            text = "";
+        }
+        // Too large is handled like an unreadable body: a submit's outcome is unknown.
+        if (text === null)
+            throw new FundingError("Service response was too large. Keep your quote reference and recover its status before submitting again.", path === "/v1/sponsorship/submit" ? "pending" : "unavailable");
+        try {
+            value = JSON.parse(text);
         }
         catch {
             // A proxy/gateway error page (e.g. a 502 HTML body) is not JSON. A

package/dist/funding-types.d.ts

@@ -1,6 +1,8 @@
 import { xdr } from "@stellar/stellar-sdk";
 import { type PaymentDestination } from "./payment.js";
 import { type ClaimIntent } from "./native-types.js";
+/** Read a response body as text, refusing more than `limit` bytes, declared or streamed, so a hostile or broken endpoint cannot make the client buffer it all. Returns null over the limit. */
+export declare function readBoundedText(response: Response, limit: number): Promise<string | null>;
 export declare class FundingError extends Error {
     readonly kind: "invalid" | "unavailable" | "authorization" | "pending" | "failed";
     readonly transactionHash: string | null;

package/dist/funding-types.js

@@ -2,6 +2,36 @@ import { hash, nativeToScVal, scValToNative, xdr } from "@stellar/stellar-sdk";
 import { address, amount, bool, bytes32, exactObject, hex, hex32, label, paymentDestinationToScVal, sc, struct, u32, u64, unhex, } from "./native-codec.js";
 import { destinationFromNative } from "./payment.js";
 import { claimIntentToScVal } from "./native-types.js";
+/** Read a response body as text, refusing more than `limit` bytes, declared or streamed, so a hostile or broken endpoint cannot make the client buffer it all. Returns null over the limit. */
+export async function readBoundedText(response, limit) {
+    if (Number(response.headers.get("content-length") ?? 0) > limit) {
+        await response.body?.cancel().catch(() => undefined);
+        return null;
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
 export class FundingError extends Error {
     kind;
     transactionHash;

package/dist/index.d.ts

@@ -1,7 +1,50 @@
+import { type SubnamePolicy, type SubnameRecord } from "./names.js";
+export { type SubnamePolicy, type SubnameRecord } from "./names.js";
 import { type HistoricalRecoveryOptions } from "./native-history.js";
 import type { ClaimIntent } from "./native-types.js";
 export type { HistoricalRecoveryOptions } from "./native-history.js";
+/**
+ * @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 ChainNetwork } from "./multichain.js";
+export { CHAIN_NETWORKS, ChainAddressError, chainNetwork, chainPolicyFromNative, chainPolicyToNative, encodeChainAddress, decodeChainAddress, type ChainNetwork, type ChainAddressErrorCode } from "./multichain.js";
 import { type NativeWriteOptions, type NativeCapability } from "./native-transport.js";
+import { type ContractUpgradeOptions, type ContractUpgradeRole, type ContractUpgradeStatus } from "./native-upgrades.js";
+export { CONTRACT_RELEASES, contractUpgradeDirection, type ContractUpgradeDirection, type ContractUpgradeOptions, type ContractUpgradeRole, type ContractUpgradeStatus } from "./native-upgrades.js";
 import { type ClaimSettings, type ClaimConfig, type ClaimUsage, type ApprovalUsage } from "./native-types.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
@@ -160,8 +203,13 @@ export declare class SoranOwner {
     private nativeOwnerWrite;
     /** Current implementation after validating the Registry's native binding. */
     registrarCodeHash(namespace: string): Promise<string>;
-    /** Owner-authorized, Registry-approved update; never uses the legacy tainting path. */
-    upgradeRegistrar(namespace: string, wasmHash: string, options?: NativeWriteOptions): Promise<Submitted>;
+    /** Verify both children and the selected implementation without signing or reading claim settings. */
+    contractUpgradeStatus(namespace: string, role: ContractUpgradeRole, wasmHash: string): Promise<ContractUpgradeStatus>;
+    private upgradeContract;
+    /** Current-owner, Registry-approved update; never uses the legacy tainting path. */
+    upgradeRegistrar(namespace: string, wasmHash: string, options?: ContractUpgradeOptions): Promise<Submitted>;
+    /** Current-owner, Registry-approved Resolver update with exact native authorization. */
+    upgradeResolver(namespace: string, wasmHash: string, options?: ContractUpgradeOptions): Promise<Submitted>;
     configureClaims(namespace: string, settings: ClaimSettings, options?: NativeWriteOptions): Promise<Submitted & {
         config: ClaimConfig;
     }>;
@@ -246,6 +294,12 @@ export declare class SoranOwner {
      * Refused (ResolverFrozen) once the namespace is permanent.
      */
     setResolver(namespace: string, resolver: string | null): Promise<Submitted>;
+    /** Networks currently enabled for all holders, including names already claimed. */
+    chainPolicy(namespace: string): Promise<ChainNetwork[]>;
+    /** Set the namespace-wide network allowlist. Empty disables all multichain records.
+     * Disabled destinations remain stored and become visible if re-enabled. */
+    setChainPolicy(namespace: string, networks: readonly ChainNetwork[]): Promise<Submitted>;
+    private multichainResolverOf;
     /** The namespace's immutable issuance policy. */
     policy(namespace: string): Promise<NamespacePolicy>;
     /** Has the namespace passed the one-way door? */
@@ -254,6 +308,30 @@ export declare class SoranOwner {
     nameState(namespace: string, label: string): Promise<NameState | null>;
     /** The pending namespace transfer on the Registry, or null. */
     pendingNamespaceTransfer(namespace: string): Promise<unknown | null>;
+    private subnameReader;
+    /** Live namespace policy. Creation-disabled keeps existing children usable; suspended hides them. */
+    subnamePolicy(namespace: string): Promise<SubnamePolicy>;
+    /** Raw child state, including tombstones and stale parent generations; this is not payment resolution. */
+    subnameRecord(name: string): Promise<SubnameRecord | null>;
+    /** Bounded on-chain historical labels, including removed children. Re-read metadata before treating a child as active. */
+    subnames(parent: string, options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        parent: string;
+        policy: SubnamePolicy;
+        records: {
+            parentNode: Uint8Array;
+            parentGeneration: bigint;
+            generation: bigint;
+            address: string;
+            active: boolean;
+            name: string;
+        }[];
+        offset: number;
+        nextOffset: number | null;
+    }>;
+    setSubnamePolicy(namespace: string, policy: SubnamePolicy): Promise<Submitted>;
     private readRecord;
     private readRecords;
     /** Simulation-only contract read — no signature, no fee, no state change. */
@@ -274,6 +352,8 @@ export declare class SoranOwner {
      * auth demands an address the envelope signature cannot satisfy.
      */
     private assertSatisfiableAuth;
+    /** Authorize exactly the selected policy with no additional child operations. */
+    private assertChainPolicyIntent;
     private attempt;
     private restore;
     private confirm;

package/dist/index.js

@@ -1,3 +1,5 @@
+import { subnamePolicyToNative } from "./names.js";
+import { createSubnameReader, SUBNAME_REGISTRAR_ERRORS } from "./subnames-client.js";
 import { recoverFrozenClaim, historicalReadLedger } from "./native-history.js";
 /**
  * @sorandomains/owner — the write-side SDK for Soran namespace owners.
@@ -36,6 +38,8 @@ import { recoverFrozenClaim, historicalReadLedger } from "./native-history.js";
  * that one only. The few reads here (policy, pending transfers, records) exist
  * to support write flows.
  */
+import { chainPolicyFromNative, chainPolicyToNative } from "./multichain.js";
+export { CHAIN_NETWORKS, ChainAddressError, chainNetwork, chainPolicyFromNative, chainPolicyToNative, encodeChainAddress, decodeChainAddress } from "./multichain.js";
 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). */
@@ -87,6 +91,8 @@ function decodeIssuedEvents(events, registrarId) {
 }
 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 { contractUpgradeStatus as readContractUpgradeStatus, contractUpgradeDirection, upgradeHash } from "./native-upgrades.js";
+export { CONTRACT_RELEASES, contractUpgradeDirection } from "./native-upgrades.js";
 import { claimSettingsToScVal, claimConfigFromNative, claimLabelToScVal, claimUsageFromNative, approvalUsageFromNative } from "./native-types.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
@@ -183,6 +189,15 @@ const REGISTRAR_ERRORS = {
     49: "MigrationUnavailable",
     50: "MigrationUnsupported",
     51: "PermanentLockDisabled",
+    52: "InvalidRenewalGrace",
+    53: "SubnameCreationDisabled", 54: "SubnamesSuspended",
+    55: "SubnameGenerationMismatch", 56: "SubnameIndexUnavailable",
+};
+/** Error names shared by native multichain Resolver reads and writes. */
+const CHAIN_RESOLVER_ERRORS = {
+    2: "NotInitialized", 7: "InvalidAuthority", 33: "UnsupportedCoinType",
+    34: "ChainDisabled", 35: "InvalidChainAddress", 36: "InvalidChainPolicy",
+    37: "ChainContextMismatch", 38: "ChainUnavailable",
 };
 /** Registry contract error codes, by number. */
 const REGISTRY_ERRORS = {
@@ -227,6 +242,7 @@ const REGISTRY_ERRORS = {
     39: "UpgradePolicyMismatch",
     40: "UpgradeNotApproved",
     41: "PermanentLockDisabled",
+    42: "BatchTooLarge",
 };
 /** Errors for a submit the network REJECTED as a stale sequence: nothing was included, so one retry with a fresh sequence is safe. */
 const BAD_SEQ_REJECTED = new WeakSet();
@@ -428,23 +444,46 @@ export class SoranOwner {
             throw new NativeClaimError("Registrar is not a Wasm contract", "unavailable");
         return nativeHex(instance.executable.wasmHash.value);
     }
-    /** Owner-authorized, Registry-approved update; never uses the legacy tainting path. */
-    async upgradeRegistrar(namespace, wasmHash, options = {}) {
-        if (!/^[a-f0-9]{64}$/.test(wasmHash))
-            throw new NativeClaimError("Registrar implementation hash must be lowercase hex32");
-        const bytes = Uint8Array.from(wasmHash.match(/../g), value => parseInt(value, 16));
-        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
-        const [governed, approved, current] = await Promise.all([
-            this.read(cap.registrar, "upgrade_policy_version", []),
-            this.read(this.registryId, "implementation_approved", [nativeSc.u32(0), nativeSc.bytes(bytes)]),
-            this.registrarCodeHash(namespace),
-        ]);
-        if (governed !== 1 || approved !== true)
-            throw new NativeClaimError("This Registrar upgrade is not approved by the Registry", "authorization");
-        if (current === wasmHash)
-            throw new NativeClaimError("This Registrar implementation is already installed");
-        const result = await this.nativeOwnerWrite(namespace, "upgrade", [nativeSc.bytes(bytes)], options);
-        return { hash: result.hash, ledger: result.ledger };
+    /** Verify both children and the selected implementation without signing or reading claim settings. */
+    contractUpgradeStatus(namespace, role, wasmHash) {
+        return readContractUpgradeStatus(this.nativeContext(), normalizeLabel(namespace), role, wasmHash);
+    }
+    upgradeContract(namespace, role, wasmHash, options) {
+        return this.serialize(async () => {
+            const args = [upgradeHash(wasmHash)];
+            const context = this.nativeContext();
+            const status = await readContractUpgradeStatus(context, normalizeLabel(namespace), role, wasmHash);
+            const source = nativeAddress(await this.signer.publicKey(), "account", "owner transaction source");
+            if (source !== status.owner)
+                throw new NativeClaimError("the current namespace owner must authorize this change", "authorization");
+            if (!status.governed || !status.approved)
+                throw new NativeClaimError("This contract upgrade is not approved by the Registry", "authorization");
+            const direction = contractUpgradeDirection(role, status.currentHash, wasmHash);
+            if (direction === "same")
+                throw new NativeClaimError("This contract implementation is already installed");
+            // Registry approval says a hash may be installed, not that the move is safe:
+            // older releases stay approved, and a downgrade drops their fixes.
+            if (options.allowDowngrade !== true) {
+                if (direction === "backward")
+                    throw new NativeClaimError("Refusing to install a superseded implementation (a downgrade that drops later fixes). Install the latest reviewed release, or pass allowDowngrade: true only after reviewing the older release for this namespace.", "authorization");
+                if (direction === "unrecognized-current")
+                    throw new NativeClaimError("This namespace runs an implementation this SDK does not recognise, so installing the latest known release may be a downgrade. Update the SDK, or pass allowDowngrade: true after verifying the installed release is older.", "authorization");
+            }
+            const result = await sendNative(context, {
+                source, contract: status.contractId, method: "upgrade", args,
+                sourceInvocation: { contract: status.contractId, method: "upgrade", args },
+                maxFeeStroops: context.maxFeeStroops,
+            }, options);
+            return { hash: result.hash, ledger: result.ledger };
+        });
+    }
+    /** Current-owner, Registry-approved update; never uses the legacy tainting path. */
+    upgradeRegistrar(namespace, wasmHash, options = {}) {
+        return this.upgradeContract(namespace, "registrar", wasmHash, options);
+    }
+    /** Current-owner, Registry-approved Resolver update with exact native authorization. */
+    upgradeResolver(namespace, wasmHash, options = {}) {
+        return this.upgradeContract(namespace, "resolver", wasmHash, options);
     }
     async configureClaims(namespace, settings, options = {}) {
         const encoded = claimSettingsToScVal(settings);
@@ -700,6 +739,44 @@ export class SoranOwner {
         const r = await this.invoke(this.registryId, "set_resolver", [nodeArg(namehash(namespace)), resolver === null ? xdr.ScVal.scvVoid() : addrArg(resolver)], REGISTRY_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
     }
+    /** Networks currently enabled for all holders, including names already claimed. */
+    async chainPolicy(namespace) {
+        namespace = normalizeLabel(namespace);
+        const resolver = await this.multichainResolverOf(namespace);
+        return chainPolicyFromNative(await this.read(resolver, "chain_policy", []));
+    }
+    /** Set the namespace-wide network allowlist. Empty disables all multichain records.
+     * Disabled destinations remain stored and become visible if re-enabled. */
+    async setChainPolicy(namespace, networks) {
+        namespace = normalizeLabel(namespace);
+        const coins = chainPolicyToNative(networks);
+        const resolver = await this.multichainResolverOf(namespace);
+        await this.assertOwner(namespace);
+        const result = await this.invoke(resolver, "set_chain_policy", [
+            xdr.ScVal.scvVec(coins.map(coin => nativeToScVal(coin, { type: "u32" }))),
+        ], CHAIN_RESOLVER_ERRORS);
+        return { hash: result.hash, ledger: result.ledger };
+    }
+    async multichainResolverOf(namespace) {
+        const nsNode = namehash(namespace);
+        const args = [nodeArg(nsNode)];
+        const [resolver, registrar] = await Promise.all([
+            this.read(this.registryId, "resolver_of", args), this.read(this.registryId, "registrar_of", args),
+        ]);
+        if (typeof resolver !== "string" || !StrKey.isValidContract(resolver) || typeof registrar !== "string" || !StrKey.isValidContract(registrar))
+            throw new OwnerError("namespace has no native multichain route", this.registryId, "resolver_of", null, "UnsupportedImplementation");
+        const [anchor, authority, version, anchors] = await Promise.all([
+            this.read(resolver, "registry", []), this.read(resolver, "authority", []),
+            this.read(resolver, "multichain_version", []), this.read(registrar, "anchors", []),
+        ]);
+        if (anchor !== this.registryId || authority !== registrar || !Array.isArray(anchors) || anchors.length !== 2 ||
+            anchors[0] !== this.registryId || !(anchors[1] instanceof Uint8Array) || anchors[1].length !== 32 ||
+            !nsNode.every((byte, index) => byte === anchors[1][index]))
+            throw new OwnerError("multichain Resolver route does not match this Registry and namespace", resolver, "registry", 37, "ChainContextMismatch");
+        if (version !== 1)
+            throw new OwnerError("unsupported multichain Resolver version", resolver, "multichain_version", null, "UnsupportedImplementation");
+        return resolver;
+    }
     // ---- reads that support write flows --------------------------------------
     /** The namespace's immutable issuance policy. */
     async policy(namespace) {
@@ -730,6 +807,20 @@ export class SoranOwner {
         return this.read(this.registryId, "pending_transfer", [nodeArg(namehash(namespace))]);
     }
     // ---- internals -----------------------------------------------------------
+    subnameReader() { return createSubnameReader({ registryId: this.registryId, error: message => new OwnerError(message), read: (id, fn, args) => this.read(id, fn, args) }); }
+    /** Live namespace policy. Creation-disabled keeps existing children usable; suspended hides them. */
+    async subnamePolicy(namespace) { return this.subnameReader().policy(namespace); }
+    /** Raw child state, including tombstones and stale parent generations; this is not payment resolution. */
+    async subnameRecord(name) { return this.subnameReader().record(name); }
+    /** Bounded on-chain historical labels, including removed children. Re-read metadata before treating a child as active. */
+    async subnames(parent, options = {}) { return this.subnameReader().list(parent, options); }
+    async setSubnamePolicy(namespace, policy) {
+        const native = subnamePolicyToNative(policy);
+        const ctx = await this.subnameReader().context(namespace);
+        await this.assertOwner(ctx.namespace);
+        const result = await this.invoke(ctx.registrar, "set_subname_policy", [xdr.ScVal.scvVec([nativeToScVal(native[0], { type: "symbol" })])], { ...REGISTRAR_ERRORS, ...SUBNAME_REGISTRAR_ERRORS });
+        return { hash: result.hash, ledger: result.ledger };
+    }
     async readRecord(registrarId, label) {
         const rec = (await this.read(registrarId, "record_of", [labelArg(label)]));
         if (!rec)
@@ -762,7 +853,8 @@ export class SoranOwner {
             .build();
         const sim = await this.server.simulateTransaction(tx);
         if (rpc.Api.isSimulationError(sim)) {
-            throw typedError(contractId, fn, sim.error, {});
+            const errors = fn.startsWith("subname_") ? SUBNAME_REGISTRAR_ERRORS : ["chain_policy", "chain_address", "multichain_version"].includes(fn) ? CHAIN_RESOLVER_ERRORS : {};
+            throw typedError(contractId, fn, sim.error, errors);
         }
         // An archived entry is NOT absence: reads cannot restore (no signer),
         // so surface the state honestly instead of reporting "does not exist".
@@ -838,6 +930,26 @@ export class SoranOwner {
                 : `${fn}: this operation must be authorized by ${required}, but the signer is ${pub} — use that account's signer`, contractId, fn);
         }
     }
+    /** Authorize exactly the selected policy with no additional child operations. */
+    assertChainPolicyIntent(prepared, pub, contractId, fn, args) {
+        if (!["set_chain_policy", "set_subname_policy"].includes(fn))
+            return;
+        if (prepared.source !== pub || prepared.operations.length !== 1)
+            throw new OwnerError("unexpected chain policy transaction", contractId, fn);
+        const op = prepared.operations[0];
+        if (op.type !== "invokeHostFunction" || (op.source !== undefined && op.source !== pub) || op.func.type !== "hostFunctionTypeInvokeContract")
+            throw new OwnerError("unexpected chain policy operation", contractId, fn);
+        const call = op.func.invokeContract;
+        if (Address.fromScAddress(call.contractAddress).toString() !== contractId || call.functionName.toString() !== fn ||
+            call.args.length !== args.length || call.args.some((value, i) => value.toXDR("base64") !== args[i].toXDR("base64")))
+            throw new OwnerError("chain policy operation differs from selected intent", contractId, fn);
+        if (!op.auth || op.auth.length !== 1 || op.auth[0].credentials.type !== "sorobanCredentialsSourceAccount")
+            throw new OwnerError("chain policy requires exactly the source owner authorization", contractId, fn);
+        const root = op.auth[0].rootInvocation;
+        if (root.function.type !== "sorobanAuthorizedFunctionTypeContractFn" || root.subInvocations.length ||
+            root.function.contractFn.toXDR("base64") !== call.toXDR("base64"))
+            throw new OwnerError("chain policy authorization differs from selected intent", contractId, fn);
+    }
     async attempt(contractId, fn, args, errNames) {
         const pub = await this.signer.publicKey();
         const contract = new Contract(contractId);
@@ -868,6 +980,7 @@ export class SoranOwner {
         const prepared = rpc.assembleTransaction(tx, sim).build();
         this.assertNetworkFee(prepared.fee, fn);
         this.assertSatisfiableAuth(prepared, pub, contractId, fn);
+        this.assertChainPolicyIntent(prepared, pub, contractId, fn, args);
         // 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