@sorandomains/holder 0.5.0 → 0.5.1

package/README.md

@@ -143,7 +143,7 @@ supply the matching `primaryId` explicitly.
 
 ## Native username claiming
 
-Native username claiming uses `claimQuote`, `createClaimIntent`, `buildClaim` and `claim`. The current namespace owner must first enable the public policy. The claimant's G wallet authorizes the exact username, complete receiving destination, owner price, policy version and deadline. `recoverClaim` reads the original immutable receipt; it never silently retries an uncertain transaction. `acceptNameTransferWithDestination` and `renewName` cover separately authorized holder lifecycle actions.
+Native username claiming uses `claimQuote`, `createClaimIntent`, `buildClaim` and `claim`. The current namespace owner must first enable the public policy. The claimant's G wallet authorizes the exact username, complete receiving destination, owner price, policy version and deadline. `recoverClaim` reads the original immutable receipt; it never silently retries an uncertain transaction. Receipt reads, receipt absence and confirmed transaction results are accepted only after a clean Registrar attestation and executable check with RPC ledger context at least as recent as the receipt read or transaction inclusion. Missing or older context stops recovery; retain the original request and transaction hash. This check trusts the configured RPC to report its state and ledger honestly. Later namespace-owner, claim-policy or Resolver changes alone do not invalidate a historical receipt, while a tainted or upgraded Registrar cannot supply authoritative history. `acceptNameTransferWithDestination` and `renewName` cover separately authorized holder lifecycle actions.
 
 Read the [native claim APIs, security boundaries and complete signup flow](https://github.com/SoranDomains/sdk/blob/main/NATIVE-CLAIMS.md). G/no memo, G with ID/Text/Hash, full M/no separate memo and C/no memo remain supported payment destinations. Current transaction-signing adapters use classic G accounts.
 

package/dist/index.d.ts

@@ -35,7 +35,7 @@ import { type PaymentDestination } from "./payment.js";
 export { encodeMuxedAddress, decodeMuxedAddress, PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination, type PaymentMemo, type PaymentDestination } from "./payment.js";
 import { type ClaimSubmitOptions } from "./native-holder.js";
 import type { ClaimIntent, TransferIntent, RenewIntent } from "./native-types.js";
-import type { NativeWriteOptions } from "./native-transport.js";
+import { type NativeWriteOptions } from "./native-transport.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
 export * from "./native-approver.js";
@@ -244,6 +244,8 @@ export declare class SoranHolder {
     private paymentResolverOf;
     private assertMemoFree;
     private read;
+    private readWithLedger;
+    private simulateRead;
     private signEnvelope;
     private serialize;
     private sourceAccount;

package/dist/index.js

@@ -36,6 +36,7 @@ import { decodeMuxedAddress, destinationFromNative, paymentFromNative, paymentMe
 export { encodeMuxedAddress, decodeMuxedAddress, PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination } from "./payment.js";
 import { NativeHolderClient } from "./native-holder.js";
 import { NativeClaimError } from "./native-codec.js";
+import { requireReadLedger } from "./native-transport.js";
 export * from "./native-types.js";
 export * from "./native-allowlist.js";
 export * from "./native-approver.js";
@@ -280,7 +281,8 @@ export class SoranHolder {
     }
     nativeClient() {
         return new NativeHolderClient({ registryId: this.registryId, passphrase: this.passphrase, server: this.server, signer: this.signer, fee: this.fee, timeoutSecs: this.timeoutSecs, maxFeeStroops: this.maxNativeFeeStroops,
-            read: (id, method, args) => this.read(id, method, args), serialize: work => this.serialize(work) });
+            read: (id, method, args) => this.read(id, method, args),
+            readWithLedger: (id, method, args) => this.readWithLedger(id, method, args), serialize: work => this.serialize(work) });
     }
     nativeClaimCapability(namespace) { return this.nativeClient().nativeClaimCapability(namespace); }
     claimQuote(name, claimant) { return this.nativeClient().claimQuote(name, claimant); }
@@ -603,6 +605,13 @@ export class SoranHolder {
         return registrar;
     }
     async read(contractId, fn, args) {
+        return (await this.simulateRead(contractId, fn, args)).value;
+    }
+    async readWithLedger(contractId, fn, args) {
+        const result = await this.simulateRead(contractId, fn, args);
+        return { value: result.value, ledger: requireReadLedger(result.ledger) };
+    }
+    async simulateRead(contractId, fn, args) {
         const tx = new TransactionBuilder(new Account(SIM_SOURCE, "0"), {
             fee: BASE_FEE,
             networkPassphrase: this.passphrase,
@@ -619,7 +628,7 @@ export class SoranHolder {
         if (!rpc.Api.isSimulationSuccess(sim) || !sim.result?.retval)
             throw new HolderError(`${fn}: missing simulation return value`, contractId, fn);
         const v = scValToNative(sim.result.retval);
-        return v === undefined ? null : v;
+        return { value: v === undefined ? null : v, ledger: sim.latestLedger };
     }
     async signEnvelope(xdrBase64) {
         const signed = await this.signer.signTransaction(xdrBase64, {

package/dist/native-holder.d.ts

@@ -31,7 +31,7 @@ export declare class NativeHolderClient {
     private checkQuote;
     claimReceipt(namespace: string, claimant: string, requestId: string): Promise<ClaimReceipt | null>;
     private receiptAt;
-    recoverClaim(intent: ClaimIntent): Promise<ClaimReceipt | null>;
+    recoverClaim(input: ClaimIntent): Promise<ClaimReceipt | null>;
     private planClaim;
     buildClaim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<PreparedClaim>;
     claim(intent: ClaimIntent, options?: ClaimSubmitOptions): Promise<NativeClaimSubmission>;

package/dist/native-holder.js

@@ -1,6 +1,6 @@
 import { hash, scValToNative, xdr } from "@stellar/stellar-sdk";
 import { NativeClaimError, address, bytes32, exactObject, hex, hex32, label, namespaceNode, sc, u64, unhex, utf8 } from "./native-codec.js";
-import { nativeCapability, requireNative, verifyRegistrarProvenance, prepareNative, sendNative } from "./native-transport.js";
+import { nativeCapability, requireNative, requireReadLedger, verifyRegistrarProvenance, prepareNative, sendNative } from "./native-transport.js";
 import { claimIntentToScVal, claimIntentFromNative, claimQuoteFromNative, claimReceiptFromNative, claimResultFromNative, destinationPreviewFromNative, transferIntentToScVal, renewIntentToScVal, nativeIntentHash, claimLabelToScVal } from "./native-types.js";
 import { paymentDestinationToScVal } from "./native-codec.js";
 import { validatePaymentDestination } from "./payment.js";
@@ -27,6 +27,8 @@ function receiptMatches(receipt, method, intent, holder) {
     if (receipt.intentHash !== nativeIntentHash(method, intent) || receipt.holder !== holder)
         throw new NativeClaimError("request ID already belongs to a different immutable intent");
     const raw = scValToNative(intent), expectedOperation = { claim: "claim", issue_reserved_with_destination: "reserved", accept_transfer_with_destination: "transfer", renew_holder: "renew" }[method];
+    if (receipt.timestamp < raw.context.valid_after || receipt.timestamp > raw.context.deadline)
+        throw new NativeClaimError("receipt timestamp is outside the original request window");
     const nodeBytes = new Uint8Array(64);
     nodeBytes.set(raw.context.namespace);
     nodeBytes.set(hash(raw.label), 32);
@@ -44,20 +46,34 @@ function receiptMatches(receipt, method, intent, holder) {
     else {
         if (receipt.feeAmount !== 0n || receipt.feeRecipient !== null)
             throw new NativeClaimError("lifecycle receipt unexpectedly contains a username fee");
-        if (method === "accept_transfer_with_destination" && receipt.expiresAt !== raw.expected_expiry)
-            throw new NativeClaimError("transfer receipt changed the lease");
+        if (method === "accept_transfer_with_destination" && (receipt.expiresAt !== raw.expected_expiry || receipt.timestamp > raw.proposal_expires))
+            throw new NativeClaimError("transfer receipt changed the lease or exceeded the proposal window");
         if (method === "renew_holder" && (receipt.expiresAt < raw.min_new_expiry || receipt.expiresAt > raw.max_new_expiry || receipt.expiresAt !== (receipt.timestamp > raw.expected_expiry ? receipt.timestamp : raw.expected_expiry) + raw.term_secs))
             throw new NativeClaimError("renewal receipt differs from signed lease bounds");
     }
 }
-function confirmedResult(result, method, encoded, holder) { try {
-    const decoded = claimResultFromNative(result.value);
-    receiptMatches(decoded.receipt, method, encoded, holder);
-    return { ...decoded, transaction: { hash: result.hash, ledger: result.ledger } };
+function receiptReadMatches(receipt, holder, observedLedger) {
+    requireReadLedger(receipt.ledger);
+    if (receipt.holder !== holder || receipt.ledger > observedLedger)
+        throw new NativeClaimError("receipt holder or inclusion ledger differs from the requested snapshot", "unavailable");
+}
+async function confirmedResult(context, result, method, encoded, holder) {
+    try {
+        // Inclusion proves the reviewed transaction ran, not that an owner left the
+        // Registrar on its trusted implementation until it ran. Recheck after it.
+        const raw = scValToNative(encoded);
+        await verifyRegistrarProvenance(context, raw.context.registrar, hex(raw.context.namespace), result.ledger);
+        const decoded = claimResultFromNative(result.value);
+        receiptReadMatches(decoded.receipt, holder, result.ledger);
+        if (decoded.status === "fresh" && decoded.receipt.ledger !== result.ledger)
+            throw new NativeClaimError("fresh receipt does not belong to the confirmed ledger");
+        receiptMatches(decoded.receipt, method, encoded, holder);
+        return { ...decoded, transaction: { hash: result.hash, ledger: result.ledger } };
+    }
+    catch (error) {
+        throw new NativeClaimError(`transaction confirmed but result could not be verified: ${String(error)}; recover the original request`, "pending", result.hash);
+    }
 }
-catch (error) {
-    throw new NativeClaimError(`transaction confirmed but result could not be verified: ${String(error)}; recover the original request`, "pending", result.hash);
-} }
 export class NativeHolderClient {
     context;
     constructor(context) {
@@ -100,14 +116,31 @@ export class NativeHolderClient {
         if (quote.node !== hex(hash(bytes)))
             throw new NativeClaimError("quote name node is invalid", "unavailable");
     }
-    async claimReceipt(namespace, claimant, requestId) { return this.receiptAt(await this.registrar(canonicalNamespace(namespace)), claimant, requestId); }
-    async receiptAt(registrar, claimant, requestId) {
-        const raw = await this.context.read(registrar, "claim_receipt", [sc.address(address(claimant, "identity", "receipt holder")), sc.bytes(unhex(requestId))]);
-        return raw === null ? null : claimReceiptFromNative(raw);
+    async claimReceipt(namespace, claimant, requestId) {
+        const canonical = canonicalNamespace(namespace);
+        return this.receiptAt(await this.registrar(canonical), hex(namespaceNode(canonical)), claimant, requestId);
+    }
+    async receiptAt(registrar, namespace, claimant, requestId) {
+        const holder = address(claimant, "identity", "receipt holder");
+        const snapshot = await this.context.readWithLedger(registrar, "claim_receipt", [sc.address(holder), sc.bytes(unhex(hex32(requestId, "request ID")))]);
+        const ledger = requireReadLedger(snapshot?.ledger);
+        // Validate both Some and None before they can drive a recovery/replay decision.
+        await verifyRegistrarProvenance(this.context, registrar, namespace, ledger);
+        if (snapshot.value === null)
+            return null;
+        const receipt = claimReceiptFromNative(snapshot.value);
+        receiptReadMatches(receipt, holder, ledger);
+        return receipt;
+    }
+    async recoverClaim(input) {
+        const encoded = claimIntentToScVal(input), intent = claimIntentFromNative(scValToNative(encoded));
+        scoped(this.context, intent.context);
+        await verifyRegistrarProvenance(this.context, intent.context.registrar, intent.context.namespace);
+        const receipt = await this.receiptAt(intent.context.registrar, intent.context.namespace, intent.claimant, intent.context.requestId);
+        if (receipt)
+            receiptMatches(receipt, "claim", encoded, intent.claimant);
+        return receipt;
     }
-    async recoverClaim(intent) { const encoded = claimIntentToScVal(intent); scoped(this.context, intent.context); await verifyRegistrarProvenance(this.context, intent.context.registrar, intent.context.namespace); if (await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(unhex(intent.context.namespace))]) !== intent.context.registrar)
-        throw new NativeClaimError("recovery Registrar is not the Registry attestation", "unavailable"); const receipt = await this.receiptAt(intent.context.registrar, intent.claimant, intent.context.requestId); if (receipt)
-        receiptMatches(receipt, "claim", encoded, intent.claimant); return receipt; }
     async planClaim(input, proof = []) {
         const encoded = claimIntentToScVal(input);
         const intent = claimIntentFromNative(scValToNative(encoded));
@@ -177,7 +210,7 @@ export class NativeHolderClient {
         // Snapshot before any awaits: callers cannot mutate reviewed destination/amount mid-flow.
         const snapshot = claimIntentFromNative(scValToNative(claimIntentToScVal(intent)));
         return this.context.serialize(async () => { const old = await this.recoverClaim(snapshot); if (old)
-            return { status: "replayed", receipt: old, transaction: null }; const { plan } = await this.planClaim(snapshot, options.proof); const result = await sendNative(this.context, plan, options); return confirmedResult(result, "claim", claimIntentToScVal(snapshot), snapshot.claimant); });
+            return { status: "replayed", receipt: old, transaction: null }; const { plan } = await this.planClaim(snapshot, options.proof); const result = await sendNative(this.context, plan, options); return confirmedResult(this.context, result, "claim", claimIntentToScVal(snapshot), snapshot.claimant); });
     }
     async renewalPreview(name) {
         const parsed = names(name), registrar = await this.registrar(parsed.namespace);
@@ -198,9 +231,7 @@ export class NativeHolderClient {
         scoped(this.context, request);
         return this.context.serialize(async () => {
             await verifyRegistrarProvenance(this.context, request.registrar, request.namespace);
-            if (await this.context.read(this.context.registryId, "registrar_of", [sc.bytes(unhex(request.namespace))]) !== request.registrar)
-                throw new NativeClaimError("recovery Registrar is not the Registry attestation", "unavailable");
-            const old = await this.receiptAt(request.registrar, holder, request.requestId);
+            const old = await this.receiptAt(request.registrar, request.namespace, holder, request.requestId);
             if (old) {
                 receiptMatches(old, method, intent, holder);
                 return { status: "replayed", receipt: old, transaction: null };
@@ -215,7 +246,7 @@ export class NativeHolderClient {
             if (source !== holder)
                 throw new NativeClaimError("connected wallet is not the intended holder/recipient", "authorization");
             const result = await sendNative(this.context, { source, contract: request.registrar, method, args: [intent], sourceInvocation: { contract: request.registrar, method, args: [intent], children: child ? [child] : [] }, maxFeeStroops: this.context.maxFeeStroops }, options);
-            return confirmedResult(result, method, intent, holder);
+            return confirmedResult(this.context, result, method, intent, holder);
         });
     }
 }

package/dist/native-transport.d.ts

@@ -8,6 +8,10 @@ export type NativeSigner = {
         signedTxXdr: string;
     }>;
 };
+export type NativeRead = {
+    value: unknown;
+    ledger: number;
+};
 export type NativeContext = {
     registryId: string;
     passphrase: string;
@@ -17,6 +21,7 @@ export type NativeContext = {
     timeoutSecs: number;
     maxFeeStroops: bigint;
     read(contract: string, method: string, args: xdr.ScVal[]): Promise<unknown>;
+    readWithLedger(contract: string, method: string, args: xdr.ScVal[]): Promise<NativeRead>;
     serialize<T>(work: () => Promise<T>): Promise<T>;
 };
 export type NativeCapability = {
@@ -33,8 +38,10 @@ export type NativeCapability = {
     owner: string;
     ownerEpoch: bigint;
 };
+/** A missing context is not evidence that an RPC observation is fresh. */
+export declare function requireReadLedger(value: unknown, minimum?: number): number;
 /** 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 verifyRegistrarProvenance(context: NativeContext, registrar: string, namespace: string, minimumLedger?: number): 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;

package/dist/native-transport.js

@@ -3,8 +3,46 @@ import { NativeClaimError, address, bytes32, hex, namespaceNode, sc, unhex } fro
 import { assertSignedBodyUnchanged, validateEligibilityAuthorization, validateNativeTransaction } from "./native-auth.js";
 /** This published legacy code has owner-only issuance. Missing RPC data is never legacy detection. */
 const LEGACY_REGISTRAR_HASH = "ed06b3374ff4342b4a2316fc546505132cd8fd35be6666571cf088710af9bbc6";
+/** A missing context is not evidence that an RPC observation is fresh. */
+export function requireReadLedger(value, minimum = 1) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value < 1 || value > 0xffff_ffff)
+        throw new NativeClaimError("RPC read has missing, invalid or stale ledger context", "unavailable");
+    return value;
+}
+/** Every post-receipt observation must be at least as new as that simulation.
+ * Registry taint is irreversible: clean at/after the receipt rules out an
+ * upgrade before it, even when these truthful RPC snapshots differ in ledger.
+ * The RPC remains trusted to report its ledger and returned state honestly.
+ */
+async function verifyProvenanceAfter(context, registrar, namespace, minimumLedger) {
+    requireReadLedger(minimumLedger);
+    const node = sc.bytes(unhex(namespace));
+    const key = new Contract(registrar).getFootprint();
+    const [attestation, taint, templates, executable] = await Promise.all([
+        context.readWithLedger(context.registryId, "registrar_of", [node]),
+        context.readWithLedger(context.registryId, "registrar_tainted", [node]),
+        context.readWithLedger(context.registryId, "template_hashes", []),
+        context.server.getLedgerEntries(key),
+    ]);
+    for (const observation of [attestation, taint, templates])
+        requireReadLedger(observation?.ledger, minimumLedger);
+    requireReadLedger(executable?.latestLedger, minimumLedger);
+    if (attestation.value !== registrar || taint.value !== false || !Array.isArray(templates.value) || templates.value.length !== 2)
+        throw new NativeClaimError("Registrar provenance changed or is unavailable after receipt read", "unavailable");
+    // getContractInstance discards latestLedger; read and bind the exact entry.
+    const entry = executable.entries?.[0];
+    if (executable.entries?.length !== 1 || !entry || entry.key.toXDR("base64") !== key.toXDR("base64") || entry.val.type !== "contractData")
+        throw new NativeClaimError("Registrar executable proof is missing or mismatched", "unavailable");
+    const data = entry.val.value;
+    if (data.contract.toXDR("base64") !== new Contract(registrar).address().toScAddress().toXDR("base64") || data.key.type !== "scvLedgerKeyContractInstance" || data.durability !== xdr.ContractDataDurability.persistent || data.val.type !== "scvContractInstance" || data.val.value.executable.type !== "contractExecutableWasm")
+        throw new NativeClaimError("Registrar executable proof is not the requested Wasm instance", "unavailable");
+    if (hex(bytes32(templates.value[0], "Registry Registrar template")) !== hex(data.val.value.executable.wasmHash.value))
+        throw new NativeClaimError("Registrar executable differs from immutable Registry template after receipt read", "unavailable");
+}
 /** Historical reads must not trust an upgraded Registrar that can fabricate receipts. Resolver changes do not block this Registrar-only check. */
-export async function verifyRegistrarProvenance(context, registrar, namespace) {
+export async function verifyRegistrarProvenance(context, registrar, namespace, minimumLedger) {
+    if (minimumLedger !== undefined)
+        return verifyProvenanceAfter(context, registrar, namespace, minimumLedger);
     const node = sc.bytes(unhex(namespace));
     const [attested, tainted, templates, instance] = await Promise.all([
         context.read(context.registryId, "registrar_of", [node]), context.read(context.registryId, "registrar_tainted", [node]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorandomains/holder",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Manage your own Soran name on Stellar \u2014 records, profile, reverse, primary, and transfers, signed by your key.",
   "type": "module",
   "main": "./dist/index.js",