@sorandomains/owner 0.10.1 → 0.12.0

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-code-policy.d.ts

@@ -10,5 +10,12 @@ type Context = {
 };
 /** Select policy from an exact Registry instance proof. Failed RPC/method reads
  * never downgrade governed verification to the historical template rule. */
+export type ExpectedNativeCode = {
+    governed: boolean;
+    registrar: string;
+    resolver: string;
+};
+export declare function expectedNativeCode(context: Context, namespace: string, minimumLedger?: number): Promise<ExpectedNativeCode>;
+/** Registrar-only consumers retain the same governed/legacy policy selection. */
 export declare function expectedRegistrarCode(context: Context, namespace: string, minimumLedger?: number): Promise<string>;
 export {};

package/dist/native-code-policy.js

@@ -6,9 +6,7 @@ function ledger(value, minimum) {
         fail('missing or stale ledger context');
     return value;
 }
-/** Select policy from an exact Registry instance proof. Failed RPC/method reads
- * never downgrade governed verification to the historical template rule. */
-export async function expectedRegistrarCode(context, namespace, minimumLedger) {
+export async function expectedNativeCode(context, namespace, minimumLedger) {
     const key = new Contract(context.registryId).getFootprint();
     const proof = await context.server.getLedgerEntries(key);
     const observed = ledger(proof?.latestLedger, minimumLedger ?? 1);
@@ -38,7 +36,7 @@ export async function expectedRegistrarCode(context, namespace, minimumLedger) {
         const templates = await read('template_hashes');
         if (!Array.isArray(templates) || templates.length !== 2)
             fail('malformed historical templates');
-        return hex(bytes32(templates[0], 'Registry Registrar template'));
+        return { governed: false, registrar: hex(bytes32(templates[0], 'Registry Registrar template')), resolver: hex(bytes32(templates[1], 'Registry Resolver template')) };
     }
     if (authorities[0].val.type !== 'scvAddress')
         fail('malformed upgrade authority');
@@ -48,6 +46,9 @@ export async function expectedRegistrarCode(context, namespace, minimumLedger) {
     const code = exactObject(await read('native_code', [sc.bytes(unhex(namespace))]), ['registrar', 'resolver', 'registrar_updates', 'resolver_updates'], 'native code');
     u32(code.registrar_updates, 'Registrar upgrade count');
     u32(code.resolver_updates, 'Resolver upgrade count');
-    bytes32(code.resolver, 'Registry Resolver code');
-    return hex(bytes32(code.registrar, 'Registry Registrar code'));
+    return { governed: true, registrar: hex(bytes32(code.registrar, 'Registry Registrar code')), resolver: hex(bytes32(code.resolver, 'Registry Resolver code')) };
+}
+/** Registrar-only consumers retain the same governed/legacy policy selection. */
+export async function expectedRegistrarCode(context, namespace, minimumLedger) {
+    return (await expectedNativeCode(context, namespace, minimumLedger)).registrar;
 }

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

@@ -0,0 +1,48 @@
+import { xdr } from "@stellar/stellar-sdk";
+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;
+    currentHash: string;
+    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>;