@sorandomains/owner 0.10.0 → 0.11.0

package/README.md

@@ -121,3 +121,24 @@ The older `maxNativeFeeStroops` option remains supported: when the new option is
 On a governed Registry, native verification reads the exact per-namespace Registrar code pin and its upgrade history. Approved upgrades do not have to match the current factory default. Missing or malformed provenance still prevents signing and receipt confirmation; RPC failure never downgrades verification to a legacy rule.
 
 Historical claim recovery is read-only and binds the original intent to the frozen source Registrar and sealed migration commitments. It never rewrites the intent to a successor Registry or treats an unavailable receipt as permission to submit again. Deployment migration and package publication are separate; check the release status for the active addresses.
+
+## Namespace contract updates
+
+The current namespace owner can update each governed child contract separately:
+
+```ts
+const status = await client.contractUpgradeStatus("acme", "resolver", approvedResolverHash);
+// status: { owner, contractId, currentHash, approved, governed }
+if (status.approved && status.governed && status.currentHash !== approvedResolverHash) {
+  await client.upgradeResolver("acme", approvedResolverHash, {
+    onPrepared: ({ hash, feeStroops }) => savePendingUpdate({ hash, feeStroops }),
+  });
+}
+await client.upgradeRegistrar("acme", approvedRegistrarHash);
+```
+
+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.

package/dist/funding-service.js

@@ -38,7 +38,16 @@ export class FundingServiceClient {
         catch {
             throw new FundingError("Service response unavailable. Keep your quote reference and recover its status before submitting again.", "unavailable");
         }
-        const value = (await r.json());
+        let value;
+        try {
+            value = (await r.json());
+        }
+        catch {
+            // A proxy/gateway error page (e.g. a 502 HTML body) is not JSON. A
+            // submit's outcome is then unknown, so it reads as pending; anything
+            // else simply could not be answered.
+            throw new FundingError("Service response was not valid JSON. Keep your quote reference and recover its status before submitting again.", path === "/v1/sponsorship/submit" ? "pending" : "unavailable");
+        }
         if (!value || typeof value !== "object" || Array.isArray(value))
             throw new FundingError("Invalid service response", "unavailable");
         if (!r.ok || value.error)

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { type HistoricalRecoveryOptions } from "./native-history.js";
 import type { ClaimIntent } from "./native-types.js";
 export type { HistoricalRecoveryOptions } from "./native-history.js";
 import { type NativeWriteOptions, type NativeCapability } from "./native-transport.js";
+import { type ContractUpgradeRole, type ContractUpgradeStatus } from "./native-upgrades.js";
+export type { ContractUpgradeRole, ContractUpgradeStatus } from "./native-upgrades.js";
 import { type ClaimSettings, type ClaimConfig, type ClaimUsage, type ApprovalUsage } from "./native-types.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
@@ -160,8 +162,13 @@ export declare class SoranOwner {
     private nativeOwnerWrite;
     /** Current implementation after validating the Registry's native binding. */
     registrarCodeHash(namespace: string): Promise<string>;
-    /** Owner-authorized, Registry-approved update; never uses the legacy tainting path. */
+    /** Verify both children and the selected implementation without signing or reading claim settings. */
+    contractUpgradeStatus(namespace: string, role: ContractUpgradeRole, wasmHash: string): Promise<ContractUpgradeStatus>;
+    private upgradeContract;
+    /** Current-owner, Registry-approved update; never uses the legacy tainting path. */
     upgradeRegistrar(namespace: string, wasmHash: string, options?: NativeWriteOptions): Promise<Submitted>;
+    /** Current-owner, Registry-approved Resolver update with exact native authorization. */
+    upgradeResolver(namespace: string, wasmHash: string, options?: NativeWriteOptions): Promise<Submitted>;
     configureClaims(namespace: string, settings: ClaimSettings, options?: NativeWriteOptions): Promise<Submitted & {
         config: ClaimConfig;
     }>;

package/dist/index.js

@@ -87,6 +87,7 @@ 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 { claimSettingsToScVal, claimConfigFromNative, claimLabelToScVal, claimUsageFromNative, approvalUsageFromNative } from "./native-types.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
@@ -228,6 +229,25 @@ const REGISTRY_ERRORS = {
     40: "UpgradeNotApproved",
     41: "PermanentLockDisabled",
 };
+/** 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();
+function isBadSeqResult(result) {
+    try {
+        const field = result?.result;
+        const inner = (typeof field === "function" ? field.call(result) : field);
+        if (inner && typeof inner === "object" && "type" in inner)
+            return inner.type === "txBadSeq";
+        throw new Error("unrecognised result");
+    }
+    catch {
+        try {
+            return /txBadSeq|bad_seq/i.test(String(result?.toXDR?.() ?? ""));
+        }
+        catch {
+            return false;
+        }
+    }
+}
 /**
  * A failed owner operation. When the contract itself rejected the call,
  * `code`/`codeName` carry its typed error (e.g. code 9 / "NotNamespaceOwner"
@@ -409,23 +429,37 @@ export class SoranOwner {
             throw new NativeClaimError("Registrar is not a Wasm contract", "unavailable");
         return nativeHex(instance.executable.wasmHash.value);
     }
-    /** Owner-authorized, Registry-approved update; never uses the legacy tainting path. */
-    async upgradeRegistrar(namespace, wasmHash, options = {}) {
-        if (!/^[a-f0-9]{64}$/.test(wasmHash))
-            throw new NativeClaimError("Registrar implementation hash must be lowercase hex32");
-        const bytes = Uint8Array.from(wasmHash.match(/../g), value => parseInt(value, 16));
-        const cap = await requireNative(this.nativeContext(), normalizeLabel(namespace));
-        const [governed, approved, current] = await Promise.all([
-            this.read(cap.registrar, "upgrade_policy_version", []),
-            this.read(this.registryId, "implementation_approved", [nativeSc.u32(0), nativeSc.bytes(bytes)]),
-            this.registrarCodeHash(namespace),
-        ]);
-        if (governed !== 1 || approved !== true)
-            throw new NativeClaimError("This Registrar upgrade is not approved by the Registry", "authorization");
-        if (current === wasmHash)
-            throw new NativeClaimError("This Registrar implementation is already installed");
-        const result = await this.nativeOwnerWrite(namespace, "upgrade", [nativeSc.bytes(bytes)], options);
-        return { hash: result.hash, ledger: result.ledger };
+    /** Verify both children and the selected implementation without signing or reading claim settings. */
+    contractUpgradeStatus(namespace, role, wasmHash) {
+        return readContractUpgradeStatus(this.nativeContext(), normalizeLabel(namespace), role, wasmHash);
+    }
+    upgradeContract(namespace, role, wasmHash, options) {
+        return this.serialize(async () => {
+            const args = [upgradeHash(wasmHash)];
+            const context = this.nativeContext();
+            const status = await readContractUpgradeStatus(context, normalizeLabel(namespace), role, wasmHash);
+            const source = nativeAddress(await this.signer.publicKey(), "account", "owner transaction source");
+            if (source !== status.owner)
+                throw new NativeClaimError("the current namespace owner must authorize this change", "authorization");
+            if (!status.governed || !status.approved)
+                throw new NativeClaimError("This contract upgrade is not approved by the Registry", "authorization");
+            if (status.currentHash === wasmHash)
+                throw new NativeClaimError("This contract implementation is already installed");
+            const result = await sendNative(context, {
+                source, contract: status.contractId, method: "upgrade", args,
+                sourceInvocation: { contract: status.contractId, method: "upgrade", args },
+                maxFeeStroops: context.maxFeeStroops,
+            }, options);
+            return { hash: result.hash, ledger: result.ledger };
+        });
+    }
+    /** Current-owner, Registry-approved update; never uses the legacy tainting path. */
+    upgradeRegistrar(namespace, wasmHash, options = {}) {
+        return this.upgradeContract(namespace, "registrar", wasmHash, options);
+    }
+    /** Current-owner, Registry-approved Resolver update with exact native authorization. */
+    upgradeResolver(namespace, wasmHash, options = {}) {
+        return this.upgradeContract(namespace, "resolver", wasmHash, options);
     }
     async configureClaims(namespace, settings, options = {}) {
         const encoded = claimSettingsToScVal(settings);
@@ -788,7 +822,7 @@ export class SoranOwner {
             catch (e) {
                 // A stale sequence (another process moved the account) is safe to
                 // retry once with a fresh sequence — nothing was included.
-                if (!(e instanceof OwnerError && e.txHash) && /txBadSeq|bad_seq/i.test(String(e))) {
+                if ((BAD_SEQ_REJECTED.has(e) || (!(e instanceof OwnerError && e.txHash) && /txBadSeq|bad_seq/i.test(String(e))))) {
                     return await this.attempt(contractId, fn, args, errNames);
                 }
                 throw e;
@@ -864,7 +898,10 @@ export class SoranOwner {
             throw new OwnerError(`${fn}: submit failed after signing (${String(e)}) — transaction ${txHash} may or may not have reached the network; check the hash before retrying`, contractId, fn, null, null, txHash);
         }
         if (sent.status === "ERROR") {
-            throw new OwnerError(`${fn}: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, contractId, fn, null, null, txHash);
+            const rejected = new OwnerError(`${fn}: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, contractId, fn, null, null, txHash);
+            if (isBadSeqResult(sent.errorResult))
+                BAD_SEQ_REJECTED.add(rejected);
+            throw rejected;
         }
         if (sent.status === "TRY_AGAIN_LATER") {
             throw new OwnerError(`${fn}: the network did not accept the transaction (TRY_AGAIN_LATER) — it was NOT queued; safe to retry shortly`, contractId, fn, null, null, txHash);

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-upgrades.d.ts

@@ -0,0 +1,13 @@
+import { xdr } from "@stellar/stellar-sdk";
+import type { NativeContext } from "./native-transport.js";
+export type ContractUpgradeRole = "registrar" | "resolver";
+export type ContractUpgradeStatus = {
+    owner: string;
+    contractId: string;
+    currentHash: string;
+    approved: boolean;
+    governed: boolean;
+};
+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

@@ -0,0 +1,54 @@
+import { NativeClaimError, address, bool, bytes32, exactObject, hex, namespaceNode, sc, u32 } from "./native-codec.js";
+import { expectedNativeCode } from "./native-code-policy.js";
+export function upgradeHash(hash) {
+    if (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))
+        throw new NativeClaimError("Contract implementation hash must be lowercase hex32");
+    return sc.bytes(Uint8Array.from(hash.match(/../g), value => parseInt(value, 16)));
+}
+/** Independent of claim versions, claim configuration and fee-token policy. */
+export async function contractUpgradeStatus(context, namespace, role, wasmHash) {
+    if (role !== "registrar" && role !== "resolver")
+        throw new NativeClaimError("Unknown namespace contract role");
+    const target = upgradeHash(wasmHash);
+    const node = namespaceNode(namespace), args = [sc.bytes(node)];
+    const [pair, owner, code, registrar, resolver, selected, registrarTainted, resolverTainted] = await Promise.all([
+        context.read(context.registryId, "native_contracts", args),
+        context.read(context.registryId, "owner_of", args),
+        expectedNativeCode(context, hex(node)),
+        context.read(context.registryId, "registrar_of", args),
+        context.read(context.registryId, "attested_resolver_of", args),
+        context.read(context.registryId, "resolver_of", args),
+        context.read(context.registryId, "registrar_tainted", args),
+        context.read(context.registryId, "resolver_tainted", args),
+    ]);
+    const fail = (message) => { throw new NativeClaimError(message, "unavailable"); };
+    if (!Array.isArray(pair) || pair.length !== 2 || pair[0] !== registrar || pair[1] !== resolver || selected !== resolver || registrarTainted !== false || resolverTainted !== false)
+        fail("Namespace contracts are missing, tainted or differ from the Registry's native binding");
+    const registrarId = address(registrar, "contract", "namespace Registrar");
+    const resolverId = address(resolver, "contract", "namespace Resolver");
+    const contractId = role === "registrar" ? registrarId : resolverId;
+    const [registrarInstance, resolverInstance, anchors, provenanceRaw, authority, registry, version] = await Promise.all([
+        context.server.getContractInstance(registrarId),
+        context.server.getContractInstance(resolverId),
+        context.read(registrarId, "anchors", []),
+        context.read(resolverId, "provenance", []),
+        context.read(resolverId, "authority", []),
+        context.read(resolverId, "registry", []),
+        // A verified legacy Registry is safely reported as disallowed without probing a new child ABI.
+        code.governed ? context.read(contractId, "upgrade_policy_version", []) : 0,
+    ]);
+    for (const [instance, expected] of [[registrarInstance, code.registrar], [resolverInstance, code.resolver]]) {
+        if (instance.executable.type !== "contractExecutableWasm" || hex(instance.executable.wasmHash.value) !== expected)
+            fail("Namespace contract executable differs from Registry-approved code");
+    }
+    if (!Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== context.registryId || hex(bytes32(anchors[1], "Registrar namespace")) !== hex(node))
+        fail("Registrar anchors differ from selected namespace");
+    const provenance = exactObject(provenanceRaw, ["registry", "node"], "Resolver provenance");
+    if (provenance.registry !== context.registryId || hex(bytes32(provenance.node, "Resolver namespace")) !== hex(node) || authority !== registrarId || registry !== context.registryId)
+        fail("Resolver provenance or authority differs from selected namespace");
+    const governed = code.governed && u32(version, "contract upgrade policy") === 1;
+    const approved = code.governed
+        ? bool(await context.read(context.registryId, "implementation_approved", [sc.u32(role === "registrar" ? 0 : 1), target]), "implementation approval")
+        : false;
+    return { owner: address(owner, "identity", "namespace owner"), contractId, currentHash: code[role], approved, governed };
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@sorandomains/owner",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Run your Soran namespace on Stellar: configure claims, issue names and manage namespace policies.",
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [