@sorandomains/holder 0.2.0 → 0.3.1

package/README.md

@@ -1,5 +1,10 @@
 # @sorandomains/holder
 
+Version 0.3.1 targets Stellar SDK17 (`>=17 <18`). ASCII names
+and labels are validated before lowercase normalization; Unicode lookalikes are
+rejected. Writes continue to target the owning Registry/Registrar/Resolver. Universal
+Lookup is the read entry point in `@sorandomains/lookup` 0.5.1.
+
 Your Soran name, managed with your own key. The third piece of the SDK
 trilogy: [`@sorandomains/lookup`](https://www.npmjs.com/package/@sorandomains/lookup)
 reads names, [`@sorandomains/owner`](https://www.npmjs.com/package/@sorandomains/owner)
@@ -22,11 +27,50 @@ await me.setProfile("alice.nova", {  // the standard keys every wallet reads
 });
 ```
 
+## Publish payment instructions
+
+Ordinary G/C names resolve without extra setup. `setPayment` discovers the native
+Resolver from Registry, checks its Registry and Registrar anchors and payment API
+version, then signs one call that updates address and memo in that Resolver:
+
+```ts
+const me = new SoranHolder({ signer });
+await me.setPayment("alice.nova", {
+  address: exchangeDepositAddress,
+  memo: { type: "id", value: "18446744073709551615" },
+});
+// Explicitly remove a required memo:
+await me.setPayment("alice.nova", { address: myAddress, memo: { type: "none" } });
+```
+
+ID values are canonical unsigned 64-bit decimal strings; text is exact nonempty
+UTF-8 up to 28 bytes; hashes are 64 lowercase hex characters. Required memos work
+only with G addresses. C addresses permit `none`. The Resolver authorizes the
+current holder and updates its records atomically. Failures never retry as separate
+address and text writes. Old unsupported Resolvers fail closed; no payment-specific
+contract address is configured.
+
+`setText` and `clearText` reserve `payment` for `setPayment`. Configured missing or
+empty instructions remain errors. Remove a memo with explicit `none`.
+`setRecord` invokes native `set_addr`, which atomically permits ordinary names and
+updates an existing valid `none` tuple while rejecting required memos or broken
+state. A concurrently added memo cannot be replaced by a client-side None rewrite.
+`setAddress` retains its Registrar-only semantics and first requires a valid native
+`none` result. It changes only the built-in target; an explicit Resolver payment
+record continues to take precedence. Failed preflight reads never permit a write.
+
+Resolver selection follows the namespace owner's Registry pointer. Compatibility
+and anchor checks do not prove custom/upgraded code is trustworthy. Upgraded
+Resolvers remain supported. Payment readers must use `resolvePayment` and preserve
+the returned memo; old deployed code and direct Registrar reads cannot be upgraded
+by installing this SDK. The verified deployment used by this release is listed below.
+
 ## What's in the box
 
 | Operation | What it does |
 | --- | --- |
-| `setRecord` | Point your name's explicit resolver record at any address (generation-gated — stops resolving the moment the name changes hands) |
+| `setPayment` | Atomically publish address and memo in the namespace native Resolver |
+| `setRecord` | Change a memo-free native Resolver address atomically; required memos need `setPayment` |
 | `setAddress` | Re-point the built-in (Registrar) resolution target |
 | `setText` / `setProfile` / `clearText` | Publish text records; `setProfile` writes the standard `PROFILE_KEYS` (one transaction per key); records are overwrite-only on chain — `clearText` retracts by writing the empty value standard readers treat as unset |
 | `setReverse` / `clearReverse` | Claim your address→name reverse record — the contract refuses names that don't already resolve to you (`ForwardMismatch`) |
@@ -64,3 +108,20 @@ its own (enforced in CI), with `@stellar/stellar-sdk` as the only peer
 dependency.
 
 Docs: <https://github.com/SoranDomains/docs> · License: MIT
+
+Primary writes verify the Primary contract's Registry anchor before signing.
+Custom Registry or passphrase settings do not inherit a Primary deployment pin;
+supply the matching `primaryId` explicitly.
+
+## Verified testnet deployment
+
+Verified on 2026-09-05 at ledger 4520986. Network passphrase: `Test SDF Network ; September 2015`.
+
+| Contract | Address |
+|---|---|
+| Registry | `CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE` |
+| Primary | `CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X` |
+
+Mainnet has no deployment preset. Custom networks must supply their own verified
+addresses. Universal Lookup upgrades remain immediately executable; an address
+and ABI version do not pin the code that will execute after a governance upgrade.

package/dist/index.d.ts

@@ -30,13 +30,15 @@
  * before signing. Operations on one instance are serialized so concurrent
  * calls cannot race the account sequence number.
  */
+import { type PaymentDestination } from "./payment.js";
+export { PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination, type PaymentMemo, type PaymentDestination } from "./payment.js";
 /** Known public deployments. Pass explicit options for anything else. */
 export declare const DEPLOYMENTS: {
     readonly testnet: {
         readonly rpcUrl: "https://soroban-testnet.stellar.org";
         readonly passphrase: string;
-        readonly registryId: "CAUEHYVLLNNDZ4H5QWCPBDWEONRI44SI3XYSEACB4U3HYILIVQGQAMNI";
-        readonly primaryId: "CAZMXB6UBXKL4DGC2GUC5VKHIZMF47CIZXZFAZPYLM2RP6ZJZNSIIYS2";
+        readonly registryId: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE";
+        readonly primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X";
     };
 };
 /** Same shape as the owner SDK's signer — wallet-kit compatible. */
@@ -65,6 +67,7 @@ export declare class HolderError extends Error {
     readonly txHash: string | null;
     constructor(message: string, contractId?: string | null, fn?: string | null, code?: number | null, codeName?: string | null, txHash?: string | null);
 }
+export declare function normalizeLabel(value: string): string;
 /** Split and validate `label.namespace`, lowercasing first. Throws
  *  HolderError — @sorandomains/lookup exports the same helper throwing its
  *  own SoranError; import from the package whose errors you handle. */
@@ -110,6 +113,11 @@ export declare class SoranHolder {
     private resolvers;
     private static POINTER_TTL_MS;
     constructor(opts: HolderOptions);
+    /** Atomically update the forward address and complete payment instruction.
+     * Use memo {type:"none"} to explicitly publish a memo-free destination.
+     * The native Resolver updates its own records atomically. This method never
+     * retries as separate set_addr/set_text calls. */
+    setPayment(name: string, destination: PaymentDestination): Promise<Submitted>;
     /**
      * Re-point where YOUR name pays to on its BUILT-IN path (the Registrar's
      * record — what resolvers fall back to when no explicit record is set).
@@ -122,6 +130,9 @@ export declare class SoranHolder {
      * `lookup.resolve()` prefers over the built-in target. Generation-gated:
      * the Resolver verifies you hold the name right now (NotHolder otherwise),
      * and your record stops resolving the moment the name changes hands.
+     * Native set_addr checks the current payment state atomically: ordinary
+     * names and explicit None can change address; required memos require setPayment.
+     * No client preflight is converted into a later setPayment(None).
      */
     setRecord(name: string, address: string): Promise<Submitted>;
     /**
@@ -197,6 +208,8 @@ export declare class SoranHolder {
     registrarOf(namespace: string): Promise<string>;
     /** The namespace's resolver pointer. Cached briefly. */
     resolverOf(namespace: string): Promise<string>;
+    private paymentResolverOf;
+    private assertMemoFree;
     private read;
     private signEnvelope;
     private serialize;

package/dist/index.js

@@ -30,7 +30,9 @@
  * before signing. Operations on one instance are serialized so concurrent
  * calls cannot race the account sequence number.
  */
-import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, } from "@stellar/stellar-sdk";
+import { Account, Address, BASE_FEE, Contract, Keypair, Networks, Operation, StrKey, TransactionBuilder, hash, nativeToScVal, rpc, scValToNative, } from "@stellar/stellar-sdk";
+import { paymentFromNative, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
+export { PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination } from "./payment.js";
 // ---------------------------------------------------------------------------
 // Deployments
 // ---------------------------------------------------------------------------
@@ -39,8 +41,8 @@ export const DEPLOYMENTS = {
     testnet: {
         rpcUrl: "https://soroban-testnet.stellar.org",
         passphrase: Networks.TESTNET,
-        registryId: "CAUEHYVLLNNDZ4H5QWCPBDWEONRI44SI3XYSEACB4U3HYILIVQGQAMNI",
-        primaryId: "CAZMXB6UBXKL4DGC2GUC5VKHIZMF47CIZXZFAZPYLM2RP6ZJZNSIIYS2",
+        registryId: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE",
+        primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X",
     },
 };
 /** A TxSigner over a raw secret key — for scripts and backends. */
@@ -93,6 +95,14 @@ const RESOLVER_ERRORS = {
     10: "InvalidRegistry",
     11: "UpgradeTaintFailed",
     12: "MalformedName",
+    13: "PaymentNotConfigured",
+    14: "MalformedPayment",
+    15: "DestinationMismatch",
+    16: "UnsupportedMemoDestination",
+    17: "InvalidMemo",
+    18: "UsePaymentMethod",
+    19: "PaymentContextMismatch",
+    20: "PaymentUnavailable",
 };
 const PRIMARY_ERRORS = {
     1: "MalformedName",
@@ -140,6 +150,13 @@ function typedError(contractId, fn, raw, names, txHash = null) {
 const LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 // Soroban Symbol constraint — text-record keys live in this alphabet.
 const SYMBOL_RE = /^[A-Za-z0-9_]{1,32}$/;
+export function normalizeLabel(value) {
+    if (typeof value !== "string" || /[^\x00-\x7f]/.test(value))
+        throw new HolderError("label must contain ASCII characters only");
+    const normalized = value.toLowerCase();
+    assertLabel(normalized);
+    return normalized;
+}
 function assertLabel(label) {
     if (label.length < 1 || label.length > 63 || !LABEL_RE.test(label)) {
         throw new HolderError(`invalid label "${label}" — 1-63 chars of a-z, 0-9, and non-edge hyphens`);
@@ -149,6 +166,8 @@ function assertLabel(label) {
  *  HolderError — @sorandomains/lookup exports the same helper throwing its
  *  own SoranError; import from the package whose errors you handle. */
 export function parseName(name) {
+    if (typeof name !== "string" || /[^\x00-\x7f]/.test(name))
+        throw new HolderError("name must contain ASCII characters only");
     const parts = name.toLowerCase().split(".");
     if (parts.length !== 2)
         throw new HolderError(`expected "label.namespace", got "${name}"`);
@@ -221,7 +240,7 @@ export class SoranHolder {
         this.registryId = opts.registryId ?? d.registryId;
         // The preset PrimaryName is anchored to the preset Registry — never let
         // it leak onto a custom registryId, where it could only mis-verify.
-        const presetPrimary = opts.registryId && opts.registryId !== d.registryId ? null : d.primaryId;
+        const presetPrimary = (opts.registryId && opts.registryId !== d.registryId) || (opts.passphrase && opts.passphrase !== d.passphrase) ? null : d.primaryId;
         this.primaryId = opts.primaryId === null ? null : (opts.primaryId ?? presetPrimary ?? null);
         this.signer = opts.signer;
         const t = opts.timeoutSecs ?? 60;
@@ -232,6 +251,27 @@ export class SoranHolder {
         this.fee = opts.fee ?? BASE_FEE;
     }
     // ---- resolution targets --------------------------------------------------
+    /** Atomically update the forward address and complete payment instruction.
+     * Use memo {type:"none"} to explicitly publish a memo-free destination.
+     * The native Resolver updates its own records atomically. This method never
+     * retries as separate set_addr/set_text calls. */
+    async setPayment(name, destination) {
+        const { label, namespace } = parseName(name);
+        let payment;
+        try {
+            payment = validatePaymentDestination(destination);
+        }
+        catch (e) {
+            throw new HolderError(String(e));
+        }
+        const { resolver } = await this.paymentResolverOf(namespace);
+        const holder = await this.signer.publicKey();
+        const r = await this.invoke(resolver, "set_payment", [
+            nativeToScVal(`${label}.${namespace}`, { type: "string" }), addrArg(holder),
+            addrArg(payment.address), paymentMemoToScVal(payment.memo),
+        ], RESOLVER_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
     /**
      * Re-point where YOUR name pays to on its BUILT-IN path (the Registrar's
      * record — what resolvers fall back to when no explicit record is set).
@@ -240,7 +280,7 @@ export class SoranHolder {
      */
     async setAddress(name, address) {
         const { label, namespace } = parseName(name);
-        const registrarId = await this.registrarOf(namespace);
+        const registrarId = await this.assertMemoFree(name);
         const r = await this.invoke(registrarId, "set_address", [labelArg(label), addrArg(address)], REGISTRAR_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
     }
@@ -249,10 +289,13 @@ export class SoranHolder {
      * `lookup.resolve()` prefers over the built-in target. Generation-gated:
      * the Resolver verifies you hold the name right now (NotHolder otherwise),
      * and your record stops resolving the moment the name changes hands.
+     * Native set_addr checks the current payment state atomically: ordinary
+     * names and explicit None can change address; required memos require setPayment.
+     * No client preflight is converted into a later setPayment(None).
      */
     async setRecord(name, address) {
         const { label, namespace } = parseName(name);
-        const resolverId = await this.resolverOf(namespace);
+        const { resolver: resolverId } = await this.paymentResolverOf(namespace);
         const pub = await this.signer.publicKey();
         const r = await this.invoke(resolverId, "set_addr", [bytesArg(nameNode(label, namespace)), addrArg(pub), addrArg(address)], RESOLVER_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
@@ -270,6 +313,8 @@ export class SoranHolder {
      */
     async setText(name, key, value) {
         const { label, namespace } = parseName(name);
+        if (key === "payment")
+            throw new HolderError("payment records must be written atomically with setPayment");
         if (!SYMBOL_RE.test(key)) {
             throw new HolderError(`invalid text-record key "${key}" — 1-32 chars of A-Za-z0-9_`);
         }
@@ -351,8 +396,8 @@ export class SoranHolder {
     }
     /** Remove your reverse record on a namespace's resolver. */
     async clearReverse(namespace) {
-        assertLabel(namespace.toLowerCase());
-        const resolverId = await this.resolverOf(namespace.toLowerCase());
+        assertLabel(normalizeLabel(namespace));
+        const resolverId = await this.resolverOf(normalizeLabel(namespace));
         const pub = await this.signer.publicKey();
         const r = await this.invoke(resolverId, "clear_reverse", [addrArg(pub)], RESOLVER_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
@@ -368,6 +413,8 @@ export class SoranHolder {
             throw new HolderError("setPrimary needs the PrimaryName contract — configure primaryId (the testnet preset supplies one)");
         }
         parseName(name); // validate shape before spending anything
+        if (await this.read(this.primaryId, "registry", []) !== this.registryId)
+            throw new HolderError("Primary is anchored to a different Registry");
         const pub = await this.signer.publicKey();
         const r = await this.invoke(this.primaryId, "set_primary", [addrArg(pub), nativeToScVal(name.toLowerCase(), { type: "string" })], PRIMARY_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
@@ -377,6 +424,8 @@ export class SoranHolder {
         if (!this.primaryId) {
             throw new HolderError("clearPrimary needs the PrimaryName contract — configure primaryId (the testnet preset supplies one)");
         }
+        if (await this.read(this.primaryId, "registry", []) !== this.registryId)
+            throw new HolderError("Primary is anchored to a different Registry");
         const pub = await this.signer.publicKey();
         const r = await this.invoke(this.primaryId, "clear_primary", [addrArg(pub)], PRIMARY_ERRORS);
         return { hash: r.hash, ledger: r.ledger };
@@ -420,7 +469,7 @@ export class SoranHolder {
     // ---- discovery -----------------------------------------------------------
     /** The namespace's Registry-attested Registrar. Cached briefly. */
     async registrarOf(namespace) {
-        namespace = namespace.toLowerCase();
+        namespace = normalizeLabel(namespace);
         assertLabel(namespace);
         const hit = this.registrars.get(namespace);
         if (hit && Date.now() - hit.at < SoranHolder.POINTER_TTL_MS)
@@ -436,7 +485,7 @@ export class SoranHolder {
     }
     /** The namespace's resolver pointer. Cached briefly. */
     async resolverOf(namespace) {
-        namespace = namespace.toLowerCase();
+        namespace = normalizeLabel(namespace);
         assertLabel(namespace);
         const hit = this.resolvers.get(namespace);
         if (hit && Date.now() - hit.at < SoranHolder.POINTER_TTL_MS)
@@ -445,12 +494,58 @@ export class SoranHolder {
             bytesArg(namehash(namespace)),
         ]));
         if (!id) {
-            throw new HolderError(`namespace "${namespace}" has no public resolver — records/reverse are unavailable (setAddress still works where the namespace has an attested Registrar)`, this.registryId, "resolver_of");
+            throw new HolderError(`namespace "${namespace}" has no public resolver — records/reverse and SDK payment-address edits are unavailable`, this.registryId, "resolver_of");
         }
         this.resolvers.set(namespace, { value: id, at: Date.now() });
         return id;
     }
     // ---- internals (same pipeline discipline as @sorandomains/owner) --------
+    async paymentResolverOf(namespace) {
+        const nsNode = namehash(namespace);
+        const args = [bytesArg(nsNode)];
+        const [resolver, registrar] = await Promise.all([
+            this.read(this.registryId, "resolver_of", args),
+            this.read(this.registryId, "registrar_of", args),
+        ]);
+        if (typeof resolver !== "string" || !StrKey.isValidContract(resolver))
+            throw new HolderError("namespace has no valid native payment Resolver");
+        if (typeof registrar !== "string" || !StrKey.isValidContract(registrar))
+            throw new HolderError("namespace has no valid Registrar");
+        const [anchor, authority, version, anchors] = await Promise.all([
+            this.read(resolver, "registry", []),
+            this.read(resolver, "authority", []),
+            this.read(resolver, "payment_version", []),
+            this.read(registrar, "anchors", []),
+        ]);
+        if (anchor !== this.registryId)
+            throw new HolderError("payment Resolver is anchored to a different Registry", resolver, "registry");
+        if (authority !== registrar)
+            throw new HolderError("payment Resolver authority does not match the namespace Registrar", resolver, "authority");
+        if (!Array.isArray(anchors) || anchors.length !== 2 || anchors[0] !== this.registryId ||
+            !(anchors[1] instanceof Uint8Array) || anchors[1].length !== nsNode.length ||
+            !nsNode.every((byte, index) => anchors[1][index] === byte))
+            throw new HolderError("Registrar anchors do not match this Registry and namespace", registrar, "anchors");
+        if (version !== 1)
+            throw new HolderError("unsupported native payment Resolver version", resolver, "payment_version");
+        return { resolver, registrar };
+    }
+    async assertMemoFree(name) {
+        const { label, namespace } = parseName(name);
+        const { resolver, registrar } = await this.paymentResolverOf(namespace);
+        const raw = await this.read(resolver, "resolve_payment", [nativeToScVal(`${label}.${namespace}`, { type: "string" })]);
+        let payment;
+        try {
+            payment = paymentFromNative(raw);
+        }
+        catch (e) {
+            throw new HolderError(`invalid payment result: ${String(e)}`, resolver, "resolve_payment");
+        }
+        if (payment.memo.type !== "none")
+            throw new HolderError("this name requires a memo; use setPayment to update address and memo together");
+        // Registrar-only write below cannot alter a Resolver's explicit addr/memo.
+        // A concurrent set_payment installs its own addr, preserving its memo routing.
+        return registrar;
+    }
     async read(contractId, fn, args) {
         const tx = new TransactionBuilder(new Account(SIM_SOURCE, "0"), {
             fee: BASE_FEE,
@@ -466,7 +561,7 @@ export class SoranHolder {
             throw new HolderError(`${fn}: the on-chain entry is archived (rent lapsed) — any write restores it automatically`, contractId, fn);
         }
         if (!rpc.Api.isSimulationSuccess(sim) || !sim.result?.retval)
-            return null;
+            throw new HolderError(`${fn}: missing simulation return value`, contractId, fn);
         const v = scValToNative(sim.result.retval);
         return v === undefined ? null : v;
     }

package/dist/payment.d.ts

@@ -0,0 +1,28 @@
+/** Payment wire format v1. Kept identical in the independently published lookup
+ * and holder packages; the conformance tests exercise both copies. */
+import { xdr } from "@stellar/stellar-sdk";
+export declare const PAYMENT_RECORD_KEY = "payment";
+export type PaymentMemo = {
+    type: "none";
+} | {
+    type: "id";
+    value: string;
+} | {
+    type: "text";
+    value: string;
+} | {
+    type: "hash";
+    value: string;
+};
+export type PaymentDestination = {
+    address: string;
+    memo: PaymentMemo;
+};
+/** Reject invalid data without normalizing meaningful memo bytes. */
+export declare function validatePaymentDestination(value: unknown): PaymentDestination;
+export declare function encodePaymentRecord(value: PaymentDestination): string;
+/** Empty/missing records are not explicit payment instructions. */
+export declare function parsePaymentRecord(raw: string): PaymentDestination;
+export declare function paymentMemoToScVal(memo: PaymentMemo): xdr.ScVal;
+/** Decode Soroban contract enum values, checking arity and native types. */
+export declare function paymentFromNative(raw: unknown): PaymentDestination;

package/dist/payment.js

@@ -0,0 +1,95 @@
+/** Payment wire format v1. Kept identical in the independently published lookup
+ * and holder packages; the conformance tests exercise both copies. */
+import { StrKey, nativeToScVal, xdr } from "@stellar/stellar-sdk";
+export const PAYMENT_RECORD_KEY = "payment";
+const MAX_U64 = 18446744073709551615n;
+const utf8 = (value) => new TextEncoder().encode(value);
+/** Reject invalid data without normalizing meaningful memo bytes. */
+export function validatePaymentDestination(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid payment destination");
+    const p = value;
+    if (Object.keys(p).sort().join(",") !== "address,memo")
+        throw new Error("unexpected payment fields");
+    if (typeof p.address !== "string" || (!StrKey.isValidEd25519PublicKey(p.address) && !StrKey.isValidContract(p.address)))
+        throw new Error("payment address must be a valid G or C address");
+    if (!p.memo || typeof p.memo !== "object" || Array.isArray(p.memo))
+        throw new Error("invalid memo");
+    const m = p.memo;
+    if (m.type === "none") {
+        if (Object.keys(m).join(",") !== "type")
+            throw new Error("none memo cannot have a value");
+        return { address: p.address, memo: { type: "none" } };
+    }
+    if (!StrKey.isValidEd25519PublicKey(p.address))
+        throw new Error("memos require a classic G address");
+    if (Object.keys(m).sort().join(",") !== "type,value" || typeof m.value !== "string")
+        throw new Error("memo value must be a string");
+    switch (m.type) {
+        case "id":
+            if (!/^(0|[1-9][0-9]{0,19})$/.test(m.value) || BigInt(m.value) > MAX_U64)
+                throw new Error("memo ID must be canonical decimal u64");
+            return { address: p.address, memo: { type: "id", value: m.value } };
+        case "text": {
+            const bytes = utf8(m.value);
+            if (!bytes.length || bytes.length > 28 || new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) !== m.value)
+                throw new Error("memo text must be valid UTF-8, 1–28 bytes");
+            return { address: p.address, memo: { type: "text", value: m.value } };
+        }
+        case "hash":
+            if (!/^[0-9a-f]{64}$/.test(m.value))
+                throw new Error("memo hash must be 32 bytes as lowercase hex");
+            return { address: p.address, memo: { type: "hash", value: m.value } };
+        default: throw new Error("unsupported memo type");
+    }
+}
+export function encodePaymentRecord(value) {
+    const p = validatePaymentDestination(value);
+    return `1|${p.address}|${p.memo.type}|${p.memo.type === "none" ? "" : p.memo.value}`;
+}
+/** Empty/missing records are not explicit payment instructions. */
+export function parsePaymentRecord(raw) {
+    if (typeof raw !== "string" || utf8(raw).length > 128)
+        throw new Error("invalid payment record length");
+    const first = raw.indexOf("|");
+    const second = raw.indexOf("|", first + 1);
+    const third = raw.indexOf("|", second + 1);
+    if (first < 0 || second < 0 || third < 0 || raw.slice(0, first) !== "1")
+        throw new Error("unsupported payment record");
+    const address = raw.slice(first + 1, second);
+    const type = raw.slice(second + 1, third);
+    const value = raw.slice(third + 1);
+    if (type === "none" && value !== "")
+        throw new Error("none memo cannot have a value");
+    return validatePaymentDestination({ address, memo: type === "none" ? { type } : { type, value } });
+}
+export function paymentMemoToScVal(memo) {
+    const symbol = (s) => nativeToScVal(s, { type: "symbol" });
+    switch (memo.type) {
+        case "none": return xdr.ScVal.scvVec([symbol("None")]);
+        case "id": return xdr.ScVal.scvVec([symbol("Id"), nativeToScVal(BigInt(memo.value), { type: "u64" })]);
+        case "text": return xdr.ScVal.scvVec([symbol("Text"), nativeToScVal(memo.value, { type: "string" })]);
+        case "hash": return xdr.ScVal.scvVec([symbol("Hash"), nativeToScVal(Uint8Array.from(memo.value.match(/../g), (b) => parseInt(b, 16)), { type: "bytes" })]);
+    }
+}
+/** Decode Soroban contract enum values, checking arity and native types. */
+export function paymentFromNative(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("invalid payment result");
+    const p = raw;
+    if (Object.keys(p).sort().join(",") !== "address,memo" || !Array.isArray(p.memo))
+        throw new Error("invalid payment result fields");
+    const m = p.memo;
+    let memo;
+    if (m.length === 1 && m[0] === "None")
+        memo = { type: "none" };
+    else if (m.length === 2 && m[0] === "Id" && typeof m[1] === "bigint")
+        memo = { type: "id", value: m[1].toString() };
+    else if (m.length === 2 && m[0] === "Text" && typeof m[1] === "string")
+        memo = { type: "text", value: m[1] };
+    else if (m.length === 2 && m[0] === "Hash" && m[1] instanceof Uint8Array && m[1].length === 32)
+        memo = { type: "hash", value: Array.from(m[1], (b) => b.toString(16).padStart(2, "0")).join("") };
+    else
+        throw new Error("invalid payment memo result");
+    return validatePaymentDestination({ address: p.address, memo });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sorandomains/holder",
-  "version": "0.2.0",
-  "description": "Manage your own Soran name on Stellar — records, profile, reverse, primary, and transfers, signed by your key.",
+  "version": "0.3.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",
   "types": "./dist/index.d.ts",
@@ -18,7 +18,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "tsc",
-    "check:browser": "esbuild dist/index.js --bundle --platform=browser --external:@stellar/stellar-sdk --outfile=browser-check.js --legal-comments=none --log-level=error && node -e \"const fs=require('fs');const s=fs.readFileSync('browser-check.js','utf8');fs.unlinkSync('browser-check.js');if(/\\bBuffer\\b/.test(s)){console.error('FAIL: bare Buffer reference in browser bundle');process.exit(1)}console.log('browser bundle clean')\""
+    "check:browser": "esbuild dist/index.js --bundle --platform=browser --external:@stellar/stellar-sdk --outfile=browser-check.js --legal-comments=none --log-level=error && node -e \"const fs=require('fs');const s=fs.readFileSync('browser-check.js','utf8');fs.unlinkSync('browser-check.js');if(/\\bBuffer\\b/.test(s)){console.error('FAIL: bare Buffer reference in browser bundle');process.exit(1)}console.log('browser bundle clean')\"",
+    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/payment.test.mts test/integration.test.mts"
   },
   "license": "MIT",
   "repository": {