@sorandomains/owner 0.6.0 → 0.8.0-migration.0

package/dist/native-auth.js

@@ -0,0 +1,85 @@
+import { Address, Transaction, TransactionBuilder, authorizeEntry, xdr } from "@stellar/stellar-sdk";
+import { NativeClaimError, address, hex, u32 } from "./native-codec.js";
+export function authorizedInvocation(value) {
+    return new xdr.SorobanAuthorizedInvocation({
+        function: xdr.SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(new xdr.InvokeContractArgs({
+            contractAddress: new Address(address(value.contract, "contract", "invocation contract")).toScAddress(), functionName: value.method, args: value.args,
+        })), subInvocations: (value.children ?? []).map(authorizedInvocation),
+    });
+}
+function sameInvocation(actual, expected) {
+    return actual.toXDR("base64") === authorizedInvocation(expected).toXDR("base64");
+}
+export function validateEligibilityAuthorization(entry, expected, requireSigned = true) {
+    if (expected.invocation.method !== "claim" || expected.invocation.args.length !== 1 || (expected.invocation.children?.length ?? 0) !== 0)
+        throw new NativeClaimError("eligibility may authorize only one exact native claim intent", "authorization");
+    address(expected.account, "account", "eligibility account");
+    u32(expected.latestLedger, "latest ledger");
+    u32(expected.maxExpirationLedger, "maximum auth expiration ledger");
+    if (entry.credentials.type !== "sorobanCredentialsAddress")
+        throw new NativeClaimError("eligibility requires the supported native G address credential", "authorization");
+    const credential = entry.credentials.address;
+    if (Address.fromScAddress(credential.address).toString() !== expected.account || !sameInvocation(entry.rootInvocation, expected.invocation) || entry.rootInvocation.subInvocations.length !== 0)
+        throw new NativeClaimError("eligibility authorization differs from the exact claim intent", "authorization");
+    if (requireSigned) {
+        if (credential.signatureExpirationLedger <= expected.latestLedger || credential.signatureExpirationLedger > expected.maxExpirationLedger)
+            throw new NativeClaimError("eligibility authorization expiry is outside the approved ledger bound", "authorization");
+        if (credential.signature.type !== "scvVec" || !credential.signature.vec?.length)
+            throw new NativeClaimError("eligibility authorization has no native account signatures", "authorization");
+    }
+    else if (credential.signature.type !== "scvVoid" && !(credential.signature.type === "scvVec" && credential.signature.vec?.length === 0)) {
+        throw new NativeClaimError("refusing to sign an already signed eligibility credential", "authorization");
+    }
+}
+/** Signs only the expected admission entry. This helper never signs a transaction. */
+export async function signEligibilityAuthorization(unsignedEntry, expected, signer, expirationLedger, networkPassphrase) {
+    validateEligibilityAuthorization(unsignedEntry, expected, false);
+    u32(expirationLedger, "expiration ledger");
+    if (expirationLedger <= expected.latestLedger || expirationLedger > expected.maxExpirationLedger)
+        throw new NativeClaimError("eligibility expiration is outside the approved range", "authorization");
+    if (!networkPassphrase)
+        throw new NativeClaimError("network passphrase is required");
+    const signed = await authorizeEntry(unsignedEntry, signer, expirationLedger, networkPassphrase);
+    validateEligibilityAuthorization(signed, expected);
+    return signed;
+}
+/** Exact local intent and native role scope; does not relax ordinary SDK authorization. */
+export function validateNativeTransaction(tx, plan, requireEligibilitySigned = true) {
+    address(plan.source, "account", "claim transaction source");
+    if (tx.source !== plan.source)
+        throw new NativeClaimError(`native transaction source ${tx.source} differs from reviewed source ${plan.source}`, "authorization");
+    if (tx.operations.length !== 1)
+        throw new NativeClaimError(`native transaction has ${tx.operations.length} operations; exactly one was reviewed`, "authorization");
+    if (tx.memo.type !== "none")
+        throw new NativeClaimError(`native transaction memo type ${tx.memo.type} differs from reviewed none`, "authorization");
+    if (BigInt(tx.fee) > plan.maxFeeStroops)
+        throw new NativeClaimError(`native transaction network fee ${tx.fee} stroops exceeds the configured maximum ${plan.maxFeeStroops} stroops`, "authorization");
+    const op = tx.operations[0];
+    if (op.type !== "invokeHostFunction" || op.source && op.source !== plan.source || op.func.type !== "hostFunctionTypeInvokeContract")
+        throw new NativeClaimError("unexpected native operation", "authorization");
+    const call = op.func.invokeContract;
+    if (Address.fromScAddress(call.contractAddress).toString() !== plan.contract || call.functionName.toString() !== plan.method || call.args.length !== plan.args.length || call.args.some((arg, i) => arg.toXDR("base64") !== plan.args[i].toXDR("base64")))
+        throw new NativeClaimError("native operation differs from the exact reviewed intent", "authorization");
+    const entries = op.auth ?? [];
+    if (entries.length !== (plan.eligibility ? 2 : 1))
+        throw new NativeClaimError("unexpected native authorization count", "authorization");
+    const sources = entries.filter(entry => entry.credentials.type === "sorobanCredentialsSourceAccount");
+    if (sources.length !== 1 || !sameInvocation(sources[0].rootInvocation, plan.sourceInvocation))
+        throw new NativeClaimError("holder or owner authorization differs from exact reviewed intent", "authorization");
+    if (plan.eligibility) {
+        if (plan.eligibility.account === plan.source)
+            throw new NativeClaimError("eligibility account must be separate from claimant", "authorization");
+        const separate = entries.filter(entry => entry.credentials.type !== "sorobanCredentialsSourceAccount");
+        if (separate.length !== 1)
+            throw new NativeClaimError("unexpected second authorizer", "authorization");
+        validateEligibilityAuthorization(separate[0], plan.eligibility, requireEligibilitySigned);
+    }
+}
+export function assertSignedBodyUnchanged(prepared, signedXdr, passphrase) {
+    const signed = TransactionBuilder.fromXDR(signedXdr, passphrase);
+    if (!(signed instanceof Transaction) || hex(signed.hash()) !== hex(prepared.hash()))
+        throw new NativeClaimError("wallet changed the reviewed native transaction body", "authorization");
+    if (!signed.signatures.length)
+        throw new NativeClaimError("wallet returned an unsigned transaction", "authorization");
+    return signed;
+}

package/dist/native-code-policy.d.ts

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

package/dist/native-code-policy.js

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

package/dist/native-codec.d.ts

@@ -0,0 +1,38 @@
+/** Local successor-ABI helpers. No deployed defaults are changed by this module. */
+import { xdr } from "@stellar/stellar-sdk";
+import { type PaymentDestination } from "./payment.js";
+export declare const NATIVE_REGISTRAR_ERRORS: Record<number, string>;
+export declare class NativeClaimError extends Error {
+    readonly kind: "unsupported" | "unavailable" | "invalid" | "authorization" | "pending" | "failed";
+    readonly txHash: string | null;
+    readonly contractCode: number | null;
+    readonly contractError: string | null;
+    constructor(message: string, kind?: "unsupported" | "unavailable" | "invalid" | "authorization" | "pending" | "failed", txHash?: string | null);
+}
+export declare function exactObject(raw: unknown, keys: readonly string[], label: string): Record<string, unknown>;
+export declare function u64(value: unknown, label: string): bigint;
+export declare function u32(value: unknown, label: string): number;
+export declare function amount(value: unknown, label: string): bigint;
+export declare function bool(value: unknown, label: string): boolean;
+export declare function address(value: unknown, kind: "account" | "contract" | "identity", label: string): string;
+export declare function bytes32(value: unknown, label: string): Uint8Array;
+export declare function hex32(value: unknown, label: string): string;
+export declare const hex: (value: Uint8Array) => string;
+export declare const unhex: (value: string) => Uint8Array;
+export declare const utf8: (value: string) => Uint8Array;
+export declare function label(value: unknown): string;
+export declare function namespaceNode(namespace: string): Uint8Array;
+export declare const sc: {
+    address: (value: string) => xdr.ScVal;
+    bytes: (value: Uint8Array) => xdr.ScVal;
+    u64: (value: bigint) => xdr.ScVal;
+    u32: (value: number) => xdr.ScVal;
+    i128: (value: bigint) => xdr.ScVal;
+    bool: (value: boolean) => xdr.ScVal;
+    symbol: (value: string) => xdr.ScVal;
+    option: (value: xdr.ScVal | null) => xdr.ScVal;
+};
+/** Contract structs are canonical symbol-keyed maps, not generic JSON maps. */
+export declare function struct(fields: Record<string, xdr.ScVal>): xdr.ScVal;
+export declare function paymentDestinationToScVal(raw: PaymentDestination): xdr.ScVal;
+export declare function sameScVal(left: xdr.ScVal, right: xdr.ScVal): boolean;

package/dist/native-codec.js

@@ -0,0 +1,95 @@
+/** 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 class NativeClaimError extends Error {
+    kind;
+    txHash;
+    contractCode;
+    contractError;
+    constructor(message, kind = "invalid", txHash = null) {
+        super(message);
+        this.kind = kind;
+        this.txHash = txHash;
+        this.name = "NativeClaimError";
+        const match = /Error\(Contract, #(\d+)\)/.exec(message);
+        this.contractCode = match ? Number(match[1]) : null;
+        this.contractError = this.contractCode === null ? null : NATIVE_REGISTRAR_ERRORS[this.contractCode] ?? null;
+    }
+}
+export function exactObject(raw, keys, label) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).sort().join(",") !== [...keys].sort().join(","))
+        throw new NativeClaimError(`invalid ${label} fields`);
+    return raw;
+}
+export function u64(value, label) {
+    if (typeof value !== "bigint" || value < 0n || value > 18446744073709551615n)
+        throw new NativeClaimError(`${label} must be an unsigned 64-bit bigint`);
+    return value;
+}
+export function u32(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 4294967295)
+        throw new NativeClaimError(`${label} must be an unsigned 32-bit number`);
+    return value;
+}
+export function amount(value, label) {
+    if (typeof value !== "bigint" || value < 0n || value > (1n << 127n) - 1n)
+        throw new NativeClaimError(`${label} must be a nonnegative i128 bigint`);
+    return value;
+}
+export function bool(value, label) {
+    if (typeof value !== "boolean")
+        throw new NativeClaimError(`${label} must be boolean`);
+    return value;
+}
+export function address(value, kind, label) {
+    if (typeof value !== "string" || !(kind !== "contract" && StrKey.isValidEd25519PublicKey(value) || kind !== "account" && StrKey.isValidContract(value)))
+        throw new NativeClaimError(`${label} must be a valid ${kind === "identity" ? "G or C" : kind === "account" ? "G" : "C"} address`);
+    return value;
+}
+export function bytes32(value, label) {
+    if (!(value instanceof Uint8Array) || value.length !== 32)
+        throw new NativeClaimError(`${label} must contain exactly 32 bytes`);
+    return new Uint8Array(value);
+}
+export function hex32(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
+        throw new NativeClaimError(`${label} must be 64 lowercase hex characters`);
+    return value;
+}
+export const hex = (value) => Array.from(value, byte => byte.toString(16).padStart(2, "0")).join("");
+export const unhex = (value) => Uint8Array.from(hex32(value, "32-byte value").match(/../g), byte => parseInt(byte, 16));
+export const utf8 = (value) => new TextEncoder().encode(value);
+export function label(value) {
+    if (typeof value !== "string" || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(value))
+        throw new NativeClaimError("intent label must be canonical lowercase ASCII, 1–63 characters");
+    return value;
+}
+export function namespaceNode(namespace) {
+    const combined = new Uint8Array(64);
+    combined.set(hash(utf8(label(namespace))), 32);
+    return new Uint8Array(hash(combined));
+}
+export const sc = {
+    address: (value) => new Address(value).toScVal(),
+    bytes: (value) => nativeToScVal(value, { type: "bytes" }),
+    u64: (value) => nativeToScVal(value, { type: "u64" }),
+    u32: (value) => nativeToScVal(value, { type: "u32" }),
+    i128: (value) => nativeToScVal(value, { type: "i128" }),
+    bool: (value) => nativeToScVal(value, { type: "bool" }),
+    symbol: (value) => nativeToScVal(value, { type: "symbol" }),
+    option: (value) => value ?? xdr.ScVal.scvVoid(),
+};
+/** Contract structs are canonical symbol-keyed maps, not generic JSON maps. */
+export function struct(fields) {
+    return xdr.ScVal.scvMap(Object.keys(fields).sort().map(key => new xdr.ScMapEntry({ key: sc.symbol(key), val: fields[key] })));
+}
+export function paymentDestinationToScVal(raw) {
+    const payment = validatePaymentDestination(raw);
+    if (StrKey.isValidMed25519PublicKey(payment.address)) {
+        const value = decodeMuxedAddress(payment.address);
+        return xdr.ScVal.scvVec([sc.symbol("Muxed"), struct({ account: sc.address(value.account), id: sc.u64(BigInt(value.id)) })]);
+    }
+    return xdr.ScVal.scvVec([sc.symbol("Direct"), struct({ address: sc.address(payment.address), memo: paymentMemoToScVal(payment.memo) })]);
+}
+export function sameScVal(left, right) { return left.toXDR("base64") === right.toXDR("base64"); }

package/dist/native-history.d.ts

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

package/dist/native-history.js

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

package/dist/native-transport.d.ts

@@ -0,0 +1,66 @@
+import { Transaction, rpc, xdr } from "@stellar/stellar-sdk";
+import { type NativeAuthorizationPlan } from "./native-auth.js";
+export type NativeSigner = {
+    publicKey(): string | Promise<string>;
+    signTransaction(encoded: string, opts: {
+        networkPassphrase: string;
+    }): Promise<string | {
+        signedTxXdr: string;
+    }>;
+};
+export type NativeContext = {
+    registryId: string;
+    passphrase: string;
+    server: rpc.Server;
+    signer: NativeSigner;
+    fee: string;
+    timeoutSecs: number;
+    maxFeeStroops: bigint;
+    read(contract: string, method: string, args: xdr.ScVal[]): Promise<unknown>;
+    serialize<T>(work: () => Promise<T>): Promise<T>;
+};
+export type NativeCapability = {
+    supported: false;
+    registrar: string;
+    reason: "legacy-template" | "unsupported-version";
+} | {
+    supported: true;
+    version: 1;
+    registrar: string;
+    resolver: string;
+    registry: string;
+    namespace: string;
+    owner: string;
+    ownerEpoch: bigint;
+};
+/** Historical reads must not trust an upgraded Registrar that can fabricate receipts. Resolver changes do not block this Registrar-only check. */
+export declare function verifyRegistrarProvenance(context: NativeContext, registrar: string, namespace: string): Promise<void>;
+export declare function nativeCapability(context: NativeContext, namespace: string): Promise<NativeCapability>;
+export declare function requireNative(context: NativeContext, namespace: string): Promise<Extract<NativeCapability, {
+    supported: true;
+}>>;
+export type NativePrepared = {
+    transactionXdr: string;
+    hash: string;
+    networkPassphrase: string;
+    feeStroops: bigint;
+    eligibilityEntryXdr: string | null;
+};
+export type NativeWriteOptions = {
+    /** Exact native admission authorization from the app. This is not an owner transaction signature. */
+    eligibilityAuthorization?: string;
+    /** Persist the public recovery reference before wallet signing/broadcast. Rejecting stops submission. */
+    onPrepared?: (prepared: NativePrepared) => void | Promise<void>;
+};
+export declare function prepareNative(context: NativeContext, plan: NativeAuthorizationPlan, options?: NativeWriteOptions): Promise<{
+    transaction: Transaction;
+    prepared: NativePrepared;
+}>;
+/** No automatic transaction retry, implicit restoration or hash-losing error path. */
+export declare function sendNative(context: NativeContext, plan: NativeAuthorizationPlan, options?: NativeWriteOptions): Promise<{
+    hash: string;
+    ledger: number;
+    value: unknown;
+}>;
+/** Bind terminal RPC context before classifying success or failure. An incomplete response remains uncertain. */
+export declare function validateNativeTerminalReceipt(receipt: rpc.Api.GetSuccessfulTransactionResponse | rpc.Api.GetFailedTransactionResponse, expectedHash: string, passphrase: string): void;