@sorandomains/holder 0.3.1 → 0.4.0

package/README.md

@@ -1,9 +1,14 @@
 # @sorandomains/holder
 
-Version 0.3.1 targets Stellar SDK17 (`>=17 <18`). ASCII names
+> Native muxed release. The testnet deployment below was verified on chain at
+> ledger 4521644 on 5 September 2026 (18:10 UTC). See the
+> [release status](https://docs.soran.domains/reference/release-status) for package and service availability.
+
+
+Version 0.4.0 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.
+Lookup is the read entry point in `@sorandomains/lookup` 0.6.0.
 
 Your Soran name, managed with your own key. The third piece of the SDK
 trilogy: [`@sorandomains/lookup`](https://www.npmjs.com/package/@sorandomains/lookup)
@@ -45,7 +50,12 @@ 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
+only with G addresses. C addresses permit `none`. A full muxed M address also
+requires `none`: its embedded ID belongs to the operation destination, not a
+transaction memo. On native Resolver v2, `setPayment` decodes M and signs
+`set_muxed(name, holder, baseG, exactU64Id)`; G/C uses `set_payment` as before.
+The signed authorization must match the exact selected call, base account and ID.
+A signer returning a different transaction body is rejected before submission. 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.
@@ -53,17 +63,34 @@ 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
+updates an existing valid direct `none` tuple while rejecting muxed routes, 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
+direct `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.
+by installing this SDK. The verified deployment for this release is listed below.
+
+### Publish a muxed destination
+
+```ts
+await me.setPayment("customer420.nova", {
+  address: "MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAAAAAABUTGI4",
+  memo: { type: "none" },
+});
+```
+
+This illustrative M address contains the G account shown in Stellar's examples
+and ID 420. Publish only the actual route supplied by the recipient. No separate
+ID/text/hash memo is permitted. V1 Resolvers cannot store M and fail before signing.
+Use `setPayment` to explicitly replace or remove muxed routing; `setAddress` and
+`setRecord` remain G/C account-address operations. Namespace/name ownership,
+operator and signer addresses remain G/C. Muxed payment destinations do not act
+as separate reverse/Primary identities.
 
 ## What's in the box
 
@@ -115,12 +142,12 @@ supply the matching `primaryId` explicitly.
 
 ## Verified testnet deployment
 
-Verified on 2026-09-05 at ledger 4520986. Network passphrase: `Test SDF Network ; September 2015`.
+Verified on 5 September 2026 at ledger **4521644** (18:10 UTC). Network passphrase: `Test SDF Network ; September 2015`.
 
 | Contract | Address |
 |---|---|
-| Registry | `CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE` |
-| Primary | `CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X` |
+| Registry | `CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H` |
+| Primary | `CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ` |
 
 Mainnet has no deployment preset. Custom networks must supply their own verified
 addresses. Universal Lookup upgrades remain immediately executable; an address

package/dist/index.d.ts

@@ -31,14 +31,14 @@
  * 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";
+export { encodeMuxedAddress, decodeMuxedAddress, 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: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE";
-        readonly primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X";
+        readonly registryId: "CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H";
+        readonly primaryId: "CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ";
     };
 };
 /** Same shape as the owner SDK's signer — wallet-kit compatible. */
@@ -215,6 +215,8 @@ export declare class SoranHolder {
     private serialize;
     private sourceAccount;
     private assertSatisfiableAuth;
+    /** Native payment writes authorize exactly the locally selected destination. */
+    private assertPaymentIntent;
     private invoke;
     private attempt;
     private restore;

package/dist/index.js

@@ -31,8 +31,8 @@
  * calls cannot race the account sequence number.
  */
 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";
+import { decodeMuxedAddress, destinationFromNative, paymentFromNative, paymentMemoToScVal, validatePaymentDestination } from "./payment.js";
+export { encodeMuxedAddress, decodeMuxedAddress, PAYMENT_RECORD_KEY, encodePaymentRecord, parsePaymentRecord, validatePaymentDestination } from "./payment.js";
 // ---------------------------------------------------------------------------
 // Deployments
 // ---------------------------------------------------------------------------
@@ -41,8 +41,8 @@ export const DEPLOYMENTS = {
     testnet: {
         rpcUrl: "https://soroban-testnet.stellar.org",
         passphrase: Networks.TESTNET,
-        registryId: "CDSORANCV3IFF3MKHJ7KI4MKEJOJZFMTDVAZCD5XFOR4WTGNXJJNOKQE",
-        primaryId: "CCSORANOADXKLSW5CUANBW5WZFVCNZ5KZ4KNMIUWOZOES3LXYRUYZ56X",
+        registryId: "CASORANI5CN2NJFEO2MGTRDA35AOEF3D3OCVBWN3FS6B6FXNQ74RTJ7H",
+        primaryId: "CCSORANJZOR5ZYTI4KAW34ESAQFMJAO4NKMTIVOVJOI2VDKCDK3RICXZ",
     },
 };
 /** A TxSigner over a raw secret key — for scripts and backends. */
@@ -103,6 +103,7 @@ const RESOLVER_ERRORS = {
     18: "UsePaymentMethod",
     19: "PaymentContextMismatch",
     20: "PaymentUnavailable",
+    21: "MuxedDestination",
 };
 const PRIMARY_ERRORS = {
     1: "MalformedName",
@@ -200,7 +201,11 @@ function nameNode(label, namespace) {
     return new Uint8Array(hash(concatBytes(namehash(namespace), labelHash)));
 }
 const labelArg = (label) => nativeToScVal(utf8(label), { type: "bytes" });
-const addrArg = (address) => nativeToScVal(address, { type: "address" });
+const addrArg = (address) => {
+    if (!StrKey.isValidEd25519PublicKey(address) && !StrKey.isValidContract(address))
+        throw new HolderError("this account/address operation requires G or C; use setPayment for muxed destinations");
+    return nativeToScVal(address, { type: "address" });
+};
 const bytesArg = (b) => nativeToScVal(b, { type: "bytes" });
 const SIM_SOURCE = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
 /** The standard profile keys shared with @sorandomains/lookup's profile(). */
@@ -264,8 +269,18 @@ export class SoranHolder {
         catch (e) {
             throw new HolderError(String(e));
         }
-        const { resolver } = await this.paymentResolverOf(namespace);
+        const { resolver, version } = await this.paymentResolverOf(namespace);
         const holder = await this.signer.publicKey();
+        if (StrKey.isValidMed25519PublicKey(payment.address)) {
+            if (version !== 2)
+                throw new HolderError("muxed destinations require native Resolver v2", resolver, "payment_version");
+            const muxed = decodeMuxedAddress(payment.address);
+            const r = await this.invoke(resolver, "set_muxed", [
+                nativeToScVal(`${label}.${namespace}`, { type: "string" }), addrArg(holder),
+                addrArg(muxed.account), nativeToScVal(BigInt(muxed.id), { type: "u64" }),
+            ], RESOLVER_ERRORS);
+            return { hash: r.hash, ledger: r.ledger };
+        }
         const r = await this.invoke(resolver, "set_payment", [
             nativeToScVal(`${label}.${namespace}`, { type: "string" }), addrArg(holder),
             addrArg(payment.address), paymentMemoToScVal(payment.memo),
@@ -525,21 +540,26 @@ export class SoranHolder {
             !(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)
+        if (version !== 1 && version !== 2)
             throw new HolderError("unsupported native payment Resolver version", resolver, "payment_version");
-        return { resolver, registrar };
+        if (version === 2 && await this.read(resolver, "destination_version", []) !== 2)
+            throw new HolderError("unsupported Resolver destination version", resolver, "destination_version");
+        return { resolver, registrar, version };
     }
     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" })]);
+        const { resolver, registrar, version } = await this.paymentResolverOf(namespace);
+        const fn = version === 2 ? "resolve_destination" : "resolve_payment";
+        const raw = await this.read(resolver, fn, [nativeToScVal(`${label}.${namespace}`, { type: "string" })]);
         let payment;
         try {
-            payment = paymentFromNative(raw);
+            payment = version === 2 ? destinationFromNative(raw) : paymentFromNative(raw);
         }
         catch (e) {
-            throw new HolderError(`invalid payment result: ${String(e)}`, resolver, "resolve_payment");
+            throw new HolderError(`invalid payment result: ${String(e)}`, resolver, fn);
         }
+        if (StrKey.isValidMed25519PublicKey(payment.address))
+            throw new HolderError("this name has a muxed routing ID; use setPayment to explicitly update its destination");
         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.
@@ -602,6 +622,26 @@ export class SoranHolder {
                 : `${fn}: this operation must be authorized by ${required}, but the signer is ${pub} — use that account's signer`, contractId, fn);
         }
     }
+    /** Native payment writes authorize exactly the locally selected destination. */
+    assertPaymentIntent(prepared, pub, contractId, fn, args) {
+        if (fn !== "set_payment" && fn !== "set_muxed")
+            return;
+        if (prepared.source !== pub || prepared.operations.length !== 1)
+            throw new HolderError("unexpected payment transaction source or operation count", contractId, fn);
+        const op = prepared.operations[0];
+        if (op.type !== "invokeHostFunction" || (op.source !== undefined && op.source !== pub) || op.func.type !== "hostFunctionTypeInvokeContract")
+            throw new HolderError("unexpected payment operation", contractId, fn);
+        const call = op.func.invokeContract;
+        if (Address.fromScAddress(call.contractAddress).toString() !== contractId || call.functionName.toString() !== fn ||
+            call.args.length !== args.length || call.args.some((value, i) => value.toXDR("base64") !== args[i].toXDR("base64")))
+            throw new HolderError("payment operation differs from selected intent", contractId, fn);
+        if (!op.auth || op.auth.length !== 1 || op.auth[0].credentials.type !== "sorobanCredentialsSourceAccount")
+            throw new HolderError("payment requires exactly the source holder authorization", contractId, fn);
+        const root = op.auth[0].rootInvocation;
+        if (root.function.type !== "sorobanAuthorizedFunctionTypeContractFn" || root.subInvocations.length ||
+            root.function.contractFn.toXDR("base64") !== call.toXDR("base64"))
+            throw new HolderError("payment authorization differs from selected intent", contractId, fn);
+    }
     invoke(contractId, fn, args, errNames) {
         return this.serialize(async () => {
             try {
@@ -640,9 +680,12 @@ export class SoranHolder {
         }
         const prepared = rpc.assembleTransaction(tx, sim).build();
         this.assertSatisfiableAuth(prepared, pub, contractId, fn);
+        this.assertPaymentIntent(prepared, pub, contractId, fn, args);
         const txHash = toHex(prepared.hash()); // (SDK17) hash() is Uint8Array
         const signed = await this.signEnvelope(prepared.toXDR());
         const envelope = TransactionBuilder.fromXDR(signed, this.passphrase);
+        if ((fn === "set_payment" || fn === "set_muxed") && toHex(envelope.hash()) !== txHash)
+            throw new HolderError("signer changed the reviewed transaction body", contractId, fn);
         let sent;
         try {
             sent = await this.server.sendTransaction(envelope);

package/dist/payment.d.ts

@@ -1,4 +1,4 @@
-/** Payment wire format v1. Kept identical in the independently published lookup
+/** Direct v1 and muxed v2 payment records. 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";
@@ -26,3 +26,12 @@ 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;
+/** Decode a full muxed destination without treating its operation ID as a memo. */
+export declare function decodeMuxedAddress(address: string): {
+    account: string;
+    id: string;
+};
+/** Encode only canonical G + exact decimal u64; numbers are never accepted. */
+export declare function encodeMuxedAddress(account: string, id: string): string;
+/** Strict additive on-chain destination enum; v1 payment structs stay separate. */
+export declare function destinationFromNative(raw: unknown): PaymentDestination;

package/dist/payment.js

@@ -1,4 +1,4 @@
-/** Payment wire format v1. Kept identical in the independently published lookup
+/** Direct v1 and muxed v2 payment records. 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";
@@ -11,14 +11,16 @@ export function validatePaymentDestination(value) {
     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 (typeof p.address !== "string" || (!StrKey.isValidEd25519PublicKey(p.address) && !StrKey.isValidContract(p.address) && !StrKey.isValidMed25519PublicKey(p.address)))
+        throw new Error("payment address must be a valid G, C or M 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");
+        if (StrKey.isValidMed25519PublicKey(p.address))
+            decodeMuxedAddress(p.address);
         return { address: p.address, memo: { type: "none" } };
     }
     if (!StrKey.isValidEd25519PublicKey(p.address))
@@ -45,6 +47,10 @@ export function validatePaymentDestination(value) {
 }
 export function encodePaymentRecord(value) {
     const p = validatePaymentDestination(value);
+    if (StrKey.isValidMed25519PublicKey(p.address)) {
+        const muxed = decodeMuxedAddress(p.address);
+        return `2|${muxed.account}|muxed|${muxed.id}`;
+    }
     return `1|${p.address}|${p.memo.type}|${p.memo.type === "none" ? "" : p.memo.value}`;
 }
 /** Empty/missing records are not explicit payment instructions. */
@@ -54,11 +60,16 @@ export function parsePaymentRecord(raw) {
     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")
+    if (first < 0 || second < 0 || third < 0)
         throw new Error("unsupported payment record");
+    const version = raw.slice(0, first);
     const address = raw.slice(first + 1, second);
     const type = raw.slice(second + 1, third);
     const value = raw.slice(third + 1);
+    if (version === "2" && type === "muxed")
+        return { address: encodeMuxedAddress(address, value), memo: { type: "none" } };
+    if (version !== "1" || (!StrKey.isValidEd25519PublicKey(address) && !StrKey.isValidContract(address)))
+        throw new Error("unsupported payment record");
     if (type === "none" && value !== "")
         throw new Error("none memo cannot have a value");
     return validatePaymentDestination({ address, memo: type === "none" ? { type } : { type, value } });
@@ -79,6 +90,8 @@ export function paymentFromNative(raw) {
     const p = raw;
     if (Object.keys(p).sort().join(",") !== "address,memo" || !Array.isArray(p.memo))
         throw new Error("invalid payment result fields");
+    if (typeof p.address !== "string" || (!StrKey.isValidEd25519PublicKey(p.address) && !StrKey.isValidContract(p.address)))
+        throw new Error("direct payment must contain a G or C address");
     const m = p.memo;
     let memo;
     if (m.length === 1 && m[0] === "None")
@@ -93,3 +106,43 @@ export function paymentFromNative(raw) {
         throw new Error("invalid payment memo result");
     return validatePaymentDestination({ address: p.address, memo });
 }
+/** Decode a full muxed destination without treating its operation ID as a memo. */
+export function decodeMuxedAddress(address) {
+    if (typeof address !== "string" || !StrKey.isValidMed25519PublicKey(address))
+        throw new Error("invalid muxed M address");
+    const raw = StrKey.decodeMed25519PublicKey(address);
+    if (raw.length !== 40 || StrKey.encodeMed25519PublicKey(raw) !== address)
+        throw new Error("noncanonical muxed address");
+    let id = 0n;
+    for (const byte of raw.subarray(32))
+        id = (id << 8n) | BigInt(byte);
+    return { account: StrKey.encodeEd25519PublicKey(raw.subarray(0, 32)), id: id.toString() };
+}
+/** Encode only canonical G + exact decimal u64; numbers are never accepted. */
+export function encodeMuxedAddress(account, id) {
+    if (typeof account !== "string" || !StrKey.isValidEd25519PublicKey(account))
+        throw new Error("muxed base must be a G account");
+    if (typeof id !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(id) || BigInt(id) > MAX_U64)
+        throw new Error("muxed ID must be canonical decimal u64");
+    const raw = new Uint8Array(40);
+    raw.set(StrKey.decodeEd25519PublicKey(account));
+    let value = BigInt(id);
+    for (let i = 39; i >= 32; i--) {
+        raw[i] = Number(value & 255n);
+        value >>= 8n;
+    }
+    return StrKey.encodeMed25519PublicKey(raw);
+}
+/** Strict additive on-chain destination enum; v1 payment structs stay separate. */
+export function destinationFromNative(raw) {
+    if (!Array.isArray(raw) || raw.length !== 2)
+        throw new Error("invalid destination enum");
+    if (raw[0] === "Direct")
+        return paymentFromNative(raw[1]);
+    if (raw[0] !== "Muxed" || !raw[1] || typeof raw[1] !== "object" || Array.isArray(raw[1]))
+        throw new Error("invalid destination variant");
+    const value = raw[1];
+    if (Object.keys(value).sort().join(",") !== "account,id" || typeof value.account !== "string" || typeof value.id !== "bigint")
+        throw new Error("invalid muxed destination fields");
+    return { address: encodeMuxedAddress(value.account, value.id.toString()), memo: { type: "none" } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorandomains/holder",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -19,7 +19,7 @@
     "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')\"",
-    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/payment.test.mts test/integration.test.mts"
+    "test": "node --import tsx test/decode-failure.test.mts && node --import tsx --test test/payment.test.mts test/integration.test.mts test/muxed.test.mts"
   },
   "license": "MIT",
   "repository": {