@hsuite/smart-engines-cli 1.2.1 → 1.4.2

package/dist/commands/subscribe.js

@@ -6,160 +6,548 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.subscribeCommand = void 0;
 exports.runSubscribe = runSubscribe;
 /**
- * `hsuite subscribe` — Mint a subscription NFT against the validator's
- * `/api/v3/subscription/*` surface.
+ * `hsuite subscribe` — Onboard a smart-app the CANONICAL, MINT-FIRST way:
+ * create the smart-app's DKG ENTITY first, mint the builder subscription NFT
+ * ON THAT ENTITY's id, and land it on the dev wallet — so `1 smart-app =
+ * 1 DKG entity = 1 NFT`, ACTIVE from mint.
  *
- * Flow (per docs/superpowers/specs/2026-05-27-developer-subscription-gating.md §3.5):
- *   1. Read XRPL_ADDRESS + XRPL_SEED from env (written by `hsuite init`).
- *   2. POST /api/v3/subscription/request → server creates subscription doc.
- *      - `free_testnet`: server auto-activates + mints. CLI polls /status
- *         until NFT serial is set.
- *      - paid tier: server returns depositInstructions. CLI displays them,
- *         polls /status every 5s until status: 'PENDING_MINT' (deposit
- *         confirmed), then POSTs /mint to flip ACTIVE.
- *   3. Verify NFT serial lands on the wallet via GET /status.
- *   4. Write SUBSCRIPTION_APP_ID + SUBSCRIPTION_NFT_SERIAL to .env.
+ * ## Why this creates the entity (the mint-first re-architecture)
+ *
+ * `subscribe` used to mint the subscription NFT on a throwaway random
+ * `app-${uuid}` that was NEVER a DKG entity, while `hsuite deploy` separately
+ * minted a FRESH entity (+ a SECOND subscription) at `init` time. Paid id ≠
+ * deployed id → the deployed app stayed PENDING, redeploys forked, and two
+ * NFTs were minted. Now `subscribe` creates the durable DKG entity up front and
+ * uses its `entityId` as the subscription appId end-to-end; `deploy` reuses
+ * that same id (it no longer creates anything). Output:
+ * `SUBSCRIPTION_APP_ID == DEPLOYED_APP_ID == DKG entityId`, ACTIVE, ONE NFT.
+ *
+ * Full flow:
+ *   1. Read XRPL_ADDRESS + XRPL_SEED from env (written by `hsuite init`) and the
+ *      validator URL.
+ *   2. Web3-auth against the validator (challenge → sign → bearer). The
+ *      subscription + create routes are session-guarded. (Auth routes have NO
+ *      /api prefix.)
+ *   3. POST /api/v3/smart-apps (createApp) — run the per-entity DKG ceremony
+ *      to derive the canonical `entityId` AND create the (paid, pending-deposit)
+ *      subscription in the same in-process flow. The response carries
+ *      `{ appId: entityId, depositInstructions, subscriptionId }`. THIS replaces
+ *      the old random-id + standalone `subscription/request`. From here the
+ *      `entityId` is THE appId for everything downstream.
+ *   4. Ensure deposit instructions: the createApp response normally carries them.
+ *      If a node deferred deposit-account creation, fall back to the idempotent
+ *      POST /api/v3/subscription/request { appId: entityId, … } (same retry/503
+ *      semantics, returns the SAME subscription's deposit instructions — no
+ *      second subscription, no second deposit wallet).
+ *   5. Render the deposit instructions.
+ *   6. AUTO-PAY the deposit from the dev wallet over the XRPL testnet (HST
+ *      Payment with a SendMax covering the 0.25% transfer fee). `--no-autopay`
+ *      skips this and prints instructions for manual (XUMM) payment.
+ *   7. Poll GET /api/v3/subscription/status/:entityId until the deposit is
+ *      confirmed and ready to mint (status in { deposit_confirmed, pending_mint,
+ *      minting, active }; the real confirmed status is `deposit_confirmed`).
+ *   8. POST /api/v3/subscription/mint/:entityId — activates the subscription +
+ *      flips the SmartApp doc PENDING_SUBSCRIPTION → ACTIVE (via `activateApp`,
+ *      gated on the deposit-backed NFT mint) and kicks off the async NFT mint.
+ *   9. Poll /status until `subscriptionNftSerial` is set OR `chainNfts.xrpl.nftId`
+ *      is present (the NFT mints asynchronously via the mint subscriber).
+ *  10. Accept the brokered NFT sell offer so it lands on the dev wallet.
+ *  11. Verify account_nfts, then write SUBSCRIPTION_APP_ID + APP_ID +
+ *      SUBSCRIPTION_NFT_SERIAL (= entityId) to the env file.
  */
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
-const crypto_1 = require("crypto");
 const env_1 = require("../_lib/env");
 const subscription_client_1 = require("../_lib/subscription-client");
 const subscription_env_1 = require("../_lib/subscription-env");
-const VALID_TIERS = ['free_testnet', 'starter', 'professional', 'enterprise'];
+/** Public XRPL testnet websocket endpoint (matches `hsuite init` + faucet). */
+const XRPL_TESTNET_WSS = 'wss://s.altnet.rippletest.net:51233';
+/**
+ * Multiplier applied to the deposit amount for the Payment `SendMax` so the
+ * 0.25% HST transfer fee is covered (0.25% → ×1.0025; we use ×1.004 for a small
+ * safety margin against rounding).
+ */
+const HST_TRANSFER_FEE_MULTIPLIER = 1.004;
+// Every subscription is paid + NFT-backed (the validator's createSubscription
+// rejects any unknown tier on the public path). The four-tier ladder is
+// `builder → growth → scale → enterprise`; `builder` ($49/mo) is the entry tier.
+const VALID_TIERS = ['builder', 'growth', 'scale', 'enterprise'];
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function defaultXrplClientFactory(wss) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Client } = require('xrpl');
+    return new Client(wss);
+}
+function defaultWalletSignFactory(seed) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Wallet } = require('xrpl');
+    const wallet = Wallet.fromSeed(seed);
+    return (tx) => wallet.sign(tx).tx_blob;
+}
 /**
  * Pure orchestration body — exported for unit tests.
  *
- * Returns the appId + NFT serial (when minted) so callers can persist them.
- * Throws on every error path; the command-level action wraps this and
- * exits the process.
+ * Returns the appId + NFT serial (once minted + accepted) so callers can
+ * persist them. Throws on every hard-error path; the command-level action wraps
+ * this and exits the process.
  */
 async function runSubscribe(opts) {
     const env = (0, env_1.readEnv)(opts.env);
-    const { address } = (0, subscription_env_1.requireXrplCreds)(env);
+    const { address, seed } = (0, subscription_env_1.requireXrplCreds)(env);
     const tier = opts.tier;
     if (!VALID_TIERS.includes(tier)) {
         throw new Error(`unknown tier "${opts.tier}". Valid: ${VALID_TIERS.join(', ')}`);
     }
-    const selectedNetworks = opts.networks
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    if (selectedNetworks.length === 0) {
-        throw new Error('At least one network required (e.g. --networks xrpl)');
-    }
     const baseUrl = (0, subscription_env_1.requireValidatorUrl)(env, { gateway: opts.gateway });
-    const client = (opts.clientFactory ?? ((b) => new subscription_client_1.SubscriptionClient({ baseUrl: b })))(baseUrl);
+    const client = (opts.clientFactory ??
+        ((b) => new subscription_client_1.SubscriptionClient({ baseUrl: b, auth: { chain: 'xrpl', address, seed } })))(baseUrl);
+    // The subscription routes are session-guarded: obtain a validator bearer
+    // session by signing a challenge before any call.
+    await client.authenticate();
     const sleep = opts.sleep ?? defaultSleep;
-    const appId = opts.appId ??
-        env.get('SUBSCRIPTION_APP_ID') ??
-        `app-${(0, crypto_1.randomUUID)().slice(0, 8)}`;
     const appName = opts.appName ?? env.get('APP_NAME') ?? 'Smart App Showcase';
-    // Step 1: POST /request
-    let requestResp;
-    try {
-        requestResp = await client.request({
-            appId,
-            developerAccountId: address,
-            chain: 'xrpl',
-            appName,
-            selectedTier: tier,
-            selectedNetworks,
-        });
-    }
-    catch (err) {
-        throw new Error(`subscription request failed: ${err.message}`);
+    // A DNS-safe name is required by the create DTO (the entityId is derived by
+    // the DKG ceremony, not from this name; the name is the display label).
+    const dnsName = toDnsSafeName(appName);
+    // Step 1: CREATE THE DKG ENTITY (mint-first). POST /api/v3/smart-apps runs
+    // the per-entity DKG ceremony → canonical `entityId`, AND creates the (paid,
+    // pending-deposit) subscription on that same id in one in-process flow. The
+    // `entityId` it returns is THE appId for the subscription + deposit + mint +
+    // every later deploy. This REPLACES the old throwaway `app-${uuid}` + a
+    // standalone `subscription/request`.
+    //
+    // An explicit --app-id / a previously-written SUBSCRIPTION_APP_ID short-
+    // circuits create (re-running `subscribe` to finish paying/minting an
+    // already-created entity), so a resumed run does not fork a second entity.
+    const preexistingAppId = opts.appId ?? env.get('SUBSCRIPTION_APP_ID');
+    let appId;
+    let created;
+    if (preexistingAppId) {
+        appId = preexistingAppId;
     }
-    if (!requestResp.success) {
-        throw new Error(`subscription request rejected: ${requestResp.message ?? 'unknown error'}`);
+    else {
+        try {
+            created = await client.createApp({
+                name: appName,
+                services: ['database'],
+                // `config.appId` is a placeholder — SmartAppService.create overwrites it
+                // with the DKG `entityId`. acceptedLoginChains must be non-empty.
+                config: {
+                    appId: dnsName,
+                    acceptedLoginChains: ['xrpl'],
+                    acceptedPaymentTokens: [],
+                },
+                tier,
+                networks: ['testnet'],
+                // validatorRules omitted (optional) — the factory synthesizes the
+                // canonical security-first default for the standard deployment path.
+            });
+        }
+        catch (err) {
+            throw new Error(`smart-app entity creation failed: ${err.message}`);
+        }
+        if (!created.appId) {
+            throw new Error('create returned no appId (DKG entityId) — server contract violation');
+        }
+        appId = created.appId;
     }
-    const status = await (async () => {
-        // Step 2a: free_testnet path — server auto-activates. Poll until NFT serial set.
-        if (tier === 'free_testnet') {
-            return pollStatus(client, appId, sleep, opts, (s) => Boolean(s.subscriptionNftSerial));
+    // Step 2: obtain the HST deposit instructions for THIS entityId. createApp
+    // normally returns them (the subscription was created alongside the entity).
+    // If a node deferred deposit-account creation, fall back to the idempotent
+    // POST /api/v3/subscription/request { appId: entityId } — it carries the
+    // retry/503 semantics and returns the SAME subscription's deposit
+    // instructions (no second subscription, no second deposit wallet).
+    let requested;
+    let deposit = created?.depositInstructions;
+    let subscriptionId = created?.subscriptionId;
+    if (!deposit) {
+        try {
+            requested = await client.request({
+                appId,
+                developerAccountId: address,
+                chain: 'xrpl',
+                appName,
+                selectedTier: tier,
+                selectedNetworks: ['xrpl'],
+            });
+        }
+        catch (err) {
+            throw new Error(`subscription request failed: ${err.message}`);
         }
-        // Step 2b: paid tier — display deposit instructions + poll until PENDING_MINT.
-        if (!requestResp.depositInstructions) {
-            throw new Error('paid tier returned no depositInstructions — server contract violation');
+        deposit = requested.depositInstructions;
+        subscriptionId = subscriptionId ?? requested.subscriptionId;
+    }
+    if (!deposit) {
+        // No deposit instructions. On a RESUME of an already-active subscription
+        // (--app-id / SUBSCRIPTION_APP_ID, deposit long paid, NFT possibly minted),
+        // this is EXPECTED — not a contract violation. Check /status: if the
+        // subscription is already provisioned, skip deposit+pay+mint and go straight
+        // to accepting the brokered sell offer so the NFT lands on the dev wallet.
+        if (preexistingAppId) {
+            const existing = await client.status(appId);
+            const alreadyProvisioned = Boolean(existing.subscriptionNftSerial) ||
+                Boolean(existing.chainNfts?.xrpl?.nftId) ||
+                (existing.status ?? '').toLowerCase() === 'active';
+            if (alreadyProvisioned) {
+                // NFT coordinates can lag the 'active' status by a few ledgers.
+                const status = existing.subscriptionNftSerial || existing.chainNfts?.xrpl?.nftId
+                    ? existing
+                    : await pollStatus(client, appId, sleep, opts, (s) => Boolean(s.subscriptionNftSerial) || Boolean(s.chainNfts?.xrpl?.nftId), opts.nftPollAttempts ?? 24);
+                const nftAccepted = await acceptSubscriptionNft(opts, address, seed, sleep, status);
+                return {
+                    appId,
+                    subscriptionId: status.subscriptionId ?? subscriptionId,
+                    nftSerial: status.subscriptionNftSerial,
+                    tier,
+                    status: status.status,
+                    depositPaid: true,
+                    nftAccepted,
+                };
+            }
         }
-        renderDepositInstructions(requestResp.depositInstructions, tier);
-        await pollStatus(client, appId, sleep, opts, (s) => isPendingMint(s.status));
-        // Step 3: POST /mint
+        throw new Error('no depositInstructions for the created entity — server contract violation');
+    }
+    renderDepositInstructions(deposit, tier, appId);
+    // Step 3: auto-pay the deposit from the dev wallet (unless --no-autopay).
+    if (opts.noAutopay) {
+        renderManualPaymentHint(deposit);
+        return {
+            appId,
+            subscriptionId,
+            tier,
+            status: requested?.status ?? 'pending_deposit',
+            depositPaid: false,
+            nftAccepted: false,
+        };
+    }
+    await payDeposit(opts, address, seed, deposit);
+    // Step 3: poll /status until the deposit is confirmed and ready to mint.
+    await pollStatus(client, appId, sleep, opts, (s) => isReadyToMint(s.status));
+    // Step 4: POST /mint — kicks off the async NFT mint. Tolerate a non-2xx here
+    // (the server may still be finalizing); the status poll below is the source of
+    // truth for whether the NFT actually minted.
+    try {
         const mintResp = await client.mint(appId);
         if (!mintResp.success) {
-            throw new Error('mint failed (server returned success=false)');
+            console.log(chalk_1.default.yellow('  mint reported success=false — continuing to poll status'));
         }
-        // Step 4: poll until NFT serial is set.
-        return pollStatus(client, appId, sleep, opts, (s) => Boolean(s.subscriptionNftSerial));
-    })();
+    }
+    catch (err) {
+        console.log(chalk_1.default.yellow(`  mint HTTP error (tolerated, will poll status): ${err.message}`));
+    }
+    // Step 5: poll until the NFT serial is set OR the minted NFT coordinates
+    // appear on /status (the NFT mints asynchronously via the mint subscriber).
+    // The 2-of-3 issuer MPC mint + offer creation take ~15-25s, so poll ~24×5s
+    // (~120s) before giving up. Bounded by attempt count (not wall-clock) so the
+    // injected-`sleep` unit tests stay fast.
+    const status = await pollStatus(client, appId, sleep, opts, (s) => Boolean(s.subscriptionNftSerial) ||
+        Boolean(s.chainNfts?.xrpl?.nftId) ||
+        (s.status ?? '').toLowerCase() === 'active', opts.nftPollAttempts ?? 24);
+    // Step 6: accept the brokered sell offer so the NFT lands on the dev wallet.
+    const nftAccepted = await acceptSubscriptionNft(opts, address, seed, sleep, status);
     return {
         appId,
-        subscriptionId: status.subscriptionId,
+        subscriptionId: status.subscriptionId ?? subscriptionId,
         nftSerial: status.subscriptionNftSerial,
         tier,
         status: status.status,
+        depositPaid: true,
+        nftAccepted,
     };
 }
-function isPendingMint(status) {
+/**
+ * Coerce a display name into the DNS-safe shape the validator's create DTO
+ * requires (lowercase alphanumeric + hyphens, no leading/trailing hyphen, ≤63
+ * chars). The DKG `entityId` is derived by the ceremony — this only sanitises
+ * the placeholder `config.appId` + name field so a human-readable APP_NAME like
+ * "Smart App Showcase" doesn't 400 the create.
+ */
+function toDnsSafeName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63)
+        .replace(/-+$/g, '');
+    return slug.length > 0 ? slug : 'smart-app';
+}
+/**
+ * Pay the HST deposit from the dev wallet over the XRPL testnet.
+ *
+ * The HST issuer is resolved from the deposit account's HST trust line: query
+ * `account_lines` on the deposit `walletAddress`, find the line with currency
+ * 'HST', and use its `account` (the trust-line peer) as the issuer. We then
+ * submit a `Payment` of `amount` whole HST with a `SendMax` of
+ * `amount × 1.004` to cover the 0.25% HST transfer fee.
+ *
+ * Requires tesSUCCESS. Always disconnects.
+ */
+async function payDeposit(opts, address, seed, deposit) {
+    if (deposit.chain !== 'xrpl') {
+        throw new Error(`auto-pay only supports XRPL deposits (got chain=${deposit.chain}); ` +
+            'use --no-autopay and pay manually');
+    }
+    const walletSign = (opts.walletSignFactory ?? defaultWalletSignFactory)(seed);
+    const client = (opts.xrplClientFactory ?? defaultXrplClientFactory)(XRPL_TESTNET_WSS);
+    await client.connect();
+    try {
+        const issuer = await resolveHstIssuer(client, deposit.walletAddress);
+        const value = deposit.amount;
+        const sendMax = (Number(value) * HST_TRANSFER_FEE_MULTIPLIER).toFixed(6);
+        const tx = {
+            TransactionType: 'Payment',
+            Account: address,
+            Destination: deposit.walletAddress,
+            Amount: { currency: 'HST', issuer, value },
+            SendMax: { currency: 'HST', issuer, value: sendMax },
+        };
+        const prepared = await client.autofill(tx);
+        const txBlob = walletSign(prepared);
+        const result = await client.submitAndWait(txBlob);
+        const code = result.result?.meta?.TransactionResult;
+        if (code !== 'tesSUCCESS') {
+            throw new Error(`deposit Payment failed: ${code ?? 'unknown result'}`);
+        }
+    }
+    finally {
+        await client.disconnect();
+    }
+}
+/**
+ * Resolve the HST issuer from the deposit account's trust lines.
+ *
+ * The deposit account holds an HST trust line whose peer (`account`) is the HST
+ * issuer. We query `account_lines` on the deposit wallet and return the peer of
+ * the line whose `currency` is 'HST'.
+ */
+async function resolveHstIssuer(client, depositWallet) {
+    const res = await client.request({ command: 'account_lines', account: depositWallet });
+    const lines = res.result?.lines ?? [];
+    const hst = lines.find((l) => l?.currency === 'HST');
+    if (!hst?.account) {
+        throw new Error(`could not resolve HST issuer: deposit account ${depositWallet} has no HST trust line`);
+    }
+    return hst.account;
+}
+/**
+ * Ready-to-mint check.
+ *
+ * The server's ready-to-mint state is `deposit_confirmed`
+ * (`activateSubscription` refuses to mint unless status === DEPOSIT_CONFIRMED).
+ * We treat any of {deposit_confirmed, pending_mint, minting, active} as ready so
+ * the flow is robust to a server that already advanced past the gate by the time
+ * we poll. NOTE: `pending_mint` is NOT the confirmed status — `deposit_confirmed`
+ * is.
+ */
+function isReadyToMint(status) {
     if (!status)
         return false;
-    // SubscriptionStatus enum values from libs/multi-chain-core. Accept both
-    // canonical `pending_mint` and an already-active state (server may skip
-    // straight to ACTIVE if it's already minted by the time we poll).
     const s = status.toLowerCase();
-    return s === 'pending_mint' || s === 'active' || s === 'minting';
+    return (s === 'deposit_confirmed' ||
+        s === 'pending_mint' ||
+        s === 'minting' ||
+        s === 'active');
 }
-async function pollStatus(client, appId, sleep, opts, done) {
+async function pollStatus(client, appId, sleep, opts, done, maxAttempts) {
     const interval = opts.pollIntervalMs ?? 5000;
     const timeout = opts.pollTimeoutMs ?? 5 * 60 * 1000;
     const deadline = Date.now() + timeout;
     // First tick immediately so tests that prime a single response don't have
-    // to wait the full 5s.
+    // to wait the full 5s. Stops on the `done` predicate, an attempt cap, or the
+    // wall-clock deadline — whichever comes first.
+    let attempt = 0;
     while (true) {
         const status = await client.status(appId);
         if (done(status))
             return status;
+        attempt += 1;
+        if (maxAttempts !== undefined && attempt >= maxAttempts) {
+            throw new Error(`timed out waiting for subscription status for ${appId} after ${attempt} polls`);
+        }
         if (Date.now() > deadline) {
             throw new Error(`timed out waiting for subscription status for ${appId} after ${timeout}ms`);
         }
         await sleep(interval);
     }
 }
-function renderDepositInstructions(d, tier) {
-    const xummDeeplink = buildXummDeeplink(d);
+/**
+ * Accept the subscription NFT sell offer on the dev wallet.
+ *
+ * The mint creates an XRPL `NFTokenCreateOffer` (SELL, Amount '0',
+ * Destination = dev wallet) owned by the issuer — so the NFT does NOT
+ * auto-land. The dev wallet must submit `NFTokenAcceptOffer`.
+ *
+ * Strategy:
+ *   a. Poll the dev wallet's `account_nfts` first — if the NFT is already there
+ *      (already accepted on a prior run, or auto-delivered), we're done.
+ *   b. Else, if `chainNfts.xrpl.nftId` is known, query `nft_sell_offers` for
+ *      that NFTokenID and accept the offer whose `destination` is the dev wallet
+ *      (else the first offer). Exact + issuer-free.
+ *   c. Else fall back to the issuer-side scan: enumerate the issuer's
+ *      `account_objects` (type `nft_offer`) and accept the sell offer whose
+ *      `Destination` is the dev wallet. Issuer comes from
+ *      `chainNfts.xrpl.issuerAddress`, with --nft-issuer / SUBSCRIPTION_NFT_ISSUER
+ *      as an optional override.
+ *   d. With no nftId, no issuer, and no NFT yet, return false (the mint still
+ *      succeeded; only the on-wallet delivery is deferred).
+ *
+ * Retries up to 10× (≈50s at the 5s default) because the brokered sell offer
+ * needs a few ledgers to appear on-ledger after the 2-of-3 issuer MPC mint —
+ * re-querying BOTH `nft_sell_offers{nft_id}` and the issuer-side
+ * `account_objects` fallback on each attempt. Returns true when the NFT is
+ * confirmed on the dev wallet.
+ */
+async function acceptSubscriptionNft(opts, address, seed, sleep, status) {
+    const xrplNft = status?.chainNfts?.xrpl;
+    const nftId = xrplNft?.nftId;
+    // Explicit override wins; otherwise use the issuer the status now exposes.
+    const issuer = opts.nftIssuer ?? xrplNft?.issuerAddress;
+    const client = (opts.xrplClientFactory ?? defaultXrplClientFactory)(XRPL_TESTNET_WSS);
+    const walletSign = (opts.walletSignFactory ?? defaultWalletSignFactory)(seed);
+    const attempts = opts.acceptAttempts ?? 10;
+    const retryMs = opts.acceptRetryMs ?? opts.pollIntervalMs ?? 5000;
+    await client.connect();
+    try {
+        for (let i = 0; i < attempts; i++) {
+            // (a) Is the SPECIFIC subscription NFT already on the wallet? Only a
+            //     positive NFTokenID match counts — never "holds some NFT". With no
+            //     nftId known yet, fall through to resolve + accept the offer.
+            if (nftId && (await walletHasNft(client, address, nftId)))
+                return true;
+            // (b)/(c) Resolve the sell-offer index: prefer the NFTokenID-keyed lookup
+            // (exact, issuer-free), fall back to the issuer-side account_objects scan.
+            let offerIndex;
+            if (nftId) {
+                offerIndex = await findSellOfferIndexByNftId(client, nftId, address);
+            }
+            if (!offerIndex && issuer) {
+                offerIndex = await findSellOfferIndex(client, issuer, address);
+            }
+            if (offerIndex) {
+                const tx = {
+                    TransactionType: 'NFTokenAcceptOffer',
+                    Account: address,
+                    NFTokenSellOffer: offerIndex,
+                };
+                const prepared = await client.autofill(tx);
+                const txBlob = walletSign(prepared);
+                const result = await client.submitAndWait(txBlob);
+                const code = result.result?.meta?.TransactionResult;
+                if (code !== 'tesSUCCESS') {
+                    throw new Error(`NFTokenAcceptOffer failed: ${code ?? 'unknown result'}`);
+                }
+                // The tesSUCCESS above already proves the accept; confirm the specific
+                // NFT landed when its id is known, else trust the successful submit.
+                if (!nftId || (await walletHasNft(client, address, nftId)))
+                    return true;
+            }
+            if (i < attempts - 1)
+                await sleep(retryMs);
+        }
+        // Final check after the loop: only the specific NFT counts.
+        return nftId ? await walletHasNft(client, address, nftId) : false;
+    }
+    finally {
+        await client.disconnect();
+    }
+}
+/**
+ * True if the account holds the SPECIFIC subscription NFT (`nftId`).
+ *
+ * Must be NFTokenID-specific: the dev wallet routinely holds other NFTs (prior
+ * or retired subscriptions, unrelated collectibles), so a "holds ANY NFT" check
+ * would falsely report the current subscription NFT as already accepted and
+ * skip the `NFTokenAcceptOffer` entirely — the offer would sit open forever.
+ */
+async function walletHasNft(client, account, nftId) {
+    const res = await client.request({ command: 'account_nfts', account });
+    const nfts = res.result?.account_nfts ?? [];
+    return nfts.some((n) => n?.NFTokenID === nftId);
+}
+/**
+ * Find the ledger index of the issuer's NFT SELL offer brokered to `recipient`.
+ *
+ * Enumerates the issuer's `account_objects` of type `nft_offer` and returns the
+ * `index` of the offer whose `Destination` matches the recipient (else the first
+ * offer). (The mint sets `Destination = dev wallet` + `Flags = tfSellNFToken`.)
+ */
+async function findSellOfferIndex(client, issuer, recipient) {
+    const res = await client.request({
+        command: 'account_objects',
+        account: issuer,
+        type: 'nft_offer',
+    });
+    const objects = res.result?.account_objects ?? [];
+    const match = objects.find((o) => o?.Destination === recipient) ?? objects[0];
+    return match?.index;
+}
+/**
+ * Find the ledger index of the SELL offer for a specific `NFTokenID` brokered to
+ * `recipient`.
+ *
+ * Queries `nft_sell_offers` keyed by the NFTokenID — the exact, issuer-free path
+ * the validator's `chainNfts.xrpl.nftId` enables. Returns the `nft_offer_index`
+ * of the offer whose `destination` matches the dev wallet (else the first
+ * offer). Returns undefined when the offer isn't on-ledger yet.
+ */
+async function findSellOfferIndexByNftId(client, nftId, recipient) {
+    let res;
+    try {
+        res = await client.request({ command: 'nft_sell_offers', nft_id: nftId });
+    }
+    catch {
+        // `objectNotFound` is returned while no sell offer exists yet — treat as
+        // "not on-ledger yet" so the retry loop can fall back / wait.
+        return undefined;
+    }
+    const offers = res.result?.offers ?? [];
+    const match = offers.find((o) => o?.destination === recipient) ?? offers[0];
+    return match?.nft_offer_index;
+}
+function renderDepositInstructions(d, tier, appId) {
+    console.log(chalk_1.default.bold.green(`\n  Subscription requested: ${appId}`));
     console.log(chalk_1.default.bold.yellow('\n  Deposit required to mint your subscription NFT:'));
     console.log(chalk_1.default.gray(`    tier:     ${tier}`));
     console.log(chalk_1.default.gray(`    chain:    ${d.chain}`));
-    console.log(chalk_1.default.gray(`    amount:   ${d.amount} (token ${d.tokenId})`));
+    console.log(chalk_1.default.gray(`    amount:   ${d.amount} HST (token ${d.tokenId})`));
     console.log(chalk_1.default.gray(`    to:       ${d.walletAddress}\n`));
-    console.log(chalk_1.default.cyan(`  XUMM deeplink:`));
+}
+function renderManualPaymentHint(d) {
+    const xummDeeplink = buildXummDeeplink(d);
+    console.log(chalk_1.default.cyan('  --no-autopay: pay the deposit manually, then re-run `hsuite subscribe`.'));
+    console.log(chalk_1.default.cyan('  XUMM deeplink:'));
     console.log(chalk_1.default.cyan(`    ${xummDeeplink}\n`));
-    console.log(chalk_1.default.gray('  Waiting for deposit confirmation...\n'));
 }
 function buildXummDeeplink(d) {
     if (d.chain !== 'xrpl') {
         return `(no deeplink: chain=${d.chain})`;
     }
-    // Minimal Xumm deeplink shape; full IssuedCurrency requires JSON payload
-    // pushed through https://xumm.app/sign — for the CLI we surface the raw
-    // tx params so the user can paste them into their wallet.
+    // Minimal Xumm deeplink shape; full IssuedCurrency requires a JSON payload
+    // pushed through https://xumm.app/sign — for the CLI we surface the raw tx
+    // params so the user can paste them into their wallet.
     return `xumm://xrpl/send?to=${encodeURIComponent(d.walletAddress)}&amount=${encodeURIComponent(d.amount)}&token=${encodeURIComponent(d.tokenId)}`;
 }
 exports.subscribeCommand = new commander_1.Command('subscribe')
-    .description('Mint a subscription NFT against the cluster')
+    .description('Subscribe a smart-app: create DKG entity → auto-pay deposit → mint → accept subscription NFT (mint-first)')
     .option('--env <file>', 'Env file with XRPL creds', '.env.local')
     .option('--gateway <url>', 'Validator/gateway URL (defaults to VALIDATOR_URL in env)')
-    .option('--tier <tier>', 'Subscription tier (free_testnet|starter|professional|enterprise)', 'free_testnet')
-    .option('--networks <list>', 'Comma-separated networks (hedera,xrpl,etc.)', 'xrpl')
+    .option('--tier <tier>', 'Subscription tier (builder|growth|scale|enterprise)', 'builder')
+    .option('--app-id <id>', 'Resume an already-created entity by its appId (defaults to SUBSCRIPTION_APP_ID env). When unset, subscribe CREATES the DKG entity and uses its entityId.')
     .option('--app-name <name>', 'Smart-app display name')
-    .option('--app-id <id>', 'Reuse an existing app id (default: generate uuid)')
+    .option('--no-autopay', 'Skip auto-paying the HST deposit; print instructions for manual (XUMM) payment')
+    .option('--nft-issuer <address>', 'Optional override for the XRPL subscription-NFT issuer. No longer required: the /status response now exposes chainNfts.xrpl (nftId + issuerAddress) and the offer is resolved from it automatically. Defaults to SUBSCRIPTION_NFT_ISSUER env.')
     .action(async (opts) => {
     console.log(chalk_1.default.bold.cyan('\n  hsuite subscribe\n'));
     console.log(chalk_1.default.gray(`  env:    ${opts.env}`));
-    console.log(chalk_1.default.gray(`  tier:   ${opts.tier}`));
-    console.log(chalk_1.default.gray(`  nets:   ${opts.networks}\n`));
+    console.log(chalk_1.default.gray(`  tier:   ${opts.tier}\n`));
+    // Resolve the NFT issuer from env when not passed on the CLI.
+    if (!opts.nftIssuer) {
+        const env = (0, env_1.readEnv)(opts.env);
+        const fromEnv = env.get('SUBSCRIPTION_NFT_ISSUER');
+        if (fromEnv)
+            opts.nftIssuer = fromEnv;
+    }
     const spinner = (0, ora_1.default)(`requesting ${opts.tier} subscription...`).start();
     let result;
     try {
@@ -169,6 +557,17 @@ exports.subscribeCommand = new commander_1.Command('subscribe')
         spinner.fail(err.message);
         process.exit(1);
     }
+    if (!result.depositPaid) {
+        spinner.info(`subscription requested (appId=${result.appId}) — deposit not paid (--no-autopay)`);
+        const updates = {
+            SUBSCRIPTION_APP_ID: result.appId,
+            APP_ID: result.appId,
+        };
+        (0, env_1.upsertEnv)(opts.env, updates);
+        console.log(chalk_1.default.gray(`\n  wrote SUBSCRIPTION_APP_ID to ${opts.env}`));
+        console.log(chalk_1.default.yellow('\n  Pay the deposit, then re-run `hsuite subscribe` to mint + accept the NFT.\n'));
+        return;
+    }
     spinner.succeed(`subscription active (appId=${result.appId})`);
     if (result.nftSerial !== undefined) {
         console.log(chalk_1.default.gray(`  NFT serial: ${result.nftSerial}`));
@@ -176,6 +575,13 @@ exports.subscribeCommand = new commander_1.Command('subscribe')
     if (result.subscriptionId) {
         console.log(chalk_1.default.gray(`  subscriptionId: ${result.subscriptionId}`));
     }
+    if (result.nftAccepted) {
+        console.log(chalk_1.default.gray('  NFT accepted + confirmed on the dev wallet'));
+    }
+    else {
+        console.log(chalk_1.default.yellow('  NFT not yet on the dev wallet (sell offer may not be on-ledger yet). ' +
+            'Re-run `hsuite subscribe` to retry accepting it.'));
+    }
     const updates = {
         SUBSCRIPTION_APP_ID: result.appId,
         APP_ID: result.appId,