xrpjson 0.1.0

package/dist/fp/factories/confidential-mpt-convert-back.js

@@ -0,0 +1,203 @@
+/**
+ * Functional ConfidentialMptConvertBack factory — frozen-object style.
+ *
+ * Converts a holder's confidential (encrypted) MPT spending balance back
+ * into a public balance. The plaintext `MPTAmount` is credited to the
+ * holder's public balance, while the ciphertext pair is homomorphically
+ * subtracted from the holder's spending balance and the issuer's mirror
+ * balance. Issuers may also use this transaction from their dedicated
+ * second account to return confidential supply to public form.
+ *
+ * Validation happens at construction; there is no way to construct an
+ * invalid tx. Compare to the class-based equivalent, which exposes a
+ * separate `.validate()` method you must remember to call.
+ *
+ *   import { confidentialMptConvertBack } from 'xrplt/fp';
+ *   const tx = confidentialMptConvertBack({
+ *     Account,
+ *     MPTokenIssuanceID,
+ *     MPTAmount,
+ *     HolderEncryptedAmount,
+ *     IssuerEncryptedAmount,
+ *     BlindingFactor,
+ *     BalanceCommitment,
+ *     ZKProof,
+ *   });
+ *   const j = tx.toJSON();
+ *   const tx2 = tx.with({ Fee: '100' });
+ *
+ * Requires the `ConfidentialTransfer` amendment.
+ *
+ * @see https://xrpl.org/docs/references/protocol/transactions/types/confidentialmptconvertback
+ * @see XLS-0096 §11 — Transaction: `ConfidentialMPTConvertBack`
+ *   (https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0096-confidential-mpt)
+ * @see xrpl.js — packages/xrpl/src/models/transactions/ConfidentialMPTConvertBack.ts
+ *
+ * ## Divergences
+ *
+ * Compared with `src/transactions/confidential-mpt-convert-back.ts`, this
+ * factory adds guards the class skips — and is explicit about the
+ * canonical guards it cannot enforce in a zero-dependency package.
+ *
+ * - **`Account` is validated as a well-formed XRPL classic or X-address**
+ *   at construction time, with `isAccount` (`src/validation/helpers.ts`
+ *   lines 55–60). The class API delegates Account validation to its
+ *   `TokenTransaction` → `Transaction` parent chain via `super.validate()`;
+ *   failures therefore surface as a separate `.validate()` step rather
+ *   than at `new`. We re-implement the guard inline so a malformed Account
+ *   is caught at construction.
+ *   - Source: xrpl.js `validateBaseTransaction` (called transitively by
+ *     `validateConfidentialMPTConvertBack`).
+ *   - Source: xrpl-dev-portal `confidentialmptconvertback.md` JSON-Type
+ *     column for `Account` (`ACCOUNTID`).
+ *
+ * - **`MPTokenIssuanceID` is required to be exactly 48 hex characters
+ *   at construction time** (XLS-0096 §11.3 declares `MPTokenIssuanceID`
+ *   as `UINT192`; xrpl-dev-portal `confidentialmptconvertback.md`
+ *   declares the same). The class does the same check via `isHex` +
+ *   `length !== 48`, but only inside `.validate()` rather than at `new`.
+ *   - Source: XLS-0096 §11.3 Fields table, Internal Type = `UINT192`.
+ *   - Source: xrpl-dev-portal `confidentialmptconvertback.md` Fields
+ *     table row for `MPTokenIssuanceID`.
+ *
+ * - **`MPTAmount` is bounded to the canonical UInt64 range and rejected
+ *   for non-numeric / non-integer / out-of-range form.** The class only
+ *   checks `MPTAmount === '0'`, allowing `'9223372036854775808'` (one
+ *   past max uint64) to pass through and rely on the ledger to reject
+ *   it. xrpl.js's `validateConfidentialMPTAmount` (called via
+ *   `validateConfidentialMPTConvertBack` with `allowZero = false`)
+ *   enforces both `INTEGER_SANITY_CHECK` (`/^[0-9]+$/u`) and
+ *   `MPTAmount <= MAX_MPT_AMOUNT (= 9223372036854775807)`.
+ *   - Source: xrpl.js `validateConfidentialMPTAmount`
+ *     (`packages/xrpl/src/models/transactions/common.ts` lines 596–608).
+ *   - Source: xrpl.js `MAX_MPT_AMOUNT` (same file, line 48).
+ *   - Source: xrpl.js `ConfidentialMPTConvertBack.ts` line 83:
+ *     `validateConfidentialMPTAmount(tx, false)` (allowZero=false).
+ *   - Source: XLS-0096 §11.5.1 item 4: `MPTAmount` is zero or exceeds
+ *     the maximum allowable supply → `temBAD_AMOUNT`.
+ *
+ * - **`Account` must NOT be the issuer of `MPTokenIssuanceID` (KNOWN
+ *   LIMITATION — NOT IMPLEMENTED)**. XLS-0096 §11.5.1.2 mandates this
+ *   as `temMALFORMED`:
+ *
+ *     > "The account submitting the transaction is the Issuer.
+ *     > (`temMALFORMED`)"
+ *
+ *   xrpl.js's `validateConfidentialMPTConvertBack` (lines 78–82)
+ *   enforces this via its `isMPTIssuer(account, mptIssuanceID)` helper,
+ *   which calls `decodeAccountID` (base58 + double-SHA-256 checksum
+ *   decoding of the classic address) and compares the resulting 20-byte
+ *   AccountID against `mptIssuanceID.slice(8)` (the 40-hex-char issuer
+ *   portion after the 8-hex-char sequence prefix).
+ *
+ *   This factory cannot add this guard because the package is
+ *   **zero-dependency** — base58 + checksum decoding would require
+ *   either inlining a ~50-line codec or pulling in
+ *   `ripple-address-codec`, neither of which fits the scope of a
+ *   single-tx factory. The class API also skips this guard (it relies
+ *   on `super.validate()` which does not perform the issuer check), so
+ *   this is not a coverage regression relative to the class — but it
+ *   remains a documented gap that consumers must validate at the
+ *   integration layer (e.g. via the ledger submission result).
+ *   - Source: XLS-0096 §11.5.1.2 Failure Conditions (Data Verification),
+ *     item 2: `temMALFORMED` when `Account` is the Issuer.
+ *   - Source: xrpl-dev-portal `confidentialmptconvertback.md` Error
+ *     Cases table, `temMALFORMED` row.
+ *   - Source: xrpl.js `ConfidentialMPTConvertBack.ts` lines 78–82
+ *     (`isMPTIssuer` guard) and `common.ts` lines 632–646
+ *     (`isMPTIssuer` implementation, including the base58 + AccountID
+ *     decoding dependency).
+ */
+import { isAccount, isHex, isString } from '../../validation/helpers.js';
+import { ValidationError } from '../../errors.js';
+import { buildFrozenTx, mergeForWith, require } from '../shape.js';
+// ─── Spec constants ──────────────────────────────────────────────────
+// `MPTokenIssuanceID` is a `UINT192`, hex-encoded to exactly 48 chars
+// (192 / 8 = 24 bytes = 48 hex chars). XLS-0096 §11.3; xrpl-dev-portal
+// `confidentialmptconvertback.md` Fields table.
+const MPT_ISSUANCE_ID_HEX_LENGTH = 48;
+// ElGamal ciphertext = 2 compressed points = 66 bytes = 132 hex chars.
+// XLS-0096 §11.3; xrpl.js `CONFIDENTIAL_ELGAMAL_CIPHERTEXT_BYTES = 66`.
+const ELGAMAL_CIPHERTEXT_HEX_LENGTH = 132;
+// `BlindingFactor` is `UINT256` = 32 bytes = 64 hex chars.
+// XLS-0096 §11.3; xrpl.js `CONFIDENTIAL_BLINDING_FACTOR_BYTES = 32`.
+const BLINDING_FACTOR_HEX_LENGTH = 64;
+// Pedersen commitment = 1 compressed point = 33 bytes = 66 hex chars.
+// XLS-0096 §11.3; xrpl.js `CONFIDENTIAL_EC_POINT_BYTES = 33`.
+const BALANCE_COMMITMENT_HEX_LENGTH = 66;
+// `ZKProof` for ConvertBack is 816 bytes = 1632 hex chars
+// (128 bytes compact sigma + 688 bytes single Bulletproof range proof).
+// XLS-0096 §11.3 + §11 "Proof Structure"; xrpl.js
+// `CONFIDENTIAL_CONVERT_BACK_PROOF_BYTES = 816`.
+const ZK_PROOF_HEX_LENGTH = 1632;
+// `MPTAmount` is a `UINT64` per XLS-0096 §11.3. The maximum is 2^63 − 1
+// (signed integer range), matching xrpl.js's `MAX_MPT_AMOUNT`. Integer
+// form is required (no decimals, no leading sign) per xrpl.js
+// `INTEGER_SANITY_CHECK = /^[0-9]+$/u`. Zero is forbidden for
+// ConvertBack (only Convert allows zero).
+const MAX_MPT_AMOUNT = BigInt('9223372036854775807');
+const INTEGER_SANITY_CHECK = /^[0-9]+$/u;
+// ─── Helpers ─────────────────────────────────────────────────────────
+function requireHexOfLength(value, fieldName, hexLength) {
+    if (!isString(value) || !isHex(value) || value.length !== hexLength) {
+        throw new ValidationError(`ConfidentialMPTConvertBack: ${fieldName} must be a ${hexLength}-character hex string (${hexLength / 2} bytes)`);
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────
+export function confidentialMptConvertBack(props) {
+    // ── Account ── required, must be a valid XRPL classic/X-address.
+    require(props.Account, 'ConfidentialMPTConvertBack: Account is required', isAccount);
+    // ── MPTokenIssuanceID ── required, exactly 48-char hex (UINT192).
+    requireHexOfLength(props.MPTokenIssuanceID, 'MPTokenIssuanceID', MPT_ISSUANCE_ID_HEX_LENGTH);
+    // ── MPTAmount ── required, non-empty integer string, in [1, 2^63-1].
+    if (!isString(props.MPTAmount)) {
+        throw new ValidationError('ConfidentialMPTConvertBack: MPTAmount is required');
+    }
+    if (!INTEGER_SANITY_CHECK.test(props.MPTAmount)) {
+        throw new ValidationError('ConfidentialMPTConvertBack: MPTAmount must be a non-negative base-10 integer string');
+    }
+    const amount = BigInt(props.MPTAmount);
+    if (amount === BigInt(0)) {
+        throw new ValidationError('ConfidentialMPTConvertBack: MPTAmount must be non-zero');
+    }
+    if (amount > MAX_MPT_AMOUNT) {
+        throw new ValidationError(`ConfidentialMPTConvertBack: MPTAmount out of range (max ${MAX_MPT_AMOUNT.toString()})`);
+    }
+    // ── HolderEncryptedAmount ── required, 132-char hex (66-byte ElGamal ciphertext).
+    requireHexOfLength(props.HolderEncryptedAmount, 'HolderEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LENGTH);
+    // ── IssuerEncryptedAmount ── required, 132-char hex (66-byte ElGamal ciphertext).
+    requireHexOfLength(props.IssuerEncryptedAmount, 'IssuerEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LENGTH);
+    // ── BlindingFactor ── required, 64-char hex (32-byte scalar).
+    requireHexOfLength(props.BlindingFactor, 'BlindingFactor', BLINDING_FACTOR_HEX_LENGTH);
+    // ── BalanceCommitment ── required, 66-char hex (33-byte Pedersen commitment).
+    requireHexOfLength(props.BalanceCommitment, 'BalanceCommitment', BALANCE_COMMITMENT_HEX_LENGTH);
+    // ── ZKProof ── required, 1632-char hex (816-byte ConvertBack proof bundle).
+    requireHexOfLength(props.ZKProof, 'ZKProof', ZK_PROOF_HEX_LENGTH);
+    // ── AuditorEncryptedAmount ── optional, 132-char hex (66-byte ElGamal ciphertext).
+    if (props.AuditorEncryptedAmount !== undefined) {
+        requireHexOfLength(props.AuditorEncryptedAmount, 'AuditorEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LENGTH);
+    }
+    // NOTE: `Account` must NOT be the issuer of `MPTokenIssuanceID`
+    // (XLS-0096 §11.5.1.2 / xrpl.js `isMPTIssuer` guard). Not enforced
+    // here — see `## Divergences` header for why.
+    return buildFrozenTx('ConfidentialMPTConvertBack', props, {
+        validate() {
+            // Validated at construction.
+        },
+        toJSON() {
+            const json = {};
+            for (const k of Object.keys(this)) {
+                if (k === 'validate' || k === 'toJSON' || k === 'with')
+                    continue;
+                const v = this[k];
+                if (v !== undefined)
+                    json[k] = v;
+            }
+            return json;
+        },
+        with(overrides) {
+            return confidentialMptConvertBack(mergeForWith(this, overrides));
+        },
+    });
+}
+//# sourceMappingURL=confidential-mpt-convert-back.js.map

package/dist/fp/factories/confidential-mpt-convert-back.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential-mpt-convert-back.js","sourceRoot":"","sources":["../../../src/fp/factories/confidential-mpt-convert-back.ts"],"names":[],"mappings":"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"}

package/dist/fp/factories/confidential-mpt-convert.d.ts

@@ -0,0 +1,32 @@
+export interface ConfidentialMptConvertProps {
+    /** The account performing the conversion. Must be a valid XRPL classic/X-address. */
+    Account: string;
+    /** UInt192 — MPT issuance identifier (48-char hex). */
+    MPTokenIssuanceID: string;
+    /** UInt64 — plaintext public amount to convert (base-10 integer string, ≤ 2⁶³−1). */
+    MPTAmount: string;
+    /** 33-byte compressed ElGamal EC point (66 hex chars). Optional; required on first opt-in. */
+    HolderEncryptionKey?: string | undefined;
+    /** 66-byte ElGamal ciphertext credited to the holder's inbox (132 hex chars). */
+    HolderEncryptedAmount: string;
+    /** 66-byte ElGamal ciphertext credited to the issuer mirror balance (132 hex chars). */
+    IssuerEncryptedAmount: string;
+    /** 66-byte ElGamal ciphertext for the auditor (132 hex chars). Required when issuance has AuditorEncryptionKey. */
+    AuditorEncryptedAmount?: string | undefined;
+    /** UInt256 — 32-byte scalar blinding factor (64 hex chars). */
+    BlindingFactor: string;
+    /** 64-byte Schnorr proof of knowledge (128 hex chars). Required iff HolderEncryptionKey is present. */
+    ZKProof?: string | undefined;
+    /** Fee in XRP (drops), base-10 integer string. */
+    Fee?: string | undefined;
+    /** Account sequence number. */
+    Sequence?: number | undefined;
+}
+export interface ConfidentialMptConvert extends Readonly<ConfidentialMptConvertProps> {
+    readonly TransactionType: 'ConfidentialMPTConvert';
+    validate(): void;
+    toJSON(): Record<string, unknown>;
+    with(overrides: Partial<ConfidentialMptConvertProps>): ConfidentialMptConvert;
+}
+export declare function confidentialMptConvert(props: ConfidentialMptConvertProps): ConfidentialMptConvert;
+//# sourceMappingURL=confidential-mpt-convert.d.ts.map

package/dist/fp/factories/confidential-mpt-convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential-mpt-convert.d.ts","sourceRoot":"","sources":["../../../src/fp/factories/confidential-mpt-convert.ts"],"names":[],"mappings":"AAsJA,MAAM,WAAW,2BAA2B;IAC1C,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,iFAAiF;IACjF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mHAAmH;IACnH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,sBACf,SAAQ,QAAQ,CAAC,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,wBAAwB,CAAC;IACnD,QAAQ,IAAI,IAAI,CAAC;IACjB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAAG,sBAAsB,CAAC;CAC/E;AAkBD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,sBAAsB,CAgHxB"}

package/dist/fp/factories/confidential-mpt-convert.js

@@ -0,0 +1,209 @@
+/**
+ * Functional ConfidentialMPTConvert factory — frozen-object style.
+ *
+ * Converts a holder's public MPT balance to a confidential balance (credited
+ * to the holder's inbox; merge via `ConfidentialMPTMergeInbox` to make it
+ * spendable). Also serves as the **opt-in mechanism** for confidential
+ * transfer participation: a zero-amount conversion registers the holder's
+ * `HolderEncryptionKey` on their `MPToken` object.
+ *
+ * Validation happens at construction; there is no way to construct an
+ * invalid tx. Compare to the class-based equivalent, which exposes a
+ * separate `.validate()` method you must remember to call.
+ *
+ *   import { confidentialMptConvert } from 'xrplt/fp';
+ *   const tx = confidentialMptConvert({
+ *     Account, MPTokenIssuanceID, MPTAmount: '0',
+ *     HolderEncryptionKey, HolderEncryptedAmount, IssuerEncryptedAmount,
+ *     BlindingFactor, ZKProof,
+ *   });
+ *
+ * Requires the `ConfidentialTransfer` amendment.
+ *
+ * @see https://xrpl.org/docs/references/protocol/transactions/types/confidentialmptconvert
+ * @see XLS-0096 §8 — Transaction: `ConfidentialMPTConvert`
+ *   (https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0096-confidential-mpt)
+ * @see xrpl.js — packages/xrpl/src/models/transactions/ConfidentialMPTConvert.ts
+ *
+ * ## Divergences
+ *
+ * Compared with `src/transactions/confidential-mpt-convert.ts`, this
+ * factory adds guards the class skips — and documents the canonical
+ * guard that cannot be added in a zero-dependency package.
+ *
+ * - **`Account` is validated as a well-formed XRPL classic or X-address**
+ *   at construction time, with `isAccount` (`src/validation/helpers.ts`
+ *   lines 55–60). The class API delegates Account validation to its
+ *   `TokenTransaction` → `Transaction` parent chain via
+ *   `super.validate()`; failures therefore surface as a separate
+ *   `.validate()` step rather than at `new`. We re-implement the
+ *   guard inline so a malformed Account is caught at construction.
+ *   - Source: xrpl.js `validateBaseTransaction` (called transitively by
+ *     `validateConfidentialMPTConvert`).
+ *   - Source: xrpl-dev-portal `confidentialmptconvert.md` JSON-Type
+ *     column for `Account` (`ACCOUNTID`).
+ *
+ * - **`MPTAmount` is validated as a non-negative base-10 uint64 string
+ *   ≤ 2⁶³−1, with `0` permitted** (XLS-0096 §8.4.1.8 declares
+ *   over-max as `temBAD_AMOUNT`; a zero-amount convert is explicitly
+ *   used to register the holder key per §8.1). The class accepts the
+ *   field as-is with no range or well-formedness check.
+ *   - Source: XLS-0096 §8.2 Fields table, Internal Type = `UINT64`.
+ *   - Source: XLS-0096 §8.4.1.8 Failure Conditions, `temBAD_AMOUNT`.
+ *   - Source: xrpl.js `validateConfidentialMPTAmount(tx, true)`
+ *     (`packages/xrpl/src/models/transactions/common.ts` lines 596–608)
+ *     which uses `MAX_MPT_AMOUNT = 2^63 − 1` and `INTEGER_SANITY_CHECK`.
+ *   - Source: xrpl-dev-portal `confidentialmptconvert.md` Error Cases,
+ *     `temBAD_AMOUNT` row.
+ *
+ * - **`HolderEncryptionKey` length is enforced to exactly 33 bytes
+ *   (66 hex chars)** when present (XLS-0096 §8.4.1.5 declares
+ *   `temMALFORMED` for any other length). The class only verifies
+ *   `isHex` and that the length is non-zero, so a 64-char Schnorr-like
+ *   blob or a 32-char short pubkey would pass the class and be rejected
+ *   by rippled with `temMALFORMED`.
+ *   - Source: XLS-0096 §8.4.1.5 Failure Conditions, `temMALFORMED`.
+ *   - Source: xrpl.js `isHexWithByteLength(CONFIDENTIAL_EC_POINT_BYTES)`
+ *     where `CONFIDENTIAL_EC_POINT_BYTES = 33`
+ *     (`packages/xrpl/src/models/transactions/common.ts` lines 35–43).
+ *   - Source: xrpl-dev-portal `confidentialmptconvert.md` Error Cases,
+ *     `temMALFORMED` row "The length of `HolderEncryptionKey` is not
+ *     exactly 33 bytes."
+ *
+ * - **`ZKProof` without `HolderEncryptionKey` is rejected** (XLS-0096
+ *   §8.4.1.4 — `temMALFORMED`). The class only enforces the forward
+ *   direction ("if HolderEncryptionKey is present, ZKProof must be
+ *   present"); the reverse case slips through the class and is rejected
+ *   by rippled.
+ *   - Source: XLS-0096 §8.4.1.4 Failure Conditions, `temMALFORMED`.
+ *   - Source: xrpl.js `validateHolderKeyProofPairing`
+ *     (`packages/xrpl/src/models/transactions/ConfidentialMPTConvert.ts`
+ *     lines 73–79) checks both directions symmetrically with
+ *     `(tx.HolderEncryptionKey == null) !== (tx.ZKProof == null)`.
+ *
+ * - **`Account` must NOT be the issuer of `MPTokenIssuanceID`
+ *   (KNOWN LIMITATION — NOT IMPLEMENTED)**. XLS-0096 §8.4.1.2 mandates
+ *   this as `temMALFORMED`:
+ *
+ *     > "The `Account` is the Issuer of the `MPTokenIssuanceID`."
+ *
+ *   xrpl.js enforces this via `isMPTIssuer(account, mptIssuanceID)`
+ *   (`packages/xrpl/src/models/transactions/common.ts` lines 632–646),
+ *   which calls `decodeAccountID` (base58 + double-SHA-256 checksum
+ *   decoding of the classic address) and compares the resulting
+ *   20-byte AccountID against `mptIssuanceID.slice(8)` (the 40-hex-char
+ *   issuer portion after the 8-hex-char sequence prefix).
+ *
+ *   This factory cannot add this guard because the package is
+ *   **zero-dependency** — base58 + checksum decoding would require
+ *   either inlining a ~50-line codec or pulling in
+ *   `ripple-address-codec`, neither of which fits the scope of a
+ *   single-tx factory. The class API also skips this guard (it
+ *   relies on `super.validate()` which does not perform the
+ *   issuer check), so this is not a coverage regression relative
+ *   to the class — but it remains a documented gap that consumers
+ *   must validate at the integration layer (e.g. via the ledger
+ *   submission result).
+ *   - Source: XLS-0096 §8.4.1.2 Failure Conditions (Data Verification),
+ *     item 2: `temMALFORMED` when `Account` is the Issuer.
+ *   - Source: xrpl-dev-portal `confidentialmptconvert.md` Error
+ *     Cases table, `temMALFORMED` row.
+ *   - Source: xrpl.js `ConfidentialMPTConvert.ts` lines 94–98
+ *     (`isMPTIssuer` guard).
+ */
+import { isAccount, isHex, isString } from '../../validation/helpers.js';
+import { ValidationError } from '../../errors.js';
+import { buildFrozenTx, mergeForWith, require } from '../shape.js';
+// ─── Spec constants ──────────────────────────────────────────────────
+// `MPTokenIssuanceID` is a `UINT192`, hex-encoded to exactly 48 chars
+// (192 / 8 = 24 bytes = 48 hex chars). XLS-0096 §8.2; xrpl-dev-portal
+// `confidentialmptconvert.md` Fields table.
+const MPT_ISSUANCE_ID_HEX_LEN = 48;
+// `HolderEncryptedAmount` / `IssuerEncryptedAmount` / `AuditorEncryptedAmount`
+// are 66-byte ElGamal ciphertexts. XLS-0096 §8.2; xrpl.js
+// `CONFIDENTIAL_ELGAMAL_CIPHERTEXT_BYTES = 66`.
+const ELGAMAL_CIPHERTEXT_HEX_LEN = 132;
+// `HolderEncryptionKey` is a 33-byte compressed ElGamal EC point.
+// XLS-0096 §8.4.1.5; xrpl.js `CONFIDENTIAL_EC_POINT_BYTES = 33`.
+const HOLDER_ENCRYPTION_KEY_HEX_LEN = 66;
+// `BlindingFactor` is a `UINT256` (32 bytes = 64 hex chars). XLS-0096 §8.2;
+// xrpl.js `CONFIDENTIAL_BLINDING_FACTOR_BYTES = 32`.
+const BLINDING_FACTOR_HEX_LEN = 64;
+// `ZKProof` is a 64-byte Schnorr Proof of Knowledge. XLS-0096 §8.4.1.6;
+// xrpl.js `CONFIDENTIAL_CONVERT_PROOF_BYTES = 64`.
+const ZK_PROOF_HEX_LEN = 128;
+// `MPTAmount` is `UINT64`; per XLS-0096 §8.4.1.8 over-max returns
+// `temBAD_AMOUNT`. Per XLS-0096 §8.1 a zero-amount convert is explicitly
+// permitted to register the holder key. xrpl.js `MAX_MPT_AMOUNT` =
+// 2^63 − 1 = 9_223_372_036_854_775_807.
+const MAX_MPT_AMOUNT = BigInt('9223372036854775807');
+const INTEGER_SANITY_CHECK = /^[0-9]+$/u;
+// ─── Helpers ─────────────────────────────────────────────────────────
+function requireHexOfLength(value, fieldName, hexLength) {
+    if (!isString(value) || !isHex(value) || value.length !== hexLength) {
+        throw new ValidationError(`ConfidentialMPTConvert: ${fieldName} must be a ${hexLength}-character hex string`);
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────
+export function confidentialMptConvert(props) {
+    // ── Account ── required, must be a valid XRPL classic/X-address.
+    require(props.Account, 'ConfidentialMPTConvert: Account is required', isAccount);
+    // ── MPTokenIssuanceID ── required, exactly 48-char hex (UINT192).
+    requireHexOfLength(props.MPTokenIssuanceID, 'MPTokenIssuanceID', MPT_ISSUANCE_ID_HEX_LEN);
+    // NOTE: `Account` must NOT be the issuer of `MPTokenIssuanceID`
+    // (XLS-0096 §8.4.1.2 / xrpl.js `isMPTIssuer` guard). Not enforced
+    // here — see `## Divergences` header for why.
+    // ── MPTAmount ── required, non-negative uint64 ≤ 2⁶³−1; zero is allowed.
+    if (!isString(props.MPTAmount) || !INTEGER_SANITY_CHECK.test(props.MPTAmount)) {
+        throw new ValidationError('ConfidentialMPTConvert: MPTAmount must be a non-negative base-10 integer string');
+    }
+    if (BigInt(props.MPTAmount) > MAX_MPT_AMOUNT) {
+        throw new ValidationError(`ConfidentialMPTConvert: MPTAmount exceeds maximum ${MAX_MPT_AMOUNT.toString()}`);
+    }
+    // ── HolderEncryptedAmount ── required, 66-byte ElGamal ciphertext.
+    requireHexOfLength(props.HolderEncryptedAmount, 'HolderEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LEN);
+    // ── IssuerEncryptedAmount ── required, 66-byte ElGamal ciphertext.
+    requireHexOfLength(props.IssuerEncryptedAmount, 'IssuerEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LEN);
+    // ── BlindingFactor ── required, 32-byte scalar (UINT256).
+    requireHexOfLength(props.BlindingFactor, 'BlindingFactor', BLINDING_FACTOR_HEX_LEN);
+    // ── HolderEncryptionKey / ZKProof pairing ──
+    //
+    // XLS-0096 §8.4.1.3–§8.4.1.6 mandates: the pair must be set together
+    // or not at all, and each must be exactly its declared byte length.
+    // Symmetric guard via `xor`-style presence check.
+    const hasHolderKey = props.HolderEncryptionKey !== undefined;
+    const hasZkProof = props.ZKProof !== undefined;
+    if (hasHolderKey !== hasZkProof) {
+        throw new ValidationError('ConfidentialMPTConvert: set HolderEncryptionKey and ZKProof together (both required when either is present)');
+    }
+    if (hasHolderKey) {
+        // 33-byte compressed ElGamal EC point.
+        requireHexOfLength(props.HolderEncryptionKey, 'HolderEncryptionKey', HOLDER_ENCRYPTION_KEY_HEX_LEN);
+        // 64-byte Schnorr Proof of Knowledge.
+        requireHexOfLength(props.ZKProof, 'ZKProof', ZK_PROOF_HEX_LEN);
+    }
+    // ── AuditorEncryptedAmount ── optional; 66-byte ElGamal ciphertext.
+    if (props.AuditorEncryptedAmount !== undefined) {
+        requireHexOfLength(props.AuditorEncryptedAmount, 'AuditorEncryptedAmount', ELGAMAL_CIPHERTEXT_HEX_LEN);
+    }
+    return buildFrozenTx('ConfidentialMPTConvert', props, {
+        validate() {
+            // Validated at construction.
+        },
+        toJSON() {
+            const json = {};
+            for (const k of Object.keys(this)) {
+                if (k === 'validate' || k === 'toJSON' || k === 'with')
+                    continue;
+                const v = this[k];
+                if (v !== undefined)
+                    json[k] = v;
+            }
+            return json;
+        },
+        with(overrides) {
+            return confidentialMptConvert(mergeForWith(this, overrides));
+        },
+    });
+}
+//# sourceMappingURL=confidential-mpt-convert.js.map

package/dist/fp/factories/confidential-mpt-convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential-mpt-convert.js","sourceRoot":"","sources":["../../../src/fp/factories/confidential-mpt-convert.ts"],"names":[],"mappings":"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"}

package/dist/fp/factories/confidential-mpt-merge-inbox.d.ts

@@ -0,0 +1,18 @@
+export interface ConfidentialMptMergeInboxProps {
+    /** The account performing the merge. Must be a valid XRPL classic/X-address. */
+    Account: string;
+    /** UInt192 — MPT issuance identifier (48-char hex). */
+    MPTokenIssuanceID: string;
+    /** Fee in XRP (drops), base-10 integer string. */
+    Fee?: string | undefined;
+    /** Account sequence number. */
+    Sequence?: number | undefined;
+}
+export interface ConfidentialMptMergeInbox extends Readonly<ConfidentialMptMergeInboxProps> {
+    readonly TransactionType: 'ConfidentialMPTMergeInbox';
+    validate(): void;
+    toJSON(): Record<string, unknown>;
+    with(overrides: Partial<ConfidentialMptMergeInboxProps>): ConfidentialMptMergeInbox;
+}
+export declare function confidentialMptMergeInbox(props: ConfidentialMptMergeInboxProps): ConfidentialMptMergeInbox;
+//# sourceMappingURL=confidential-mpt-merge-inbox.d.ts.map

package/dist/fp/factories/confidential-mpt-merge-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential-mpt-merge-inbox.d.ts","sourceRoot":"","sources":["../../../src/fp/factories/confidential-mpt-merge-inbox.ts"],"names":[],"mappings":"AAqGA,MAAM,WAAW,8BAA8B;IAC7C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,yBACf,SAAQ,QAAQ,CAAC,8BAA8B,CAAC;IAChD,QAAQ,CAAC,eAAe,EAAE,2BAA2B,CAAC;IACtD,QAAQ,IAAI,IAAI,CAAC;IACjB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CACF,SAAS,EAAE,OAAO,CAAC,8BAA8B,CAAC,GACjD,yBAAyB,CAAC;CAC9B;AAID,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,yBAAyB,CA+C3B"}

package/dist/fp/factories/confidential-mpt-merge-inbox.js

@@ -0,0 +1,130 @@
+/**
+ * Functional ConfidentialMPTMergeInbox factory — frozen-object style.
+ *
+ * Merges the holder's pending confidential inbox balance into their
+ * spendable confidential balance for the named MPT issuance. Resets
+ * the inbox to canonical encrypted zero and increments the spending
+ * version, ensuring subsequent zero-knowledge proofs reference a
+ * stable spending balance.
+ *
+ * Validation happens at construction; there is no way to construct
+ * an invalid tx. Compare to the class-based equivalent, which exposes
+ * a separate `.validate()` method you must remember to call.
+ *
+ *   import { confidentialMptMergeInbox } from 'xrplt/fp';
+ *   const tx = confidentialMptMergeInbox({ Account, MPTokenIssuanceID });
+ *   const j = tx.toJSON();
+ *   const tx2 = tx.with({ Fee: '100' });
+ *
+ * Requires the `ConfidentialTransfer` amendment.
+ *
+ * @see https://xrpl.org/docs/references/protocol/transactions/types/confidentialmptmergeinbox
+ * @see XLS-0096 §10 — Transaction: `ConfidentialMPTMergeInbox`
+ *   (https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0096-confidential-mpt)
+ * @see xrpl.js — packages/xrpl/src/models/transactions/ConfidentialMPTMergeInbox.ts
+ *
+ * ## Divergences
+ *
+ * Compared with `src/transactions/confidential-mpt-merge-inbox.ts`,
+ * this factory adds guards the class skips — and is documented where
+ * additional canonical guards cannot be added in a zero-dependency
+ * package.
+ *
+ * - **`Account` is validated as a well-formed XRPL classic or X-address**
+ *   at construction time, with `isAccount` (`src/validation/helpers.ts`
+ *   lines 55–60). The class API delegates Account validation to its
+ *   `TokenTransaction` → `Transaction` parent chain via
+ *   `super.validate()`; failures therefore surface as a separate
+ *   `.validate()` step rather than at `new`. We re-implement the
+ *   guard inline so a malformed Account is caught at construction.
+ *   - Source: xrpl.js `validateBaseTransaction` (called transitively by
+ *     `validateConfidentialMPTMergeInbox`).
+ *   - Source: xrpl-dev-portal `confidentialmptmergeinbox.md` JSON-Type
+ *     column for `Account` (`ACCOUNTID`).
+ *
+ * - **`MPTokenIssuanceID` is required to be exactly 48 hex characters
+ *   at construction time** (XLS-0096 §10.2 declares
+ *   `MPTokenIssuanceID` as `UINT192`; xrpl-dev-portal
+ *   `confidentialmptmergeinbox.md` declares the same). The class
+ *   does the same check via `isHex` + `length !== 48`, but only
+ *   inside `.validate()` rather than at `new`.
+ *   - Source: XLS-0096 §10.2 Fields table, Internal Type = `UINT192`.
+ *   - Source: xrpl-dev-portal `confidentialmptmergeinbox.md` Fields
+ *     table row for `MPTokenIssuanceID`.
+ *
+ * - **`Account` must NOT be the issuer of `MPTokenIssuanceID`
+ *   (KNOWN LIMITATION — NOT IMPLEMENTED)**. XLS-0096 §10.4.1.2
+ *   mandates this as `temMALFORMED`:
+ *
+ *     > "The account submitting the transaction is the Issuer.
+ *     > (`temMALFORMED`)"
+ *
+ *   xrpl.js's `validateConfidentialMPTMergeInbox`
+ *   (`packages/xrpl/src/models/transactions/ConfidentialMPTMergeInbox.ts`
+ *   lines 36–41) enforces this via its `isMPTIssuer(account, mptIssuanceID)`
+ *   helper, which calls `decodeAccountID` (base58 + double-SHA-256
+ *   checksum decoding of the classic address) and compares the
+ *   resulting 20-byte AccountID against `mptIssuanceID.slice(8)` (the
+ *   40-hex-char issuer portion after the 8-hex-char sequence prefix).
+ *
+ *   This factory cannot add this guard because the package is
+ *   **zero-dependency** — base58 + checksum decoding would require
+ *   either inlining a ~50-line codec or pulling in
+ *   `ripple-address-codec`, neither of which fits the scope of a
+ *   single-tx factory. The class API also skips this guard (it
+ *   relies on `super.validate()` which does not perform the
+ *   issuer check), so this is not a coverage regression relative
+ *   to the class — but it remains a documented gap that consumers
+ *   must validate at the integration layer (e.g. via the ledger
+ *   submission result).
+ *   - Source: XLS-0096 §10.4.1.2 Failure Conditions (Data Verification),
+ *     item 2: `temMALFORMED` when `Account` is the Issuer.
+ *   - Source: xrpl-dev-portal `confidentialmptmergeinbox.md` Error
+ *     Cases table, `temMALFORMED` row.
+ *   - Source: xrpl.js `ConfidentialMPTMergeInbox.ts` lines 36–41
+ *     (`isMPTIssuer` guard) and `common.ts` lines 632–646
+ *     (`isMPTIssuer` implementation, including the base58 + AccountID
+ *     decoding dependency).
+ */
+import { isAccount, isHex, isString } from '../../validation/helpers.js';
+import { ValidationError } from '../../errors.js';
+import { buildFrozenTx, mergeForWith, require } from '../shape.js';
+// ─── Spec constants ──────────────────────────────────────────────────
+// `MPTokenIssuanceID` is a `UINT192`, hex-encoded to exactly 48 chars
+// (192 / 8 = 24 bytes = 48 hex chars). XLS-0096 §10.2; xrpl-dev-portal
+// `confidentialmptmergeinbox.md` Fields table.
+const MPT_ISSUANCE_ID_HEX_LENGTH = 48;
+// ─── Factory ─────────────────────────────────────────────────────────
+export function confidentialMptMergeInbox(props) {
+    // ── Account ── required, must be a valid XRPL classic/X-address.
+    require(props.Account, 'ConfidentialMPTMergeInbox: Account is required', isAccount);
+    // ── MPTokenIssuanceID ── required, exactly 48-char hex (UINT192).
+    if (!isString(props.MPTokenIssuanceID) ||
+        !isHex(props.MPTokenIssuanceID) ||
+        props.MPTokenIssuanceID.length !== MPT_ISSUANCE_ID_HEX_LENGTH) {
+        throw new ValidationError(`ConfidentialMPTMergeInbox: MPTokenIssuanceID must be a ${MPT_ISSUANCE_ID_HEX_LENGTH}-character hex string (UInt192)`);
+    }
+    // NOTE: `Account` must NOT be the issuer of `MPTokenIssuanceID`
+    // (XLS-0096 §10.4.1.2 / xrpl.js `isMPTIssuer` guard). Not enforced
+    // here — see `## Divergences` header for why.
+    return buildFrozenTx('ConfidentialMPTMergeInbox', props, {
+        validate() {
+            // Validated at construction.
+        },
+        toJSON() {
+            const json = {};
+            for (const k of Object.keys(this)) {
+                if (k === 'validate' || k === 'toJSON' || k === 'with')
+                    continue;
+                const v = this[k];
+                if (v !== undefined)
+                    json[k] = v;
+            }
+            return json;
+        },
+        with(overrides) {
+            return confidentialMptMergeInbox(mergeForWith(this, overrides));
+        },
+    });
+}
+//# sourceMappingURL=confidential-mpt-merge-inbox.js.map

package/dist/fp/factories/confidential-mpt-merge-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidential-mpt-merge-inbox.js","sourceRoot":"","sources":["../../../src/fp/factories/confidential-mpt-merge-inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEnE,wEAAwE;AAExE,sEAAsE;AACtE,uEAAuE;AACvE,+CAA+C;AAC/C,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAyBtC,wEAAwE;AAExE,MAAM,UAAU,yBAAyB,CACvC,KAAqC;IAErC,kEAAkE;IAClE,OAAO,CACL,KAAK,CAAC,OAAO,EACb,gDAAgD,EAChD,SAAS,CACV,CAAC;IAEF,mEAAmE;IACnE,IACE,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,CAAC;QAClC,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC;QAC/B,KAAK,CAAC,iBAAiB,CAAC,MAAM,KAAK,0BAA0B,EAC7D,CAAC;QACD,MAAM,IAAI,eAAe,CACvB,0DAA0D,0BAA0B,iCAAiC,CACtH,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,mEAAmE;IACnE,8CAA8C;IAE9C,OAAO,aAAa,CAClB,2BAA2B,EAC3B,KAAK,EACL;QACE,QAAQ;YACN,6BAA6B;QAC/B,CAAC;QACD,MAAM;YACJ,MAAM,IAAI,GAA4B,EAAE,CAAC;YACzC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,MAAM;oBAAE,SAAS;gBACjE,MAAM,CAAC,GAAI,IAA2C,CAAC,CAAC,CAAC,CAAC;gBAC1D,IAAI,CAAC,KAAK,SAAS;oBAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAEF,SAAkD;YAElD,OAAO,yBAAyB,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAClE,CAAC;KACF,CACF,CAAC;AACJ,CAAC"}