@sorandomains/owner 0.11.0 → 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 |
 |---|---|
@@ -129,7 +155,8 @@ 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 }
-if (status.approved && status.governed && status.currentHash !== approvedResolverHash) {
+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 }),
   });
@@ -137,8 +164,25 @@ if (status.approved && status.governed && status.currentHash !== approvedResolve
 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,9 +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 ContractUpgradeRole, type ContractUpgradeStatus } from "./native-upgrades.js";
-export type { ContractUpgradeRole, ContractUpgradeStatus } from "./native-upgrades.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";
@@ -166,9 +207,9 @@ export declare class SoranOwner {
     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?: NativeWriteOptions): Promise<Submitted>;
+    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?: NativeWriteOptions): Promise<Submitted>;
+    upgradeResolver(namespace: string, wasmHash: string, options?: ContractUpgradeOptions): Promise<Submitted>;
     configureClaims(namespace: string, settings: ClaimSettings, options?: NativeWriteOptions): Promise<Submitted & {
         config: ClaimConfig;
     }>;
@@ -253,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? */
@@ -261,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. */
@@ -281,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,7 +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, upgradeHash } from "./native-upgrades.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";
@@ -184,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 = {
@@ -228,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();
@@ -443,8 +458,17 @@ export class SoranOwner {
                 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");
-            if (status.currentHash === wasmHash)
+            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 },
@@ -715,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) {
@@ -745,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)
@@ -777,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".
@@ -853,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);
@@ -883,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

package/dist/multichain.d.ts

@@ -0,0 +1,99 @@
+export declare const CHAIN_NETWORKS: readonly Readonly<{
+    readonly id: "bitcoin";
+    readonly name: "Bitcoin";
+    readonly coinType: 0;
+    readonly encoding: "bitcoin-script";
+    readonly caip2: "bip122:000000000019d6689c085ae165831e93";
+} | {
+    readonly id: "ethereum";
+    readonly name: "Ethereum";
+    readonly coinType: 60;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:1";
+} | {
+    readonly id: "solana";
+    readonly name: "Solana";
+    readonly coinType: 501;
+    readonly encoding: "solana";
+    readonly caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+} | {
+    readonly id: "optimism";
+    readonly name: "Optimism";
+    readonly coinType: 2147483658;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:10";
+} | {
+    readonly id: "polygon";
+    readonly name: "Polygon";
+    readonly coinType: 2147483785;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:137";
+} | {
+    readonly id: "base";
+    readonly name: "Base";
+    readonly coinType: 2147492101;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:8453";
+} | {
+    readonly id: "arbitrum";
+    readonly name: "Arbitrum";
+    readonly coinType: 2147525809;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:42161";
+} | {
+    readonly id: "bsc";
+    readonly name: "BNB Smart Chain";
+    readonly coinType: 2147483704;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:56";
+} | {
+    readonly id: "avalanche";
+    readonly name: "Avalanche C-Chain";
+    readonly coinType: 2147526762;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:43114";
+} | {
+    readonly id: "xrp";
+    readonly name: "XRP Ledger";
+    readonly coinType: 144;
+    readonly encoding: "xrp";
+    readonly caip2: "xrpl:0";
+} | {
+    readonly id: "tron";
+    readonly name: "Tron";
+    readonly coinType: 195;
+    readonly encoding: "tron";
+    readonly caip2: "tron:728126428";
+} | {
+    readonly id: "arc";
+    readonly name: "Arc";
+    readonly coinType: 2147488690;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:5042";
+} | {
+    readonly id: "tempo";
+    readonly name: "Tempo";
+    readonly coinType: 2147487865;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:4217";
+} | {
+    readonly id: "xrpl-evm";
+    readonly name: "XRPL EVM";
+    readonly coinType: 2148923648;
+    readonly encoding: "evm";
+    readonly caip2: "eip155:1440000";
+}>[];
+export type ChainNetwork = typeof CHAIN_NETWORKS[number]["id"];
+export type ChainAddressErrorCode = "UNSUPPORTED_NETWORK" | "INVALID_ADDRESS" | "INVALID_POLICY";
+export declare class ChainAddressError extends Error {
+    readonly code: ChainAddressErrorCode;
+    constructor(message: string, code: ChainAddressErrorCode);
+}
+export declare function chainNetwork(id: string): typeof CHAIN_NETWORKS[number];
+/** Strictly decode the native Vec<u32> policy; never silently discard unknown networks. */
+export declare function chainPolicyFromNative(raw: unknown): ChainNetwork[];
+export declare function chainPolicyToNative(networks: readonly ChainNetwork[]): number[];
+/** Validate and encode an explicitly selected destination network. Never infer a network. */
+export declare function encodeChainAddress(network: ChainNetwork, address: string): Uint8Array;
+/** Strictly decode native binary records to their canonical human-readable form. */
+export declare function decodeChainAddress(network: ChainNetwork, bytes: Uint8Array): string;

package/dist/multichain.js

@@ -0,0 +1,204 @@
+/** Canonical multichain address codecs. Run sdk/multichain/sync.mjs after editing.
+ * Binary records follow ENSIP-9/11: EVM raw 20 bytes; Bitcoin scriptPubKey;
+ * Solana raw 32-byte public key. Stellar retains its separate payment/memo API.
+ * These are destination-network mainnet addresses even on Soran testnet.
+ */
+import { base58, base58xrp, bech32, bech32m, createBase58check } from "@scure/base";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+export const CHAIN_NETWORKS = Object.freeze([
+    { id: "bitcoin", name: "Bitcoin", coinType: 0, encoding: "bitcoin-script", caip2: "bip122:000000000019d6689c085ae165831e93" },
+    { id: "ethereum", name: "Ethereum", coinType: 60, encoding: "evm", caip2: "eip155:1" },
+    { id: "solana", name: "Solana", coinType: 501, encoding: "solana", caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" },
+    { id: "optimism", name: "Optimism", coinType: 2147483658, encoding: "evm", caip2: "eip155:10" },
+    { id: "polygon", name: "Polygon", coinType: 2147483785, encoding: "evm", caip2: "eip155:137" },
+    { id: "base", name: "Base", coinType: 2147492101, encoding: "evm", caip2: "eip155:8453" },
+    { id: "arbitrum", name: "Arbitrum", coinType: 2147525809, encoding: "evm", caip2: "eip155:42161" },
+    { id: "bsc", name: "BNB Smart Chain", coinType: 2147483704, encoding: "evm", caip2: "eip155:56" },
+    { id: "avalanche", name: "Avalanche C-Chain", coinType: 2147526762, encoding: "evm", caip2: "eip155:43114" },
+    { id: "xrp", name: "XRP Ledger", coinType: 144, encoding: "xrp", caip2: "xrpl:0" },
+    { id: "tron", name: "Tron", coinType: 195, encoding: "tron", caip2: "tron:728126428" },
+    { id: "arc", name: "Arc", coinType: 2147488690, encoding: "evm", caip2: "eip155:5042" },
+    { id: "tempo", name: "Tempo", coinType: 2147487865, encoding: "evm", caip2: "eip155:4217" },
+    { id: "xrpl-evm", name: "XRPL EVM", coinType: 2148923648, encoding: "evm", caip2: "eip155:1440000" },
+].map(network => Object.freeze(network)));
+export class ChainAddressError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "ChainAddressError";
+    }
+}
+export function chainNetwork(id) {
+    const network = CHAIN_NETWORKS.find(network => network.id === id);
+    if (!network)
+        throw new ChainAddressError(`unsupported address network: ${String(id)}`, "UNSUPPORTED_NETWORK");
+    return network;
+}
+/** Strictly decode the native Vec<u32> policy; never silently discard unknown networks. */
+export function chainPolicyFromNative(raw) {
+    if (!Array.isArray(raw) || raw.length > CHAIN_NETWORKS.length)
+        throw new ChainAddressError("invalid chain policy: expected supported coin types", "INVALID_POLICY");
+    const seen = new Set();
+    return Array.from(raw, coin => {
+        const network = CHAIN_NETWORKS.find(network => network.coinType === coin);
+        if (typeof coin !== "number" || !Number.isInteger(coin) || !network || seen.has(coin))
+            throw new ChainAddressError("invalid chain policy: unknown or duplicate coin type", "INVALID_POLICY");
+        seen.add(coin);
+        return network.id;
+    });
+}
+export function chainPolicyToNative(networks) {
+    if (!Array.isArray(networks) || networks.length > CHAIN_NETWORKS.length)
+        throw new ChainAddressError("invalid chain policy", "INVALID_POLICY");
+    const coins = Array.from(networks, network => chainNetwork(network).coinType);
+    chainPolicyFromNative(coins);
+    return coins;
+}
+const btc58 = createBase58check(sha256);
+const hex = (bytes) => Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+const fromHex = (value) => Uint8Array.from(value.match(/../g), part => Number.parseInt(part, 16));
+const nonzero = (bytes) => bytes.some(byte => byte !== 0);
+const invalid = (message) => { throw new ChainAddressError(message, "INVALID_ADDRESS"); };
+function evmChecksum(bytes) {
+    const lower = hex(bytes);
+    const digest = hex(keccak_256(new TextEncoder().encode(lower)));
+    return "0x" + [...lower].map((char, index) => Number.parseInt(digest[index], 16) >= 8 ? char.toUpperCase() : char).join("");
+}
+function encodeBitcoin(address) {
+    if (/^(bc1|tb1|bcrt1)/i.test(address)) {
+        // The checksum encoding is tied to witness version: BIP173 v0, BIP350 v1.
+        let decoded;
+        let variant;
+        try {
+            decoded = bech32.decode(address);
+            variant = 0;
+        }
+        catch {
+            decoded = bech32m.decode(address);
+            variant = 1;
+        }
+        if (decoded.prefix !== "bc")
+            return invalid("Bitcoin address must use mainnet");
+        const version = decoded.words[0];
+        if (version !== variant)
+            return invalid("unsupported Bitcoin witness version or checksum");
+        const program = bech32.fromWords(decoded.words.slice(1));
+        if ((version === 0 && program.length !== 20 && program.length !== 32) || (version === 1 && program.length !== 32))
+            return invalid("invalid Bitcoin witness program length");
+        return Uint8Array.from([version === 0 ? 0 : 0x51, program.length, ...program]);
+    }
+    const decoded = btc58.decode(address);
+    if (decoded.length !== 21)
+        return invalid("invalid Bitcoin address length");
+    if (decoded[0] === 0)
+        return Uint8Array.from([0x76, 0xa9, 0x14, ...decoded.slice(1), 0x88, 0xac]);
+    if (decoded[0] === 5)
+        return Uint8Array.from([0xa9, 0x14, ...decoded.slice(1), 0x87]);
+    return invalid("Bitcoin address must use mainnet");
+}
+function decodeBitcoin(bytes) {
+    if (bytes.length === 25 && bytes[0] === 0x76 && bytes[1] === 0xa9 && bytes[2] === 0x14 && bytes[23] === 0x88 && bytes[24] === 0xac)
+        return btc58.encode(Uint8Array.from([0, ...bytes.slice(3, 23)]));
+    if (bytes.length === 23 && bytes[0] === 0xa9 && bytes[1] === 0x14 && bytes[22] === 0x87)
+        return btc58.encode(Uint8Array.from([5, ...bytes.slice(2, 22)]));
+    if (bytes[0] === 0 && (bytes[1] === 20 || bytes[1] === 32) && bytes.length === bytes[1] + 2)
+        return bech32.encode("bc", [0, ...bech32.toWords(bytes.slice(2))]);
+    if (bytes[0] === 0x51 && bytes[1] === 32 && bytes.length === 34)
+        return bech32m.encode("bc", [1, ...bech32m.toWords(bytes.slice(2))]);
+    return invalid("unsupported or malformed Bitcoin scriptPubKey");
+}
+/** XRP keeps the version prefix and full X-address tag payload. A classic
+ * address alone cannot represent an exchange's required destination tag. */
+function validateXrp(bytes) {
+    if (bytes.length === 21 && bytes[0] === 0 && nonzero(bytes.slice(1)))
+        return;
+    if (bytes.length === 31 && bytes[0] === 5 && bytes[1] === 0x44 && nonzero(bytes.slice(2, 22)) &&
+        (bytes[22] === 0 || bytes[22] === 1) && !nonzero(bytes.slice(27)) &&
+        (bytes[22] === 1 || !nonzero(bytes.slice(23, 27))))
+        return;
+    return invalid("invalid XRP classic or mainnet X-address payload");
+}
+function encodeXrp(bytes) {
+    validateXrp(bytes);
+    return base58xrp.encode(Uint8Array.from([...bytes, ...sha256(sha256(bytes)).slice(0, 4)]));
+}
+function decodeXrp(address) {
+    const decoded = base58xrp.decode(address);
+    if (decoded.length !== 25 && decoded.length !== 35)
+        return invalid("invalid XRP address length");
+    const bytes = decoded.slice(0, -4);
+    const checksum = sha256(sha256(bytes)).slice(0, 4);
+    if (!checksum.every((byte, index) => byte === decoded[bytes.length + index]))
+        return invalid("invalid XRP address checksum");
+    validateXrp(bytes);
+    if (encodeXrp(bytes) !== address)
+        return invalid("noncanonical XRP address");
+    return bytes;
+}
+function validateTron(bytes) {
+    if (bytes.length !== 21 || bytes[0] !== 0x41 || !nonzero(bytes.slice(1)))
+        return invalid("invalid Tron address payload");
+}
+/** Validate and encode an explicitly selected destination network. Never infer a network. */
+export function encodeChainAddress(network, address) {
+    const metadata = chainNetwork(network);
+    if (typeof address !== "string" || address.length === 0 || address.length > 128 || /\s/.test(address))
+        return invalid("address must be a nonempty string without whitespace");
+    try {
+        if (metadata.encoding === "bitcoin-script")
+            return encodeBitcoin(address);
+        if (metadata.encoding === "xrp")
+            return decodeXrp(address);
+        if (metadata.encoding === "tron") {
+            const bytes = btc58.decode(address);
+            validateTron(bytes);
+            if (!address.startsWith("T") || btc58.encode(bytes) !== address)
+                return invalid("Tron address must use canonical T format");
+            return bytes;
+        }
+        if (metadata.encoding === "solana") {
+            const bytes = base58.decode(address);
+            if (bytes.length !== 32 || !nonzero(bytes) || base58.encode(bytes) !== address)
+                return invalid("invalid Solana public key");
+            return bytes;
+        }
+        if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+            return invalid("EVM address must contain 0x and 40 hexadecimal digits");
+        const bytes = fromHex(address.slice(2));
+        if (!nonzero(bytes))
+            return invalid("zero EVM address is not a payment destination");
+        const body = address.slice(2);
+        if (body !== body.toLowerCase() && body !== body.toUpperCase() && address !== evmChecksum(bytes))
+            return invalid("invalid EIP-55 address checksum");
+        return bytes;
+    }
+    catch (error) {
+        if (error instanceof ChainAddressError)
+            throw error;
+        return invalid(`invalid ${metadata.name} address or checksum`);
+    }
+}
+/** Strictly decode native binary records to their canonical human-readable form. */
+export function decodeChainAddress(network, bytes) {
+    const metadata = chainNetwork(network);
+    if (!(bytes instanceof Uint8Array))
+        return invalid("chain address must be native bytes");
+    if (metadata.encoding === "bitcoin-script")
+        return decodeBitcoin(bytes);
+    if (metadata.encoding === "xrp")
+        return encodeXrp(bytes);
+    if (metadata.encoding === "tron") {
+        validateTron(bytes);
+        return btc58.encode(bytes);
+    }
+    if (metadata.encoding === "solana") {
+        if (bytes.length !== 32 || !nonzero(bytes))
+            return invalid("invalid Solana public key bytes");
+        return base58.encode(bytes);
+    }
+    if (bytes.length !== 20 || !nonzero(bytes))
+        return invalid("invalid EVM address bytes");
+    return evmChecksum(bytes);
+}

package/dist/names.d.ts

@@ -0,0 +1,29 @@
+export type ParsedResolvableName = {
+    name: string;
+    label: string;
+    namespace: string;
+    parent: string | null;
+    parentLabel: string;
+    childLabel: string | null;
+};
+export declare function parseNamespace(input: string): string;
+export declare function parseResolvableName(input: string): ParsedResolvableName;
+export declare function resolvableNameNode(input: string): Uint8Array;
+export type SubnamePolicy = "enabled" | "creation-disabled" | "suspended";
+export declare function subnamePolicyToNative(value: SubnamePolicy): string[];
+export declare function subnamePolicyFromNative(raw: unknown): SubnamePolicy;
+export type SubnameRecord = {
+    parentNode: Uint8Array;
+    parentGeneration: bigint;
+    generation: bigint;
+    address: string;
+    active: boolean;
+};
+export declare function exactGeneration(value: unknown): bigint;
+/** Address validity is checked by each caller's Stellar SDK, without coercion. */
+export declare function subnameRecordFromNative(raw: unknown, expectedParentNode: Uint8Array): SubnameRecord | null;
+export declare function subnameLabelsFromNative(raw: unknown, limit: number): string[];
+export declare function subnamePageInput(offset?: number, limit?: number): {
+    offset: number;
+    limit: number;
+};

package/dist/names.js

@@ -0,0 +1,83 @@
+// Generated by sdk/names/sync.mjs; edit sdk/names/names.ts.
+/** Canonical resolution grammar. Registration and lifecycle actions still use two labels. */
+import { sha256 } from "@noble/hashes/sha2.js";
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+export function parseNamespace(input) {
+    if (typeof input !== "string" || !/^[A-Za-z0-9-]+$/.test(input))
+        throw new Error("invalid namespace");
+    const value = input.toLowerCase();
+    if (!LABEL.test(value))
+        throw new Error("invalid namespace");
+    return value;
+}
+export function parseResolvableName(input) {
+    if (typeof input !== "string" || !/^[A-Za-z0-9.-]+$/.test(input) || input.length > 191)
+        throw new Error("name must contain two or three ASCII labels");
+    const name = input.toLowerCase(), parts = name.split(".");
+    if ((parts.length !== 2 && parts.length !== 3) || !parts.every(label => LABEL.test(label)))
+        throw new Error("expected label.namespace or child.label.namespace");
+    const namespace = parts.at(-1), parentLabel = parts.at(-2);
+    return { name, label: parts.slice(0, -1).join("."), namespace, parent: parts.length === 3 ? `${parentLabel}.${namespace}` : null,
+        parentLabel, childLabel: parts.length === 3 ? parts[0] : null };
+}
+export function resolvableNameNode(input) {
+    const parts = parseResolvableName(input).name.split(".").reverse();
+    let node = new Uint8Array(32);
+    for (const part of parts) {
+        const joined = new Uint8Array(64);
+        joined.set(node);
+        joined.set(sha256(new TextEncoder().encode(part)), 32);
+        node = new Uint8Array(sha256(joined));
+    }
+    return node;
+}
+const POLICIES = { enabled: "Enabled", "creation-disabled": "CreationDisabled", suspended: "Suspended" };
+export function subnamePolicyToNative(value) {
+    if (!Object.hasOwn(POLICIES, value))
+        throw new Error("invalid subname policy");
+    return [POLICIES[value]];
+}
+export function subnamePolicyFromNative(raw) {
+    if (!Array.isArray(raw) || raw.length !== 1 || typeof raw[0] !== "string")
+        throw new Error("invalid subname policy response");
+    const policy = Object.keys(POLICIES).find(key => POLICIES[key] === raw[0]);
+    if (!policy)
+        throw new Error("unsupported subname policy");
+    return policy;
+}
+export function exactGeneration(value) {
+    if (typeof value !== "bigint" || value < 0n || value > 18446744073709551615n)
+        throw new Error("generation must be an exact u64 bigint");
+    return value;
+}
+/** Address validity is checked by each caller's Stellar SDK, without coercion. */
+export function subnameRecordFromNative(raw, expectedParentNode) {
+    if (raw === null)
+        return null;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).sort().join(",") !== "active,address,generation,parent_generation,parent_node")
+        throw new Error("invalid subname record fields");
+    const r = raw;
+    if (!(r.parent_node instanceof Uint8Array) || r.parent_node.length !== 32 || expectedParentNode.length !== 32 || !r.parent_node.every((byte, i) => byte === expectedParentNode[i]) || typeof r.address !== "string" || typeof r.active !== "boolean")
+        throw new Error("invalid subname record response");
+    return { parentNode: new Uint8Array(r.parent_node), parentGeneration: exactGeneration(r.parent_generation), generation: exactGeneration(r.generation), address: r.address, active: r.active };
+}
+export function subnameLabelsFromNative(raw, limit) {
+    if (!Array.isArray(raw) || raw.length > limit)
+        throw new Error("invalid subname labels response");
+    const values = raw.map(label => {
+        if (!(label instanceof Uint8Array) || label.length < 1 || label.length > 63 || label.some(byte => byte > 127))
+            throw new Error("invalid subname label bytes");
+        const text = new TextDecoder().decode(label);
+        if (!LABEL.test(text))
+            throw new Error("invalid subname label");
+        return text;
+    });
+    if (new Set(values).size !== values.length)
+        throw new Error("duplicate subname label");
+    return values;
+}
+export function subnamePageInput(offset = 0, limit = 16) {
+    if (!Number.isInteger(offset) || offset < 0 || offset > 4294967295 || !Number.isInteger(limit) || limit < 1 || limit > 16 || offset + limit > 4294967295)
+        throw new Error("subname page requires an unsigned offset and a limit from 1 to 16");
+    return { offset, limit };
+}

package/dist/native-codec.js

@@ -1,7 +1,7 @@
 /** Local successor-ABI helpers. No deployed defaults are changed by this module. */
 import { Address, StrKey, hash, nativeToScVal, xdr } from "@stellar/stellar-sdk";
 import { decodeMuxedAddress, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
-export const NATIVE_REGISTRAR_ERRORS = { 21: "InvalidClaimConfig", 22: "ClaimsNotConfigured", 23: "ClaimsPaused", 24: "StaleClaimPolicy", 25: "ClaimIntentMismatch", 26: "ClaimIntentExpired", 27: "ReservedName", 28: "NameNotReserved", 29: "PublicIssuanceRequired", 30: "WalletClaimLimit", 31: "InvalidEligibility", 32: "ApprovalAllowanceReached", 33: "ApprovalRateReached", 34: "RequestIdConflict", 35: "CounterOverflow", 36: "InvalidNativeBinding", 37: "UnsupportedClaimant", 38: "DuplicateLabel", 39: "RenewalTooEarly", 40: "RenewalLeaseLimit", 41: "DestinationInitializationFailed", 42: "FeeSettlementFailed" };
+export const NATIVE_REGISTRAR_ERRORS = { 1: "AlreadyInitialized", 2: "NotInitialized", 3: "NameTaken", 4: "NameNotFound", 5: "NotReclaimable", 6: "NotTransferable", 7: "AlreadyPermanent", 8: "BatchTooLarge", 9: "NotNamespaceOwner", 10: "BadLabel", 11: "PermanentName", 12: "FiniteTermPolicy", 13: "PermanentlyLocked", 14: "NameExpired", 15: "NoPendingTransfer", 16: "TransferExpired", 17: "StaleTransfer", 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", 52: "InvalidRenewalGrace", 53: "SubnameCreationDisabled", 54: "SubnamesSuspended", 55: "SubnameGenerationMismatch", 56: "SubnameIndexUnavailable" };
 export class NativeClaimError extends Error {
     kind;
     txHash;

package/dist/native-transport.d.ts

@@ -1,5 +1,7 @@
 import { Transaction, rpc, xdr } from "@stellar/stellar-sdk";
 import { type NativeAuthorizationPlan } from "./native-auth.js";
+/** RPC clients sometimes reject with a plain `{ code, message }` object, which String() renders as "[object Object]". */
+export declare function describeRejection(error: unknown): string;
 export type NativeSigner = {
     publicKey(): string | Promise<string>;
     signTransaction(encoded: string, opts: {

package/dist/native-transport.js

@@ -2,6 +2,23 @@ import { expectedRegistrarCode } from "./native-code-policy.js";
 import { Contract, Operation, Transaction, TransactionBuilder, rpc, scValToNative, xdr } from "@stellar/stellar-sdk";
 import { NativeClaimError, address, hex, namespaceNode, sc, unhex } from "./native-codec.js";
 import { assertSignedBodyUnchanged, validateEligibilityAuthorization, validateNativeTransaction } from "./native-auth.js";
+/** RPC clients sometimes reject with a plain `{ code, message }` object, which String() renders as "[object Object]". */
+export function describeRejection(error) {
+    if (error instanceof Error || typeof error === "string")
+        return String(error);
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string" && message)
+            return message;
+        try {
+            const json = JSON.stringify(error);
+            if (json && json !== "{}")
+                return json.length > 300 ? `${json.slice(0, 300)}...` : json;
+        }
+        catch { /* circular or unserialisable */ }
+    }
+    return "unknown error";
+}
 /** This published legacy code has owner-only issuance. Missing RPC data is never legacy detection. */
 const LEGACY_REGISTRAR_HASH = "ed06b3374ff4342b4a2316fc546505132cd8fd35be6666571cf088710af9bbc6";
 /** Historical reads must not trust an upgraded Registrar that can fabricate receipts. Resolver changes do not block this Registrar-only check. */
@@ -119,7 +136,7 @@ export async function sendNative(context, plan, options = {}) {
     catch (error) {
         if (error instanceof NativeClaimError && error.txHash)
             throw error;
-        throw new NativeClaimError(`submission/confirmation interrupted: ${String(error)}; reconcile the original receipt`, "pending", prepared.hash);
+        throw new NativeClaimError(`submission/confirmation interrupted: ${describeRejection(error)}; reconcile the original receipt`, "pending", prepared.hash);
     }
 }
 /** Bind terminal RPC context before classifying success or failure. An incomplete response remains uncertain. */

package/dist/native-upgrades.d.ts

@@ -1,6 +1,10 @@
 import { xdr } from "@stellar/stellar-sdk";
-import type { NativeContext } from "./native-transport.js";
+import type { NativeContext, NativeWriteOptions } from "./native-transport.js";
 export type ContractUpgradeRole = "registrar" | "resolver";
+export type ContractUpgradeOptions = NativeWriteOptions & {
+    /** Explicit acknowledgement that installing a superseded (older) release, or the latest known release over code this SDK cannot place, is intended. A reinstall of the installed hash is never allowed. */
+    allowDowngrade?: boolean;
+};
 export type ContractUpgradeStatus = {
     owner: string;
     contractId: string;
@@ -8,6 +12,37 @@ export type ContractUpgradeStatus = {
     approved: boolean;
     governed: boolean;
 };
+/**
+ * Reviewed implementation lineage of the governed testnet Registry. Governance
+ * approval means "this hash may be installed on any namespace", not "this is a
+ * safe transition": superseded releases stay approved, so the chain accepts a
+ * downgrade. `latest` is the release owners are offered; `superseded` are the
+ * older releases it replaces. A test keeps this equal to the web catalog
+ * (web/lib/contractUpdates.ts) and the release record; adding a release means
+ * moving the old `latest` into `superseded` here and there.
+ */
+export declare const CONTRACT_RELEASES: {
+    readonly registrar: {
+        readonly latest: "4d6d18625f4d890028acb794b24871c5c93f96dc15d94cf3d52cbf9713b07fb1";
+        readonly superseded: readonly ["42dc5f8b40932617d3f2667e1d26dad3e5e9a62c63de1fde7c016cb67a86c420", "5c8ae72ea7370ccf19af52b9bbc0007362be94464651ccdf68a2bb1f478b6f2c", "61ded153e6311075c1087c5639a5410222e23f7cade239ed2c946150af94b1c5", "26e03cd1d7fbfa46fe442406fb1b88022ec8cd8bd9123bed570f971fce596a14"];
+    };
+    readonly resolver: {
+        readonly latest: "941bf87f26cb817f3c6a52a326de855cca8a1dc4477e62a38ec4ffa5c7f43806";
+        readonly superseded: readonly ["cb927ffa19d6b1f3f0b0187048d885e200adb6de3fddd11ee3cfeb59df9c5c48", "351bf4e056b179b578fe2a4ea46f937bfafccc6538c7357ea70021b7038d91ea", "c6dfcd7bbf35943a13406888678334d0938d0fea54939906b00c2dc37b4a9a71", "5e7b4fb8d310d67ed6966a155e748d60be771422b3e8c34bbc14485f98525574"];
+    };
+};
+/**
+ * How installing `targetHash` over `currentHash` relates to the reviewed lineage:
+ * - "same": already installed (never installable again);
+ * - "backward": the target is a superseded release, so this is a downgrade;
+ * - "forward": the latest known release over a known superseded one;
+ * - "unrecognized-current": the latest known release over code this SDK cannot
+ *   place, which may be a newer release, so installing it could be a downgrade;
+ * - "unreviewed-target": a release this SDK has no lineage for (newer than the SDK
+ *   or custom); direction cannot be judged and the caller's review is trusted.
+ */
+export type ContractUpgradeDirection = "forward" | "same" | "backward" | "unrecognized-current" | "unreviewed-target";
+export declare function contractUpgradeDirection(role: ContractUpgradeRole, currentHash: string, targetHash: string): ContractUpgradeDirection;
 export declare function upgradeHash(hash: string): xdr.ScVal;
 /** Independent of claim versions, claim configuration and fee-token policy. */
 export declare function contractUpgradeStatus(context: NativeContext, namespace: string, role: ContractUpgradeRole, wasmHash: string): Promise<ContractUpgradeStatus>;

package/dist/native-upgrades.js

@@ -1,5 +1,44 @@
 import { NativeClaimError, address, bool, bytes32, exactObject, hex, namespaceNode, sc, u32 } from "./native-codec.js";
 import { expectedNativeCode } from "./native-code-policy.js";
+/**
+ * Reviewed implementation lineage of the governed testnet Registry. Governance
+ * approval means "this hash may be installed on any namespace", not "this is a
+ * safe transition": superseded releases stay approved, so the chain accepts a
+ * downgrade. `latest` is the release owners are offered; `superseded` are the
+ * older releases it replaces. A test keeps this equal to the web catalog
+ * (web/lib/contractUpdates.ts) and the release record; adding a release means
+ * moving the old `latest` into `superseded` here and there.
+ */
+export const CONTRACT_RELEASES = {
+    registrar: {
+        latest: "4d6d18625f4d890028acb794b24871c5c93f96dc15d94cf3d52cbf9713b07fb1",
+        superseded: [
+            "42dc5f8b40932617d3f2667e1d26dad3e5e9a62c63de1fde7c016cb67a86c420",
+            "5c8ae72ea7370ccf19af52b9bbc0007362be94464651ccdf68a2bb1f478b6f2c",
+            "61ded153e6311075c1087c5639a5410222e23f7cade239ed2c946150af94b1c5",
+            "26e03cd1d7fbfa46fe442406fb1b88022ec8cd8bd9123bed570f971fce596a14",
+        ],
+    },
+    resolver: {
+        latest: "941bf87f26cb817f3c6a52a326de855cca8a1dc4477e62a38ec4ffa5c7f43806",
+        superseded: [
+            "cb927ffa19d6b1f3f0b0187048d885e200adb6de3fddd11ee3cfeb59df9c5c48",
+            "351bf4e056b179b578fe2a4ea46f937bfafccc6538c7357ea70021b7038d91ea",
+            "c6dfcd7bbf35943a13406888678334d0938d0fea54939906b00c2dc37b4a9a71",
+            "5e7b4fb8d310d67ed6966a155e748d60be771422b3e8c34bbc14485f98525574",
+        ],
+    },
+};
+export function contractUpgradeDirection(role, currentHash, targetHash) {
+    const { latest, superseded } = CONTRACT_RELEASES[role];
+    if (currentHash === targetHash)
+        return "same";
+    if (superseded.includes(targetHash))
+        return "backward";
+    if (targetHash !== latest)
+        return "unreviewed-target";
+    return superseded.includes(currentHash) ? "forward" : "unrecognized-current";
+}
 export function upgradeHash(hash) {
     if (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))
         throw new NativeClaimError("Contract implementation hash must be lowercase hex32");

package/dist/subnames-client.d.ts

@@ -0,0 +1,49 @@
+import { type xdr } from "@stellar/stellar-sdk";
+import { type SubnameRecord } from "./names.js";
+export declare const SUBNAME_REGISTRAR_ERRORS: Record<number, string>;
+export declare const subnameLabelArg: (value: string) => xdr.ScVal;
+export declare function subnameParent(input: string): import("./names.js").ParsedResolvableName;
+export declare function subnameParts(input: string): import("./names.js").ParsedResolvableName;
+export declare function createSubnameReader(config: {
+    registryId: string;
+    error?: (message: string) => Error;
+    read: (id: string, fn: string, args: xdr.ScVal[]) => Promise<unknown>;
+}): {
+    context: (input: string) => Promise<{
+        namespace: string;
+        registrar: string;
+        owner: string;
+        policy: import("./names.js").SubnamePolicy;
+    }>;
+    creationContext: (input: string) => Promise<{
+        namespace: string;
+        registrar: string;
+        owner: string;
+        policy: import("./names.js").SubnamePolicy;
+    }>;
+    recordAt: (ctx: Awaited<ReturnType<(input: string) => Promise<{
+        namespace: string;
+        registrar: string;
+        owner: string;
+        policy: import("./names.js").SubnamePolicy;
+    }>>>, parent: string, label: string) => Promise<SubnameRecord | null>;
+    record: (name: string) => Promise<SubnameRecord | null>;
+    policy: (namespace: string) => Promise<import("./names.js").SubnamePolicy>;
+    list: (parent: string, options?: {
+        offset?: number;
+        limit?: number;
+    }) => Promise<{
+        parent: string;
+        policy: import("./names.js").SubnamePolicy;
+        records: {
+            parentNode: Uint8Array;
+            parentGeneration: bigint;
+            generation: bigint;
+            address: string;
+            active: boolean;
+            name: string;
+        }[];
+        offset: number;
+        nextOffset: number | null;
+    }>;
+};

package/dist/subnames-client.js

@@ -0,0 +1,63 @@
+// Generated by sdk/names/sync.mjs; edit sdk/names/subnames-client.ts.
+import { hash, nativeToScVal, StrKey } from "@stellar/stellar-sdk";
+import { parseNamespace, parseResolvableName, resolvableNameNode, subnamePolicyFromNative, subnameRecordFromNative, subnameLabelsFromNative, subnamePageInput } from "./names.js";
+export const SUBNAME_REGISTRAR_ERRORS = { 53: "SubnameCreationDisabled", 54: "SubnamesSuspended", 55: "SubnameGenerationMismatch", 56: "SubnameIndexUnavailable" };
+const account = (value) => typeof value === "string" && (StrKey.isValidEd25519PublicKey(value) || StrKey.isValidContract(value));
+const contract = (value) => typeof value === "string" && StrKey.isValidContract(value);
+export const subnameLabelArg = (value) => nativeToScVal(new TextEncoder().encode(value), { type: "bytes" });
+export function subnameParent(input) { const parsed = parseResolvableName(input); if (parsed.childLabel)
+    throw new Error("parent must be label.namespace"); return parsed; }
+export function subnameParts(input) { const parsed = parseResolvableName(input); if (!parsed.childLabel)
+    throw new Error("subname must be child.label.namespace"); return parsed; }
+export function createSubnameReader(config) {
+    const read = config.read;
+    const failure = (message) => config.error?.(message) ?? new Error(message);
+    async function context(input) {
+        const namespace = parseNamespace(input);
+        if (!contract(config.registryId))
+            throw failure("invalid Registry");
+        const joined = new Uint8Array(64);
+        joined.set(hash(new TextEncoder().encode(namespace)), 32);
+        const node = hash(joined);
+        const arg = nativeToScVal(node, { type: "bytes" });
+        const [registrar, owner] = await Promise.all([read(config.registryId, "registrar_of", [arg]), read(config.registryId, "owner_of", [arg])]);
+        if (!contract(registrar) || !account(owner))
+            throw failure("namespace has no current Registrar or owner");
+        const anchors = await read(registrar, "anchors", []);
+        if (!Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== config.registryId || !(anchors[1] instanceof Uint8Array) || anchors[1].length !== 32 || !node.every((b, i) => b === anchors[1][i]))
+            throw failure("subname Registrar context mismatch");
+        if (await read(registrar, "subname_version", []) !== 1)
+            throw failure("subnames unsupported");
+        const policy = subnamePolicyFromNative(await read(registrar, "subname_policy", []));
+        return { namespace, registrar, owner, policy };
+    }
+    async function creationContext(input) {
+        const ctx = await context(input), joined = new Uint8Array(64);
+        joined.set(hash(new TextEncoder().encode(ctx.namespace)), 32);
+        const resolver = await read(config.registryId, "resolver_of", [nativeToScVal(hash(joined), { type: "bytes" })]);
+        if (!contract(resolver))
+            throw failure("subnames unsupported: no Resolver");
+        const [anchor, authority, version] = await Promise.all([read(resolver, "registry", []), read(resolver, "authority", []), read(resolver, "subname_version", [])]);
+        if (anchor !== config.registryId || authority !== ctx.registrar)
+            throw failure("subname Resolver context mismatch");
+        if (version !== 1)
+            throw failure("subnames unsupported by Resolver");
+        return ctx;
+    }
+    async function recordAt(ctx, parent, label) {
+        const record = subnameRecordFromNative(await read(ctx.registrar, "subname_record", [subnameLabelArg(parent), subnameLabelArg(label)]), resolvableNameNode(`${parent}.${ctx.namespace}`));
+        if (record && !account(record.address))
+            throw failure("invalid subname destination");
+        return record;
+    }
+    async function record(name) { const parsed = subnameParts(name), ctx = await context(parsed.namespace); return recordAt(ctx, parsed.parentLabel, parsed.childLabel); }
+    async function policy(namespace) { return (await context(namespace)).policy; }
+    async function list(parent, options = {}) {
+        const parsed = subnameParent(parent), { offset, limit } = subnamePageInput(options.offset, options.limit), ctx = await context(parsed.namespace);
+        const labels = subnameLabelsFromNative(await read(ctx.registrar, "subname_labels", [subnameLabelArg(parsed.label), nativeToScVal(offset, { type: "u32" }), nativeToScVal(limit, { type: "u32" })]), limit);
+        const records = await Promise.all(labels.map(async (label) => { const record = await recordAt(ctx, parsed.label, label); if (!record)
+            throw failure("subname index references missing record"); return { name: `${label}.${parsed.name}`, ...record }; }));
+        return { parent: parsed.name, policy: ctx.policy, records, offset, nextOffset: labels.length === limit ? offset + labels.length : null };
+    }
+    return { context, creationContext, recordAt, record, policy, list };
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@sorandomains/owner",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Run your Soran namespace on Stellar: configure claims, issue names and manage namespace policies.",
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,7 +16,8 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "tsc",
     "check:browser": "esbuild dist/index.js --bundle --platform=browser --external:@stellar/stellar-sdk --outfile=browser-check.js --legal-comments=none --log-level=error && node -e \"const fs=require('fs');const s=fs.readFileSync('browser-check.js','utf8');fs.unlinkSync('browser-check.js');if(/\\bBuffer\\b/.test(s)){console.error('FAIL: bare Buffer reference in browser bundle');process.exit(1)}console.log('browser bundle clean')\"",
-    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/integration.test.mts test/native-*.test.mts && node --import tsx --test test/funding.test.mts test/funding-history.test.mts"
+    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/integration.test.mts test/hardening.test.mts test/error-codes.test.mts test/native-*.test.mts && node --import tsx --test test/funding.test.mts test/funding-history.test.mts test/funding-bounds.test.mts && node --import tsx --test test/multichain.test.mts && node --import tsx --test test/subnames.test.mts",
+    "test:hardening": "node --import tsx --test test/hardening.test.mts"
   },
   "license": "MIT",
   "repository": {
@@ -51,5 +52,12 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
+  },
+  "dependencies": {
+    "@noble/hashes": "2.4.0",
+    "@scure/base": "2.4.0"
+  },
+  "overrides": {
+    "axios": "1.20.0"
   }
 }