@sorandomains/holder 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soran (SoranDomains)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @sorandomains/holder
+
+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)
+runs a namespace — this package is for the person who **holds** a name.
+
+```bash
+npm install @sorandomains/holder @stellar/stellar-sdk
+```
+
+```ts
+import { SoranHolder, keypairSigner } from "@sorandomains/holder";
+
+const me = new SoranHolder({ signer: keypairSigner(process.env.MY_SECRET!) });
+
+await me.setReverse("alice.nova");   // your address shows as alice.nova
+await me.setPrimary("alice.nova");   // ...across every namespace
+await me.setProfile("alice.nova", {  // the standard keys every wallet reads
+  org: "Alice Co",
+  url: "https://alice.dev",
+});
+```
+
+## 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) |
+| `setAddress` | Re-point the built-in (Registrar) resolution target |
+| `setText` / `setProfile` | Publish text records; `setProfile` writes the standard `PROFILE_KEYS` (one transaction per key) |
+| `setReverse` / `clearReverse` | Claim your address→name reverse record — the contract refuses names that don't already resolve to you (`ForwardMismatch`) |
+| `setPrimary` / `clearPrimary` | Your one cross-namespace display name, re-verified on chain at every read |
+| `proposeNameTransfer` / `acceptNameTransfer` / `cancelNameTransfer` | Two-step, accept-to-move name transfers (policy-gated) |
+| `pendingNameTransfer` | Read the pending proposal |
+
+Everything is holder-authorized **on chain** — the Resolver checks you hold
+the name right now, reverse and primary claims are authorized by the address
+itself, and transfers move only when the recipient accepts. No Soran account,
+no hosted API in the path.
+
+## Signing
+
+Same `TxSigner` contract as the owner SDK — `keypairSigner(secret)` for
+scripts, or wrap a browser wallet:
+
+```ts
+const me = new SoranHolder({
+  signer: {
+    publicKey: () => walletAddress,
+    signTransaction: (xdr, opts) => kit.signTransaction(xdr, opts),
+  },
+});
+```
+
+Calls are simulated before signing, so contract rejections surface as typed
+`HolderError`s (`code`, `codeName` — e.g. `NotHolder`, `ForwardMismatch`,
+`NotTransferable`) before any fee is spent; failures that reached the network
+carry `txHash`.
+
+Works in browsers, Node, and workers out of the box — zero Node built-ins of
+its own (enforced in CI), with `@stellar/stellar-sdk` as the only peer
+dependency.
+
+Docs: <https://github.com/SoranDomains/docs> · License: MIT

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @sorandomains/holder — the write-side SDK for people who HOLD a Soran name.
+ *
+ * The third persona: `@sorandomains/lookup` reads names, `@sorandomains/owner`
+ * runs a namespace — this package manages YOUR name with YOUR key:
+ *
+ *   import { SoranHolder, keypairSigner } from "@sorandomains/holder";
+ *
+ *   const me = new SoranHolder({ signer: keypairSigner(process.env.MY_SECRET!) });
+ *   await me.setReverse("alice.nova");        // addresses show as alice.nova
+ *   await me.setPrimary("alice.nova");        // ...across every namespace
+ *   await me.setProfile("alice.nova", { url: "https://alice.dev", org: "Alice Co" });
+ *
+ * TRUST MODEL. Every operation is a transaction your own key signs against
+ * the contracts over any Soroban RPC — no Soran account, no hosted API in
+ * the path. All powers here are HOLDER-authorized on chain: the Resolver
+ * checks you hold the name (generation-gated) before accepting records, the
+ * reverse and primary claims are authorized by the ADDRESS itself, and name
+ * transfers move only when the recipient accepts. Namespace-owner powers
+ * (issue, reclaim, renew, permanence) live in `@sorandomains/owner` and this
+ * package deliberately cannot exercise them.
+ *
+ * SIGNING. Same `TxSigner` contract as the owner SDK: `keypairSigner(secret)`
+ * for scripts, or wrap a browser wallet:
+ *
+ *   { publicKey: () => walletAddress, signTransaction: (x, o) => kit.signTransaction(x, o) }
+ *
+ * Each call is simulated first (typed contract errors before any fee), the
+ * envelope is handed to your signer, and unsatisfiable auth is refused
+ * before signing. Operations on one instance are serialized so concurrent
+ * calls cannot race the account sequence number.
+ */
+/** 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";
+    };
+};
+/** Same shape as the owner SDK's signer — wallet-kit compatible. */
+export type TxSigner = {
+    publicKey(): string | Promise<string>;
+    signTransaction(xdrBase64: string, opts: {
+        networkPassphrase: string;
+    }): Promise<string | {
+        signedTxXdr: string;
+    }>;
+};
+/** A TxSigner over a raw secret key — for scripts and backends. */
+export declare function keypairSigner(secret: string): TxSigner;
+/**
+ * A failed holder operation. `code`/`codeName` carry the contract's typed
+ * error (e.g. 3/"NotHolder" from the Resolver, 5/"ForwardMismatch" on a
+ * reverse claim for a name that doesn't point back at you); null for
+ * transport failures. `txHash` is set when a transaction reached the network
+ * — always re-check a hash before retrying.
+ */
+export declare class HolderError extends Error {
+    readonly contractId: string | null;
+    readonly fn: string | null;
+    readonly code: number | null;
+    readonly codeName: string | null;
+    readonly txHash: string | null;
+    constructor(message: string, contractId?: string | null, fn?: string | null, code?: number | null, codeName?: string | null, txHash?: string | null);
+}
+/** 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. */
+export declare function parseName(name: string): {
+    label: string;
+    namespace: string;
+};
+export type Submitted = {
+    hash: string;
+    ledger: number;
+};
+/** The standard profile keys shared with @sorandomains/lookup's profile(). */
+export declare const PROFILE_KEYS: readonly ["org", "url", "email", "description", "avatar", "location", "twitter", "github"];
+export type HolderOptions = {
+    /** Signs every transaction: the name HOLDER's account (or, for
+     *  `acceptNameTransfer`, the proposed new holder's). */
+    signer: TxSigner;
+    /** Named deployment preset; defaults to "testnet". Override the individual
+     *  fields below as a SET for custom deployments. */
+    network?: keyof typeof DEPLOYMENTS;
+    rpcUrl?: string;
+    passphrase?: string;
+    registryId?: string;
+    /** PrimaryName contract; the preset supplies one. `null` disables
+     *  setPrimary/clearPrimary. */
+    primaryId?: string | null;
+    allowHttp?: boolean;
+    /** Transaction time bound, seconds (integer 1-300, default 60). */
+    timeoutSecs?: number;
+    /** Base fee bid, stroops (default 100; resource fees are added on top). */
+    fee?: string;
+};
+export declare class SoranHolder {
+    private server;
+    private passphrase;
+    private registryId;
+    private primaryId;
+    private signer;
+    private timeoutSecs;
+    private fee;
+    private queue;
+    private registrars;
+    private resolvers;
+    private static POINTER_TTL_MS;
+    constructor(opts: HolderOptions);
+    /**
+     * 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).
+     * Holder-authorized, live names only; deliberately never blocked by
+     * namespace permanence — where your own name resolves is always yours.
+     */
+    setAddress(name: string, address: string): Promise<Submitted>;
+    /**
+     * Set YOUR name's explicit record on the namespace resolver — the answer
+     * `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.
+     */
+    setRecord(name: string, address: string): Promise<Submitted>;
+    /**
+     * A text record on YOUR name (`url`, `avatar`, any Symbol-legal key ≤32
+     * chars of [A-Za-z0-9_]). Use {@link PROFILE_KEYS} for records every
+     * Soran-aware wallet knows to look for.
+     *
+     * PERMANENCE NOTE: the contract stores text records overwrite-only — there
+     * is no on-chain delete. The retraction convention is an EMPTY VALUE
+     * ({@link clearText}): the entry remains on chain (empty), and standard
+     * readers (lookup's `profile()`) treat empty as unset. Publish
+     * accordingly — treat every value as permanent-ish public data.
+     */
+    setText(name: string, key: string, value: string): Promise<Submitted>;
+    /**
+     * Retract a text record by overwriting it with the empty string — the
+     * chain keeps the (empty) entry, and standard readers treat empty as
+     * unset. There is no true on-chain delete for text records.
+     */
+    clearText(name: string, key: string): Promise<Submitted>;
+    /**
+     * Publish several profile records in one call. Soroban allows one contract
+     * invocation per transaction, so this signs and submits ONE TRANSACTION
+     * PER KEY, sequentially, and returns the per-key results. On a mid-batch
+     * failure it throws with the already-set keys named in the message —
+     * records already written stay written (they are individually valid).
+     */
+    setProfile(name: string, profile: Record<string, string>): Promise<Array<Submitted & {
+        key: string;
+    }>>;
+    /**
+     * Claim `name` as YOUR ADDRESS's reverse record on its namespace resolver
+     * — what `lookup.reverseLookup` finds. Authorized by the address itself,
+     * and the contract enforces that the name's forward record already
+     * resolves to you (ForwardMismatch otherwise): a reverse claim on a name
+     * that doesn't point back at you is spoofing, and the chain refuses it.
+     */
+    setReverse(name: string): Promise<Submitted>;
+    /** Remove your reverse record on a namespace's resolver. */
+    clearReverse(namespace: string): Promise<Submitted>;
+    /**
+     * Declare `name` as YOUR one cross-namespace primary display name. The
+     * PrimaryName contract verifies the claim against the namespace resolver
+     * on every read, so a primary can never outlive the name it points at.
+     * Requires a reverse record first in practice (NotDisplayName otherwise).
+     */
+    setPrimary(name: string): Promise<Submitted>;
+    /** Withdraw your primary-name declaration. */
+    clearPrimary(): Promise<Submitted>;
+    /**
+     * Offer YOUR name to `to`. Two-step by contract design: nothing moves
+     * until the recipient accepts, so a typo'd address cannot burn the name.
+     * Policy-gated (NotTransferable on namespaces that forbid it) and live
+     * names only.
+     */
+    proposeNameTransfer(name: string, to: string): Promise<Submitted>;
+    /** Accept a name offered to you. Signer must be the PROPOSED holder. */
+    acceptNameTransfer(name: string): Promise<Submitted>;
+    /** Withdraw a pending transfer of your name. */
+    cancelNameTransfer(name: string): Promise<Submitted>;
+    /** The pending transfer proposal on a name, or null. */
+    pendingNameTransfer(name: string): Promise<{
+        from: string;
+        to: string;
+        expiresAt: bigint;
+    } | null>;
+    /** The namespace's Registry-attested Registrar. Cached briefly. */
+    registrarOf(namespace: string): Promise<string>;
+    /** The namespace's resolver pointer. Cached briefly. */
+    resolverOf(namespace: string): Promise<string>;
+    private read;
+    private signEnvelope;
+    private serialize;
+    private sourceAccount;
+    private assertSatisfiableAuth;
+    private invoke;
+    private attempt;
+    private restore;
+    private confirm;
+    private decodeFailure;
+}

package/dist/index.js

@@ -0,0 +1,632 @@
+/**
+ * @sorandomains/holder — the write-side SDK for people who HOLD a Soran name.
+ *
+ * The third persona: `@sorandomains/lookup` reads names, `@sorandomains/owner`
+ * runs a namespace — this package manages YOUR name with YOUR key:
+ *
+ *   import { SoranHolder, keypairSigner } from "@sorandomains/holder";
+ *
+ *   const me = new SoranHolder({ signer: keypairSigner(process.env.MY_SECRET!) });
+ *   await me.setReverse("alice.nova");        // addresses show as alice.nova
+ *   await me.setPrimary("alice.nova");        // ...across every namespace
+ *   await me.setProfile("alice.nova", { url: "https://alice.dev", org: "Alice Co" });
+ *
+ * TRUST MODEL. Every operation is a transaction your own key signs against
+ * the contracts over any Soroban RPC — no Soran account, no hosted API in
+ * the path. All powers here are HOLDER-authorized on chain: the Resolver
+ * checks you hold the name (generation-gated) before accepting records, the
+ * reverse and primary claims are authorized by the ADDRESS itself, and name
+ * transfers move only when the recipient accepts. Namespace-owner powers
+ * (issue, reclaim, renew, permanence) live in `@sorandomains/owner` and this
+ * package deliberately cannot exercise them.
+ *
+ * SIGNING. Same `TxSigner` contract as the owner SDK: `keypairSigner(secret)`
+ * for scripts, or wrap a browser wallet:
+ *
+ *   { publicKey: () => walletAddress, signTransaction: (x, o) => kit.signTransaction(x, o) }
+ *
+ * Each call is simulated first (typed contract errors before any fee), the
+ * envelope is handed to your signer, and unsatisfiable auth is refused
+ * 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, xdr, } from "@stellar/stellar-sdk";
+// ---------------------------------------------------------------------------
+// Deployments
+// ---------------------------------------------------------------------------
+/** Known public deployments. Pass explicit options for anything else. */
+export const DEPLOYMENTS = {
+    testnet: {
+        rpcUrl: "https://soroban-testnet.stellar.org",
+        passphrase: Networks.TESTNET,
+        registryId: "CAUEHYVLLNNDZ4H5QWCPBDWEONRI44SI3XYSEACB4U3HYILIVQGQAMNI",
+        primaryId: "CAZMXB6UBXKL4DGC2GUC5VKHIZMF47CIZXZFAZPYLM2RP6ZJZNSIIYS2",
+    },
+};
+/** A TxSigner over a raw secret key — for scripts and backends. */
+export function keypairSigner(secret) {
+    const kp = Keypair.fromSecret(secret);
+    return {
+        publicKey: () => kp.publicKey(),
+        signTransaction: async (xdrBase64, { networkPassphrase }) => {
+            const tx = TransactionBuilder.fromXDR(xdrBase64, networkPassphrase);
+            tx.sign(kp);
+            return tx.toXDR();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+const REGISTRAR_ERRORS = {
+    1: "AlreadyInitialized",
+    2: "NotInitialized",
+    3: "NameTaken",
+    4: "NameNotFound",
+    5: "NotReclaimable",
+    6: "NotTransferable",
+    7: "AlreadyPermanent",
+    8: "BatchTooLarge",
+    9: "NotNamespaceOwner",
+    10: "BadLabel",
+    11: "PermanentName",
+    12: "FiniteTermPolicy",
+    13: "PermanentlyLocked",
+    14: "NameExpired",
+    15: "NoPendingTransfer",
+    16: "TransferExpired",
+    17: "StaleTransfer",
+    18: "InvalidPolicy",
+    19: "ExpiryOverflow",
+    20: "InvalidRegistry",
+};
+const RESOLVER_ERRORS = {
+    1: "AlreadyInitialized",
+    2: "NotInitialized",
+    3: "NotHolder",
+    4: "NameInactive",
+    5: "ForwardMismatch",
+    6: "Frozen",
+    7: "InvalidAuthority",
+    8: "ProvenanceMismatch",
+    9: "ProvenanceAlreadyBound",
+    10: "InvalidRegistry",
+    11: "UpgradeTaintFailed",
+    12: "MalformedName",
+};
+const PRIMARY_ERRORS = {
+    1: "MalformedName",
+    2: "NoResolver",
+    3: "NotDisplayName",
+    4: "ResolverUnavailable",
+    5: "InvalidRegistry",
+};
+/**
+ * A failed holder operation. `code`/`codeName` carry the contract's typed
+ * error (e.g. 3/"NotHolder" from the Resolver, 5/"ForwardMismatch" on a
+ * reverse claim for a name that doesn't point back at you); null for
+ * transport failures. `txHash` is set when a transaction reached the network
+ * — always re-check a hash before retrying.
+ */
+export class HolderError extends Error {
+    contractId;
+    fn;
+    code;
+    codeName;
+    txHash;
+    constructor(message, contractId = null, fn = null, code = null, codeName = null, txHash = null) {
+        super(message);
+        this.contractId = contractId;
+        this.fn = fn;
+        this.code = code;
+        this.codeName = codeName;
+        this.txHash = txHash;
+        this.name = "HolderError";
+    }
+}
+function parseContractCode(message) {
+    const m = /Error\(Contract, #(\d+)\)/.exec(message);
+    return m ? Number(m[1]) : null;
+}
+function typedError(contractId, fn, raw, names, txHash = null) {
+    const code = parseContractCode(raw);
+    const codeName = code !== null ? (names[code] ?? null) : null;
+    const label = codeName ? ` (${codeName})` : "";
+    return new HolderError(`${fn} failed${code !== null ? `: contract error #${code}${label}` : `: ${raw}`}`, contractId, fn, code, codeName, txHash);
+}
+// ---------------------------------------------------------------------------
+// Hashing + arguments (mirror the on-chain scheme exactly)
+// ---------------------------------------------------------------------------
+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}$/;
+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`);
+    }
+}
+/** 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. */
+export function parseName(name) {
+    const parts = name.toLowerCase().split(".");
+    if (parts.length !== 2)
+        throw new HolderError(`expected "label.namespace", got "${name}"`);
+    const [label, namespace] = parts;
+    assertLabel(label);
+    assertLabel(namespace);
+    return { label, namespace };
+}
+const utf8 = (str) => new TextEncoder().encode(str);
+function concatBytes(...parts) {
+    const out = new Uint8Array(parts.reduce((n, part) => n + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function namehash(namespace) {
+    const labelHash = new Uint8Array(hash(utf8(namespace)));
+    return new Uint8Array(hash(concatBytes(new Uint8Array(32), labelHash)));
+}
+function nameNode(label, namespace) {
+    const labelHash = new Uint8Array(hash(utf8(label)));
+    return new Uint8Array(hash(concatBytes(namehash(namespace), labelHash)));
+}
+const labelArg = (label) => nativeToScVal(utf8(label), { type: "bytes" });
+const addrArg = (address) => 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(). */
+export const PROFILE_KEYS = [
+    "org",
+    "url",
+    "email",
+    "description",
+    "avatar",
+    "location",
+    "twitter",
+    "github",
+];
+// ---------------------------------------------------------------------------
+// The client
+// ---------------------------------------------------------------------------
+export class SoranHolder {
+    server;
+    passphrase;
+    registryId;
+    primaryId;
+    signer;
+    timeoutSecs;
+    fee;
+    queue = Promise.resolve();
+    registrars = new Map();
+    resolvers = new Map();
+    static POINTER_TTL_MS = 30_000;
+    constructor(opts) {
+        if (!opts?.signer)
+            throw new HolderError("HolderOptions.signer is required");
+        const d = DEPLOYMENTS[opts.network ?? "testnet"];
+        if (!d)
+            throw new HolderError(`unknown network "${opts.network}"`);
+        this.server = new rpc.Server(opts.rpcUrl ?? d.rpcUrl, { allowHttp: opts.allowHttp ?? false });
+        this.passphrase = opts.passphrase ?? d.passphrase;
+        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;
+        this.primaryId = opts.primaryId === null ? null : (opts.primaryId ?? presetPrimary ?? null);
+        this.signer = opts.signer;
+        const t = opts.timeoutSecs ?? 60;
+        if (!Number.isInteger(t) || t < 1 || t > 300) {
+            throw new HolderError(`timeoutSecs must be an integer between 1 and 300 (got ${t})`);
+        }
+        this.timeoutSecs = t;
+        this.fee = opts.fee ?? BASE_FEE;
+    }
+    // ---- resolution targets --------------------------------------------------
+    /**
+     * 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).
+     * Holder-authorized, live names only; deliberately never blocked by
+     * namespace permanence — where your own name resolves is always yours.
+     */
+    async setAddress(name, address) {
+        const { label, namespace } = parseName(name);
+        const registrarId = await this.registrarOf(namespace);
+        const r = await this.invoke(registrarId, "set_address", [labelArg(label), addrArg(address)], REGISTRAR_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /**
+     * Set YOUR name's explicit record on the namespace resolver — the answer
+     * `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.
+     */
+    async setRecord(name, address) {
+        const { label, namespace } = parseName(name);
+        const resolverId = await this.resolverOf(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 };
+    }
+    /**
+     * A text record on YOUR name (`url`, `avatar`, any Symbol-legal key ≤32
+     * chars of [A-Za-z0-9_]). Use {@link PROFILE_KEYS} for records every
+     * Soran-aware wallet knows to look for.
+     *
+     * PERMANENCE NOTE: the contract stores text records overwrite-only — there
+     * is no on-chain delete. The retraction convention is an EMPTY VALUE
+     * ({@link clearText}): the entry remains on chain (empty), and standard
+     * readers (lookup's `profile()`) treat empty as unset. Publish
+     * accordingly — treat every value as permanent-ish public data.
+     */
+    async setText(name, key, value) {
+        const { label, namespace } = parseName(name);
+        if (!SYMBOL_RE.test(key)) {
+            throw new HolderError(`invalid text-record key "${key}" — 1-32 chars of A-Za-z0-9_`);
+        }
+        const resolverId = await this.resolverOf(namespace);
+        const pub = await this.signer.publicKey();
+        const r = await this.invoke(resolverId, "set_text", [
+            bytesArg(nameNode(label, namespace)),
+            addrArg(pub),
+            nativeToScVal(key, { type: "symbol" }),
+            nativeToScVal(value, { type: "string" }),
+        ], RESOLVER_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /**
+     * Retract a text record by overwriting it with the empty string — the
+     * chain keeps the (empty) entry, and standard readers treat empty as
+     * unset. There is no true on-chain delete for text records.
+     */
+    async clearText(name, key) {
+        return this.setText(name, key, "");
+    }
+    /**
+     * Publish several profile records in one call. Soroban allows one contract
+     * invocation per transaction, so this signs and submits ONE TRANSACTION
+     * PER KEY, sequentially, and returns the per-key results. On a mid-batch
+     * failure it throws with the already-set keys named in the message —
+     * records already written stay written (they are individually valid).
+     */
+    async setProfile(name, profile) {
+        const entries = Object.entries(profile);
+        if (entries.length === 0)
+            throw new HolderError("setProfile: empty profile");
+        for (const [key] of entries) {
+            if (!SYMBOL_RE.test(key)) {
+                throw new HolderError(`invalid text-record key "${key}" — 1-32 chars of A-Za-z0-9_`);
+            }
+        }
+        const done = [];
+        for (const [key, value] of entries) {
+            try {
+                const r = await this.setText(name, key, value);
+                done.push({ key, ...r });
+            }
+            catch (e) {
+                const set = done.map((d) => d.key).join(", ") || "none";
+                throw new HolderError(`setProfile stopped at "${key}" (${e instanceof Error ? e.message : String(e)}); keys already set: ${set}`, e instanceof HolderError ? e.contractId : null, e instanceof HolderError && e.fn ? e.fn : "set_text", e instanceof HolderError ? e.code : null, e instanceof HolderError ? e.codeName : null, e instanceof HolderError ? e.txHash : null);
+            }
+        }
+        return done;
+    }
+    // ---- reverse + primary ---------------------------------------------------
+    /**
+     * Claim `name` as YOUR ADDRESS's reverse record on its namespace resolver
+     * — what `lookup.reverseLookup` finds. Authorized by the address itself,
+     * and the contract enforces that the name's forward record already
+     * resolves to you (ForwardMismatch otherwise): a reverse claim on a name
+     * that doesn't point back at you is spoofing, and the chain refuses it.
+     */
+    async setReverse(name) {
+        const { namespace } = parseName(name);
+        const resolverId = await this.resolverOf(namespace);
+        const pub = await this.signer.publicKey();
+        const r = await this.invoke(resolverId, "set_reverse", [addrArg(pub), nativeToScVal(name.toLowerCase(), { type: "string" })], RESOLVER_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /** Remove your reverse record on a namespace's resolver. */
+    async clearReverse(namespace) {
+        assertLabel(namespace.toLowerCase());
+        const resolverId = await this.resolverOf(namespace.toLowerCase());
+        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 };
+    }
+    /**
+     * Declare `name` as YOUR one cross-namespace primary display name. The
+     * PrimaryName contract verifies the claim against the namespace resolver
+     * on every read, so a primary can never outlive the name it points at.
+     * Requires a reverse record first in practice (NotDisplayName otherwise).
+     */
+    async setPrimary(name) {
+        if (!this.primaryId) {
+            throw new HolderError("setPrimary needs the PrimaryName contract — configure primaryId (the testnet preset supplies one)");
+        }
+        parseName(name); // validate shape before spending anything
+        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 };
+    }
+    /** Withdraw your primary-name declaration. */
+    async clearPrimary() {
+        if (!this.primaryId) {
+            throw new HolderError("clearPrimary needs the PrimaryName contract — configure primaryId (the testnet preset supplies one)");
+        }
+        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 };
+    }
+    // ---- name transfers ------------------------------------------------------
+    /**
+     * Offer YOUR name to `to`. Two-step by contract design: nothing moves
+     * until the recipient accepts, so a typo'd address cannot burn the name.
+     * Policy-gated (NotTransferable on namespaces that forbid it) and live
+     * names only.
+     */
+    async proposeNameTransfer(name, to) {
+        const { label, namespace } = parseName(name);
+        const registrarId = await this.registrarOf(namespace);
+        const r = await this.invoke(registrarId, "propose_transfer", [labelArg(label), addrArg(to)], REGISTRAR_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /** Accept a name offered to you. Signer must be the PROPOSED holder. */
+    async acceptNameTransfer(name) {
+        const { label, namespace } = parseName(name);
+        const registrarId = await this.registrarOf(namespace);
+        const r = await this.invoke(registrarId, "accept_transfer", [labelArg(label)], REGISTRAR_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /** Withdraw a pending transfer of your name. */
+    async cancelNameTransfer(name) {
+        const { label, namespace } = parseName(name);
+        const registrarId = await this.registrarOf(namespace);
+        const r = await this.invoke(registrarId, "cancel_transfer", [labelArg(label)], REGISTRAR_ERRORS);
+        return { hash: r.hash, ledger: r.ledger };
+    }
+    /** The pending transfer proposal on a name, or null. */
+    async pendingNameTransfer(name) {
+        const { label, namespace } = parseName(name);
+        const registrarId = await this.registrarOf(namespace);
+        const raw = (await this.read(registrarId, "pending_transfer", [labelArg(label)]));
+        if (!raw)
+            return null;
+        return { from: String(raw.from), to: String(raw.to), expiresAt: BigInt(raw.expires) };
+    }
+    // ---- discovery -----------------------------------------------------------
+    /** The namespace's Registry-attested Registrar. Cached briefly. */
+    async registrarOf(namespace) {
+        namespace = namespace.toLowerCase();
+        assertLabel(namespace);
+        const hit = this.registrars.get(namespace);
+        if (hit && Date.now() - hit.at < SoranHolder.POINTER_TTL_MS)
+            return hit.value;
+        const id = (await this.read(this.registryId, "registrar_of", [
+            bytesArg(namehash(namespace)),
+        ]));
+        if (!id) {
+            throw new HolderError(`namespace "${namespace}" has no attested Registrar on this Registry`, this.registryId, "registrar_of");
+        }
+        this.registrars.set(namespace, { value: id, at: Date.now() });
+        return id;
+    }
+    /** The namespace's resolver pointer. Cached briefly. */
+    async resolverOf(namespace) {
+        namespace = namespace.toLowerCase();
+        assertLabel(namespace);
+        const hit = this.resolvers.get(namespace);
+        if (hit && Date.now() - hit.at < SoranHolder.POINTER_TTL_MS)
+            return hit.value;
+        const id = (await this.read(this.registryId, "resolver_of", [
+            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");
+        }
+        this.resolvers.set(namespace, { value: id, at: Date.now() });
+        return id;
+    }
+    // ---- internals (same pipeline discipline as @sorandomains/owner) --------
+    async read(contractId, fn, args) {
+        const tx = new TransactionBuilder(new Account(SIM_SOURCE, "0"), {
+            fee: BASE_FEE,
+            networkPassphrase: this.passphrase,
+        })
+            .addOperation(new Contract(contractId).call(fn, ...args))
+            .setTimeout(30)
+            .build();
+        const sim = await this.server.simulateTransaction(tx);
+        if (rpc.Api.isSimulationError(sim))
+            throw typedError(contractId, fn, sim.error, {});
+        if (rpc.Api.isSimulationRestore(sim)) {
+            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;
+        const v = scValToNative(sim.result.retval);
+        return v === undefined ? null : v;
+    }
+    async signEnvelope(xdrBase64) {
+        const signed = await this.signer.signTransaction(xdrBase64, {
+            networkPassphrase: this.passphrase,
+        });
+        return typeof signed === "string" ? signed : signed.signedTxXdr;
+    }
+    serialize(work) {
+        const run = this.queue.then(work, work);
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async sourceAccount(pub, fn) {
+        try {
+            return await this.server.getAccount(pub);
+        }
+        catch {
+            throw new HolderError(`${fn}: signer account ${pub} does not exist on this network — fund it (testnet: friendbot) before writing`, null, fn);
+        }
+    }
+    assertSatisfiableAuth(prepared, pub, contractId, fn) {
+        const op = prepared.operations[0];
+        for (const entry of op?.auth ?? []) {
+            const cred = entry.credentials();
+            if (cred.switch() !== xdr.SorobanCredentialsType.sorobanCredentialsAddress())
+                continue;
+            let required;
+            try {
+                required = Address.fromScAddress(cred.address().address()).toString();
+            }
+            catch {
+                continue;
+            }
+            throw new HolderError(required === pub
+                ? `${fn}: the network requires a separate auth-entry signature from ${pub}, which this SDK does not produce yet — make the authorized account the transaction source`
+                : `${fn}: this operation must be authorized by ${required}, but the signer is ${pub} — use that account's signer`, contractId, fn);
+        }
+    }
+    invoke(contractId, fn, args, errNames) {
+        return this.serialize(async () => {
+            try {
+                return await this.attempt(contractId, fn, args, errNames);
+            }
+            catch (e) {
+                if (/txBadSeq|bad_seq/i.test(String(e))) {
+                    return await this.attempt(contractId, fn, args, errNames);
+                }
+                throw e;
+            }
+        });
+    }
+    async attempt(contractId, fn, args, errNames) {
+        const pub = await this.signer.publicKey();
+        const contract = new Contract(contractId);
+        const build = (source) => new TransactionBuilder(source, { fee: this.fee, networkPassphrase: this.passphrase })
+            .addOperation(contract.call(fn, ...args))
+            .setTimeout(this.timeoutSecs)
+            .build();
+        let tx = build(await this.sourceAccount(pub, fn));
+        let sim = await this.server.simulateTransaction(tx);
+        for (let round = 0; rpc.Api.isSimulationRestore(sim); round++) {
+            if (round >= 2) {
+                throw new HolderError(`${fn}: entries still need restoring after ${round} restore transactions — retry later`, contractId, fn);
+            }
+            await this.restore(sim, pub);
+            tx = build(await this.sourceAccount(pub, fn));
+            sim = await this.server.simulateTransaction(tx);
+        }
+        if (rpc.Api.isSimulationError(sim)) {
+            throw typedError(contractId, fn, sim.error, errNames);
+        }
+        const prepared = rpc.assembleTransaction(tx, sim).build();
+        this.assertSatisfiableAuth(prepared, pub, contractId, fn);
+        const txHash = prepared.hash().toString("hex");
+        const signed = await this.signEnvelope(prepared.toXDR());
+        const envelope = TransactionBuilder.fromXDR(signed, this.passphrase);
+        let sent;
+        try {
+            sent = await this.server.sendTransaction(envelope);
+        }
+        catch (e) {
+            throw new HolderError(`${fn}: submit failed after signing (${String(e)}) — transaction ${txHash} may or may not have reached the network; check the hash before retrying`, contractId, fn, null, null, txHash);
+        }
+        if (sent.status === "ERROR") {
+            throw new HolderError(`${fn}: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, contractId, fn, null, null, txHash);
+        }
+        if (sent.status === "TRY_AGAIN_LATER") {
+            throw new HolderError(`${fn}: the network did not accept the transaction (TRY_AGAIN_LATER) — it was NOT queued; safe to retry shortly`, contractId, fn, null, null, txHash);
+        }
+        try {
+            const { ledger, returnValue } = await this.confirm(txHash, contractId, fn, errNames);
+            return { hash: txHash, ledger, returnValue };
+        }
+        catch (e) {
+            if (e instanceof HolderError)
+                throw e;
+            throw new HolderError(`${fn}: confirmation interrupted (${String(e)}) — transaction ${txHash} may still be included; check the hash before retrying`, contractId, fn, null, null, txHash);
+        }
+    }
+    async restore(sim, pub) {
+        const pre = sim.restorePreamble;
+        const fee = (Number(this.fee) + Number(pre.minResourceFee)).toString();
+        const tx = new TransactionBuilder(await this.sourceAccount(pub, "restore_footprint"), {
+            fee,
+            networkPassphrase: this.passphrase,
+        })
+            .setSorobanData(pre.transactionData.build())
+            .addOperation(Operation.restoreFootprint({}))
+            .setTimeout(this.timeoutSecs)
+            .build();
+        const signed = await this.signEnvelope(tx.toXDR());
+        const sent = await this.server.sendTransaction(TransactionBuilder.fromXDR(signed, this.passphrase));
+        if (sent.status === "ERROR") {
+            throw new HolderError(`restore_footprint: submit rejected: ${JSON.stringify(sent.errorResult ?? sent.status)}`, null, "restore_footprint", null, null, sent.hash);
+        }
+        await this.confirm(sent.hash, "", "restore_footprint", {});
+    }
+    async confirm(hash_, contractId, fn, errNames) {
+        const tries = this.timeoutSecs + 5;
+        let got = await this.server.getTransaction(hash_);
+        for (let i = 0; i < tries && got.status === "NOT_FOUND"; i++) {
+            await new Promise((r) => setTimeout(r, 1000));
+            got = await this.server.getTransaction(hash_);
+        }
+        if (got.status === "NOT_FOUND") {
+            throw new HolderError(`${fn}: transaction ${hash_} not confirmed within ${tries}s — it may still be included; check the hash before retrying`, contractId || null, fn, null, null, hash_);
+        }
+        if (got.status !== "SUCCESS") {
+            throw this.decodeFailure(got, contractId, fn, errNames, hash_);
+        }
+        let returnValue = null;
+        try {
+            if (got.returnValue)
+                returnValue = scValToNative(got.returnValue);
+        }
+        catch {
+            /* void return */
+        }
+        return { ledger: got.ledger, returnValue };
+    }
+    decodeFailure(got, contractId, fn, errNames, hash_) {
+        let code = null;
+        try {
+            const meta = got.resultMetaXdr;
+            const diags = got.diagnosticEventsXdr ??
+                (meta && meta.switch() === 3
+                    ? (meta.v3().sorobanMeta()?.diagnosticEvents() ?? [])
+                    : meta && meta.switch() === 4
+                        ? meta.v4().diagnosticEvents()
+                        : []);
+            outer: for (const d of diags) {
+                const body = d.event().body().v0();
+                for (const v of [...body.topics(), body.data()]) {
+                    if (v.switch() === xdr.ScValType.scvError()) {
+                        const err = v.error();
+                        if (err.switch() === xdr.ScErrorType.sceContract()) {
+                            code = err.contractCode();
+                            break outer;
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            /* diagnostics unavailable */
+        }
+        let resultCode = `tx status ${got.status}`;
+        try {
+            resultCode = got.resultXdr?.result().switch().name ?? resultCode;
+        }
+        catch {
+            /* keep plain status */
+        }
+        if (code !== null) {
+            const codeName = errNames[code] ?? null;
+            return new HolderError(`${fn} failed at inclusion: contract error #${code}${codeName ? ` (${codeName})` : ""} (${resultCode})`, contractId, fn, code, codeName, hash_);
+        }
+        return new HolderError(`${fn} failed at inclusion (${resultCode})`, contractId, fn, null, null, hash_);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sorandomains/holder",
+  "version": "0.1.0",
+  "description": "Manage your own Soran name on Stellar — records, profile, reverse, primary, and transfers, signed by your key.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "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')\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SoranDomains/sdk.git",
+    "directory": "packages/holder"
+  },
+  "homepage": "https://github.com/SoranDomains/sdk/tree/main/packages/holder#readme",
+  "bugs": {
+    "url": "https://github.com/SoranDomains/sdk/issues"
+  },
+  "keywords": [
+    "stellar",
+    "soroban",
+    "soran",
+    "name-service",
+    "profile",
+    "reverse-lookup"
+  ],
+  "peerDependencies": {
+    "@stellar/stellar-sdk": ">=13 <17"
+  },
+  "devDependencies": {
+    "@stellar/stellar-sdk": "^16.2.0",
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}