xrpjson 0.1.0

package/dist/fp/factories/xchain-create-claim-id.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Functional XChainCreateClaimID factory — frozen-object style.
+ *
+ * Creates a new cross-chain claim ID on the destination chain. The claim
+ * ID represents one cross-chain transfer of value and is the first step
+ * of a transfer: after this transaction succeeds, a corresponding
+ * `XChainCommit` transaction on the source chain can reference the
+ * resulting `XChainClaimID`. Validation happens at construction; there
+ * is no way to construct an invalid tx.
+ *
+ *   import { xchainCreateClaimID } from 'xrplt/fp';
+ *   const tx = xchainCreateClaimID({
+ *     Account: 'rahDmoXrtPdh7sUdrPjini3gcnTVYjbjjw',
+ *     OtherChainSource: 'rMTi57fNy2UkUb4RcdoUeJm7gjxVQvxzUo',
+ *     SignatureReward: '100',
+ *     XChainBridge: {
+ *       LockingChainDoor: 'rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4',
+ *       LockingChainIssue: { currency: 'XRP' },
+ *       IssuingChainDoor: 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
+ *       IssuingChainIssue: { currency: 'XRP' },
+ *     },
+ *   });
+ *   const j = tx.toJSON();
+ *
+ * Required amendment: `XChainBridge`.
+ *
+ * @see https://xrpl.org/docs/references/protocol/transactions/types/xchaincreateclaimid
+ * @see https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/models/transactions/XChainCreateClaimID.ts
+ * @see XLS-0038 (Cross-Chain Bridge) §2.3.1
+ *      `~/.mavis/docs.local/xrpl-standards/repo/XLS-0038-cross-chain-bridge/README.md`
+ *      lines 376–403
+ * @see rippled `XChainBridge.cpp::XChainCreateClaimID::preflight` (signatures
+ *      must be XRP, ≥ 0, and a legal net value):
+ *      https://github.com/XRPLF/rippled/blob/develop/src/libxrpl/tx/transactors/bridge/XChainBridge.cpp#L1961-L1969
+ *
+ * ## Divergences
+ *
+ * Compared with `src/transactions/xchain-create-claim-id.ts`, this
+ * factory adds guards the class skips (or that xrpl.js / xrpl.org /
+ * XLS-38 / rippled mandate but the class omits):
+ *
+ * - **`Account` must be a valid XRPL classic or X-address.** The class
+ *   accepts any non-empty string — only the base transaction
+ *   `super.validate()` is invoked. xrpl.js's `validateBaseTransaction`
+ *   (which `validateXChainCreateClaimID` delegates to) enforces a string;
+ *   we additionally enforce the XRPL classic/X-address format at
+ *   construction, matching every other fp factory.
+ *   - Source: xrpl.js
+ *     `~/.mavis/docs.local/xrpl.js/repo/packages/xrpl/src/models/transactions/common.ts`
+ *     `validateBaseTransaction`.
+ *   - Cross-ref: rippled parses `Account` as `STAccount`; only valid
+ *     XRPL classic addresses parse. xrpl.org `xchaincreateclaimid.md`
+ *     example line 20 lists `Account` as a classic address.
+ *
+ * - **`XChainBridge` is fully shape-validated.** xrpl.js
+ *   `validateXChainCreateClaimID` line 47 calls
+ *   `validateRequiredField(tx, 'XChainBridge', isXChainBridge)`, which
+ *   requires exactly 4 keys, two `AccountID` door strings, and two
+ *   `Issue` currency objects (`{currency: 'XRP'}` or `{currency,
+ *   issuer}`). The class only verifies `isRecord`, which accepts any
+ *   object (including `{}` or `{foo: 'bar'}`). The factory uses the
+ *   local `isXChainBridge` helper to enforce the full shape.
+ *   - Source: xrpl.js
+ *     `~/.mavis/docs.local/xrpl.js/repo/packages/xrpl/src/models/transactions/common.ts`
+ *     `isXChainBridge` (lines 444–453).
+ *   - Source: XLS-38 §2.3.1.1.1 line 391 (`XChainBridge` is required;
+ *     `XCHAIN_BRIDGE` internal type).
+ *   - Source: xrpl.org `xchaincreateclaimid.md` lines 56–61 (the four
+ *     sub-fields are each required: `IssuingChainDoor`,
+ *     `IssuingChainIssue`, `LockingChainDoor`, `LockingChainIssue`).
+ *   - Cross-ref: our `src/validation/helpers.ts` `isXChainBridge`
+ *     (lines 168–177) mirrors the xrpl.js check.
+ *
+ * - **Both `XChainBridge` doors must be valid XRPL classic
+ *   / X-addresses.** `isXChainBridge` only checks that the door
+ *   strings are strings; rippled parses them as `STAccount`. The
+ *   factory additionally runs `isAccount` on each door so a malformed
+ *   door string is caught at construction.
+ *   - Source: rippled `XChainBridge.cpp` (`sfLockingChainDoor`,
+ *     `sfIssuingChainDoor` parsed as `STAccount`).
+ *   - Source: xrpl.org `xchaincreateclaimid.md` line 58
+ *     (`IssuingChainDoor` is `Account`); line 60 (`LockingChainDoor`
+ *     is `Account`).
+ *   - Cross-ref: XLS-38 §2.1.1.1.2 lines 175–180 (bridge `XCHAIN_BRIDGE`
+ *     internal type; `LockingChainDoor` / `IssuingChainDoor` are
+ *     `ACCOUNT`).
+ *
+ * - **`SignatureReward` must be a non-negative XRP drops string.** The
+ *   class delegates to `isAmount`, which accepts any of: XRP drops
+ *   string, IOU object, or MPT object. XLS-38 §2.3.1.1.2 line 398
+ *   states: "The amount, **in XRP**, to be used to reward the witness
+ *   servers for providing signatures." xrpl.org
+ *   `xchaincreateclaimid.md` line 45 calls it a `Currency Amount`
+ *   (per the JSON type column) but the example JSON (line 22) uses
+ *   `"SignatureReward": "100"` (XRP drops string form), and the
+ *   description immediately after the table says "in XRP". rippled's
+ *   `XChainCreateClaimID::preflight` enforces `isXRP(reward) &&
+ *   reward.signum() >= 0 && isLegalNet(reward)` — i.e., native (XRP),
+ *   non-negative, and within the protocol's native mantissa cap. The
+ *   factory mirrors this with a strict XRP drops string check, ≥ 0
+ *   (zero is permitted; a bridge may opt out of witness payment).
+ *   - Source: XLS-38 §2.3.1.1.2 line 398 ("in XRP").
+ *   - Source: xrpl.org `xchaincreateclaimid.md` line 45 + example line
+ *     22 (`"SignatureReward": "100"`).
+ *   - Source: rippled `XChainBridge.cpp` lines 1961–1969
+ *     (`isXRP(reward) && signum() >= 0 && isLegalNet(reward)` →
+ *     `temXCHAIN_BRIDGE_BAD_REWARD_AMOUNT`).
+ *   - Cross-ref: `isLegalNet` enforces `mantissa() <= kMaxNativeN`
+ *     (`include/xrpl/protocol/STAmount.h` line 23: `kMaxNativeN =
+ *     100'000'000'000'000'000ull`). The factory does NOT enforce this
+ *     ceiling — at 100 billion XRP the wire form would already be too
+ *     large for the integer-string parser; we rely on the `isString`
+ *     type check plus the regex. (Documented for awareness; the spec
+ *     upper bound is effectively `kMaxNativeN`.)
+ *
+ * - **`OtherChainSource` must be a valid XRPL classic / X-address.**
+ *   The class declares the field as `readonly OtherChainSource: string`
+ *   but never validates it. xrpl.js `validateXChainCreateClaimID`
+ *   line 49 calls `validateRequiredField(tx, 'OtherChainSource',
+ *   isAccount)`. xrpl.org `xchaincreateclaimid.md` line 44 marks it
+ *   `String - Address / AccountID`; XLS-38 §2.3.1.1.3 line 402 defines
+ *   it as `ACCOUNT`. rippled parses it as `STAccount`. The factory
+ *   enforces XRPL address format at construction.
+ *   - Source: xrpl.js `XChainCreateClaimID.ts` line 49 (`isAccount`).
+ *   - Source: xrpl.org `xchaincreateclaimid.md` line 44 (`AccountID`).
+ *   - Source: XLS-38 §2.3.1.1.3 line 402 (`ACCOUNT` internal type).
+ *   - Cross-ref: rippled parses `OtherChainSource` as `STAccount`; only
+ *     valid XRPL classic addresses parse.
+ *
+ * - **`XChainClaimID` is NOT a transaction field.** The task brief
+ *   mentioned `XChainClaimID` as a `number | string` UInt64 input, but
+ *   the canonical spec lists exactly three fields — `XChainBridge`,
+ *   `SignatureReward`, `OtherChainSource` — at XLS-38 §2.3.1.1 lines
+ *   385–389. xrpl.js's `XChainCreateClaimID` interface (lines 23–37)
+ *   also omits it. rippled's `XChainCreateClaimID::doApply` derives
+ *   the new claim ID by incrementing the bridge's stored counter
+ *   (`(*sleBridge)[sfXChainClaimID] + 1`, `XChainBridge.cpp:2022`).
+ *   The factory correctly omits `XChainClaimID`; consumers read the
+ *   new claim ID from the transaction's metadata after submission.
+ *   - Source: XLS-38 §2.3.1.1 lines 385–389 (no `XChainClaimID` row).
+ *   - Source: xrpl.js `XChainCreateClaimID.ts` lines 23–37 (interface
+ *     has no `XChainClaimID` field).
+ *   - Source: rippled `XChainBridge.cpp` lines 2022–2029 (claim ID is
+ *     derived, not input).
+ *
+ * - **`Account` and `OtherChainSource` are typically different
+ *   accounts.** The factory does NOT enforce a `Account !==
+ *   OtherChainSource` check (XLS-38 does not forbid self-source), but
+ *   in practice `OtherChainSource` is the source-chain account that
+ *   will later submit the `XChainCommit` transaction, while `Account`
+ *   is the destination-chain account that submits this
+ *   `XChainCreateClaimID`. Same-account usage is unusual but allowed.
+ *   Documented here to clarify the factory's scope; no spec rule is
+ *   relaxed.
+ *
+ * - **`Flags` accepted for parity with the base transaction shape.**
+ *   XChainCreateClaimID defines no transaction-specific flags; only
+ *   `tfFullyCanonicalSig` (global) is normally meaningful. The class
+ *   does not declare a `Flags` field. We accept a numeric bitmask
+ *   for parity with the rest of the fp family. This is a permissive
+ *   addition, not a tightening.
+ *   - Source: XLS-38 §2.3.1.1 lines 385–389 (no `Flags` row).
+ *   - Cross-ref: rippled accepts the `Flags` field for any transaction
+ *     (it defaults to `tfFullyCanonicalSig`).
+ */
+import type { XChainBridge } from '../../types/common.js';
+export interface XchainCreateClaimIDProps {
+    /** The unique address of the transaction sender — the destination-
+     *  chain account that will own the resulting `XChainOwnedClaimID`
+     *  ledger object. Valid XRPL classic/X-address. */
+    Account: string;
+    /** The bridge to create the claim ID for. Required; 4-key shape with
+     *  both doors as valid XRPL classic/X addresses and both Issues as
+     *  valid Issue forms. */
+    XChainBridge: XChainBridge;
+    /** The amount, in XRP, to reward the witness servers for providing
+     *  signatures. Must match the bridge's stored `SignatureReward`.
+     *  Non-negative (≥ 0). */
+    SignatureReward: string;
+    /** The account that must send the `XChainCommit` transaction on the
+     *  source chain. Valid XRPL classic/X-address. */
+    OtherChainSource: string;
+    /** Bit-flags for this transaction. XChainCreateClaimID has no
+     *  defined flags; only `tfFullyCanonicalSig` (global) is meaningful.
+     *  Accepted for parity with the base tx shape. */
+    Flags?: number | undefined;
+    /** Fee in drops. */
+    Fee?: string | undefined;
+    /** Account sequence number. */
+    Sequence?: number | undefined;
+}
+export interface XchainCreateClaimID extends Readonly<XchainCreateClaimIDProps> {
+    readonly TransactionType: 'XChainCreateClaimID';
+    validate(): void;
+    toJSON(): Record<string, unknown>;
+    with(overrides: Partial<XchainCreateClaimIDProps>): XchainCreateClaimID;
+}
+export declare function xchainCreateClaimID(props: XchainCreateClaimIDProps): XchainCreateClaimID;
+//# sourceMappingURL=xchain-create-claim-id.d.ts.map

package/dist/fp/factories/xchain-create-claim-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xchain-create-claim-id.d.ts","sourceRoot":"","sources":["../../../src/fp/factories/xchain-create-claim-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAiD1D,MAAM,WAAW,wBAAwB;IACvC;;uDAEmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB;;6BAEyB;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B;;8BAE0B;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB;sDACkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB;;sDAEkD;IAClD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBACf,SAAQ,QAAQ,CAAC,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,QAAQ,IAAI,IAAI,CAAC;IACjB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,mBAAmB,CAAC;CACzE;AAID,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,mBAAmB,CA0DrB"}

package/dist/fp/factories/xchain-create-claim-id.js

@@ -0,0 +1,78 @@
+import { isAccount, isString, isXChainBridge } from '../../validation/helpers.js';
+import { ValidationError } from '../../errors.js';
+import { buildFrozenTx, mergeForWith, require } from '../shape.js';
+// ─── Helpers ─────────────────────────────────────────────────────────
+const XRP_DROPS_REGEX = /^[0-9]+$/u;
+/**
+ * Non-negative XRP drops Amount. Accepts the canonical XRP drops
+ * mantissa form (decimal integer string with no exponent, no decimal
+ * point — the wire format used by Amount fields in XChainBridge-related
+ * transactions) and rejects zero, negative, and non-numeric values
+ * via the strictly-positive wrapper.
+ *
+ * For XChainCreateClaimID, `SignatureReward` may legitimately be `'0'`
+ * (a bridge may opt out of witness payment). Zero is therefore allowed.
+ */
+function isNonNegativeXrpAmount(value) {
+    if (!isString(value))
+        return false;
+    if (!XRP_DROPS_REGEX.test(value))
+        return false;
+    // Reject leading zeros (e.g., '01', '00100') — the XRPL wire format
+    // rejects these. `'0'` itself is the only valid zero.
+    if (value.length > 1 && value.startsWith('0'))
+        return false;
+    return true;
+}
+/**
+ * Validate XChainBridge object shape: 4 keys with both doors as valid
+ * XRPL classic/X addresses and both issues as valid Issue forms. The
+ * local `isXChainBridge` helper checks the structural 4-key + Issue
+ * shape; we add XRPL-account format validation on the two doors.
+ */
+function assertValidXChainBridge(bridge) {
+    if (!isAccount(bridge.LockingChainDoor)) {
+        throw new ValidationError('XChainCreateClaimID: XChainBridge.LockingChainDoor must be a valid XRPL account address');
+    }
+    if (!isAccount(bridge.IssuingChainDoor)) {
+        throw new ValidationError('XChainCreateClaimID: XChainBridge.IssuingChainDoor must be a valid XRPL account address');
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────
+export function xchainCreateClaimID(props) {
+    // ── Account ── required, must be a valid XRPL classic or X-address.
+    require(props.Account, 'XChainCreateClaimID: Account is required', isAccount);
+    // ── XChainBridge ── required, full shape (4 keys, both doors valid
+    //    XRPL accounts, both issues valid Issue forms).
+    require(props.XChainBridge, 'XChainCreateClaimID: XChainBridge is required and must have shape {LockingChainDoor, LockingChainIssue, IssuingChainDoor, IssuingChainIssue}', isXChainBridge);
+    // `props.XChainBridge` is now type-narrowed to XChainBridge —
+    // verify the doors are valid XRPL accounts (the helper only
+    // checks `typeof === 'string'`).
+    assertValidXChainBridge(props.XChainBridge);
+    // ── SignatureReward ── required, non-negative XRP drops string.
+    if (!isNonNegativeXrpAmount(props.SignatureReward)) {
+        throw new ValidationError('XChainCreateClaimID: SignatureReward must be a non-negative XRP drops string (in XRP, ≥ 0; XLS-38 §2.3.1.1.2 line 398)');
+    }
+    // ── OtherChainSource ── required, valid XRPL classic/X-address.
+    require(props.OtherChainSource, 'XChainCreateClaimID: OtherChainSource is required', isAccount);
+    return buildFrozenTx('XChainCreateClaimID', 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 xchainCreateClaimID(mergeForWith(this, overrides));
+        },
+    });
+}
+//# sourceMappingURL=xchain-create-claim-id.js.map

package/dist/fp/factories/xchain-create-claim-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xchain-create-claim-id.js","sourceRoot":"","sources":["../../../src/fp/factories/xchain-create-claim-id.ts"],"names":[],"mappings":"AAsKA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEnE,wEAAwE;AAExE,MAAM,eAAe,GAAG,WAAW,CAAC;AAEpC;;;;;;;;;GASG;AACH,SAAS,sBAAsB,CAAC,KAAc;IAC5C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,oEAAoE;IACpE,sDAAsD;IACtD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,uBAAuB,CAAC,MAAoB;IACnD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,eAAe,CACvB,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,eAAe,CACvB,yFAAyF,CAC1F,CAAC;IACJ,CAAC;AACH,CAAC;AAsCD,wEAAwE;AAExE,MAAM,UAAU,mBAAmB,CACjC,KAA+B;IAE/B,qEAAqE;IACrE,OAAO,CACL,KAAK,CAAC,OAAO,EACb,0CAA0C,EAC1C,SAAS,CACV,CAAC;IAEF,oEAAoE;IACpE,oDAAoD;IACpD,OAAO,CACL,KAAK,CAAC,YAAY,EAClB,8IAA8I,EAC9I,cAAc,CACf,CAAC;IACF,8DAA8D;IAC9D,4DAA4D;IAC5D,iCAAiC;IACjC,uBAAuB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAE5C,iEAAiE;IACjE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,eAAe,CACvB,wHAAwH,CACzH,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,OAAO,CACL,KAAK,CAAC,gBAAgB,EACtB,mDAAmD,EACnD,SAAS,CACV,CAAC;IAEF,OAAO,aAAa,CAClB,qBAAqB,EACrB,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,SAA4C;YAE5C,OAAO,mBAAmB,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAC5D,CAAC;KACF,CACF,CAAC;AACJ,CAAC"}

package/dist/fp/factories/xchain-modify-bridge.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Functional XChainModifyBridge factory — frozen-object style.
+ *
+ * Updates the parameters of an existing cross-chain bridge. Per XLS-38
+ * §2.2.2 (line 336), only `SignatureReward` and `MinAccountCreateAmount`
+ * may be modified — changing the door accounts or assets would be
+ * equivalent to creating a new bridge. The transaction is sent by the
+ * door account and requires witness signatures (collected outside the
+ * ledger). Validation happens at construction; there is no way to
+ * construct an invalid tx.
+ *
+ *   import { xchainModifyBridge } from 'xrplt/fp';
+ *   const tx = xchainModifyBridge({
+ *     Account: 'rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg',
+ *     XChainBridge: { ... },
+ *     SignatureReward: '250',
+ *     MinAccountCreateAmount: '500000',
+ *     Flags: { tfClearAccountCreateAmount: false },
+ *   });
+ *   // Clear the MinAccountCreateAmount via the explicit flag:
+ *   const tx2 = xchainModifyBridge({
+ *     Account: 'rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg',
+ *     XChainBridge: { ... },
+ *     SignatureReward: '250',
+ *     Flags: { tfClearAccountCreateAmount: true },
+ *   });
+ *   const j = tx.toJSON();
+ *   const tx3 = tx.with({ SignatureReward: '300' });
+ *
+ * @see https://xrpl.org/docs/references/protocol/transactions/types/xchainmodifybridge
+ * @see https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/models/transactions/XChainModifyBridge.ts
+ * @see XLS-0038 (Cross-Chain Bridge) §2.2.2
+ *     (`~/.mavis/docs.local/xrpl-standards/repo/XLS-0038-cross-chain-bridge/README.md`
+ *     lines 334–372)
+ *
+ * ## Divergences
+ *
+ * Compared with `src/transactions/xchain-modify-bridge.ts`, this factory
+ * adds guards the class skips (or that xrpl.js / xrpl.org / XLS-38
+ * mandate but the class omits):
+ *
+ * - **`Account` must be a valid XRPL classic or X-address.** The class
+ *   only invokes `super.validate()` (the base transaction check), which
+ *   does not enforce an XRPL address format. xrpl.js's
+ *   `validateBaseTransaction` (which `validateXChainModifyBridge`
+ *   delegates to) requires a string; we additionally enforce the XRPL
+ *   classic/X-address format at construction, matching every other fp
+ *   factory.
+ *   - Source: xrpl.js
+ *     `~/.mavis/docs.local/xrpl.js/repo/packages/xrpl/src/models/transactions/common.ts`
+ *     `validateBaseTransaction`.
+ *   - Cross-ref: rippled `XChainBridge.cpp` preflight parses
+ *     `Account` as `STAccount`; only valid XRPL classic addresses parse.
+ *     xrpl.org `xchainmodifybridge.md` line 26 lists `Account` as the
+ *     door account.
+ *
+ * - **`XChainBridge` is fully shape-validated.** xrpl.js
+ *   `validateXChainModifyBridge.ts:72` calls
+ *   `validateRequiredField(tx, 'XChainBridge', isXChainBridge)`,
+ *   which requires exactly 4 keys, two `AccountID` door strings, and
+ *   two `Issue` currency objects. Our class only verifies `isRecord`,
+ *   which accepts any object (including `{}` or `{foo: 'bar'}`). The
+ *   factory uses the local `isXChainBridge` helper to enforce the full
+ *   shape.
+ *   - Source: xrpl.js `common.ts` `isXChainBridge` (lines 444–453).
+ *   - Source: XLS-38 §2.2.2.1.1 line 354 (`XChainBridge` is required,
+ *     `XCHAIN_BRIDGE` internal type).
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 50 (required).
+ *
+ * - **Both `XChainBridge` doors must be valid XRPL classic
+ *   addresses.** `isXChainBridge` only checks that the door strings are
+ *   strings; rippled parses them as `STAccount`. The factory
+ *   additionally runs `isAccount` on each door so a malformed door
+ *   string is caught at construction.
+ *   - Source: xrpl.org `xchainmodifybridge.md` lines 57, 59 (each
+ *     door is `AccountID`).
+ *   - Cross-ref: rippled `XChainBridge.cpp` (`sfLockingChainDoor`,
+ *     `sfIssuingChainDoor` parsed as `STAccount`).
+ *
+ * - **`SignatureReward` must be a non-negative XRP drops string.**
+ *   XLS-38 §2.1.1.1.3 line 200 (the spec text is shared between
+ *   create-bridge and modify-bridge): "The total amount, **in XRP**, to
+ *   be rewarded for providing a signature for a cross-chain transfer or
+ *   for signing for the cross-chain reward." xrpl.js
+ *   `validateXChainModifyBridge.ts:74` only runs `isAmount`, which
+ *   accepts any of: XRP drops string, IOU object, or MPT object. The
+ *   factory enforces XRP-only (drops string) with `≥ 0`, matching the
+ *   XLS-38 wording and rippled's `STAmount` parse for `sfSignatureReward`.
+ *   The factory treats `SignatureReward` as **required** even though the
+ *   canonical sources mark it as optional, because modifying the
+ *   signature reward is the canonical use case of this transaction and
+ *   forcing the caller to be explicit avoids silently no-op txs
+ *   (cf. Spec Ambiguities #1).
+ *   - Source: XLS-38 §2.1.1.1.3 line 200 ("in XRP").
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 49 (example uses
+ *     numeric `200`).
+ *   - Source: XLS-38 §2.2.2.1.2 line 358 (`SignatureReward` field).
+ *
+ * - **`MinAccountCreateAmount`, when present, must be a non-negative
+ *   XRP drops string.** xrpl.org line 48: "The minimum amount, **in
+ *   XRP**, required for a `XChainAccountCreateCommit` transaction.
+ *   ... **This field can only be present on XRP-XRP bridges.**" XLS-38
+ *   §2.1.1.1.4 line 204 repeats the same. The class accepts any string;
+ *   xrpl.js's `validateXChainModifyBridge.ts:76` does the same. The
+ *   factory rejects IOU/MPT forms and non-canonical wire forms (leading
+ *   zeros, decimals, exponents) at construction.
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 48 ("in XRP";
+ *     "can only be present on XRP-XRP bridges").
+ *   - Source: XLS-38 §2.1.1.1.4 line 204 ("in XRP"; "XRP-XRP
+ *     bridges only").
+ *   - Source: XLS-38 §2.2.2.1.3 line 362 (`MinAccountCreateAmount`
+ *     field).
+ *
+ * - **`Account` must equal `XChainBridge.LockingChainDoor`.** xrpl.org
+ *   line 13: "Only managers can send this transaction." xrpl.org line
+ *   15: "This transaction must be sent by the door account." The
+ *   example JSON (lines 26, 28) sets `Account === LockingChainDoor`.
+ *   The factory enforces this equality at construction. The class does
+ *   not (it accepts any `Account` shape). Note: an issuing-chain
+ *   submission uses the `IssuingChainDoor` instead; we do not enforce
+ *   that case here — see Spec Ambiguities #2.
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 13 ("Only managers
+ *     can send this transaction").
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 15 ("must be sent
+ *     by the door account").
+ *   - Source: xrpl.org example JSON (lines 26, 28) — `Account` equals
+ *     `LockingChainDoor`.
+ *   - Cross-ref: rippled `XChainBridge.cpp` preflight checks
+ *     `tx[sfAccount]` matches the door account.
+ *
+ * - **`Flags` accepts the `tfClearAccountCreateAmount` flag (0x00010000)
+ *   via boolean-map form.** XLS-38 §2.2.2.1.4 lines 366–372 defines a
+ *   single transaction-specific flag,
+ *   `tfClearAccountCreateAmount` (`0x00010000`), which clears the
+ *   `MinAccountCreateAmount` on the bridge. xrpl.js exposes this via
+ *   `XChainModifyBridgeFlagsInterface` (lines 29–32). The class does
+ *   not declare any `Flags` field; we accept both numeric and
+ *   boolean-map forms and translate the latter to a numeric bitmask
+ *   for downstream consumers (mirroring `nftokenMint`'s flag handling).
+ *   When set, the resulting `Flags` includes the `0x00010000` bit.
+ *   - Source: xrpl.js `XChainModifyBridge.ts` lines 18–32
+ *     (`XChainModifyBridgeFlags` enum, `XChainModifyBridgeFlagsInterface`).
+ *   - Source: XLS-38 §2.2.2.1.4 line 372.
+ *   - Source: xrpl.org `xchainmodifybridge.md` line 69.
+ *
+ * - **No `Amount` / `Destination` / `Memos` are not declared here.**
+ *   `XChainModifyBridge` only carries `SignatureReward` /
+ *   `MinAccountCreateAmount` (plus the `XChainBridge`). We do not add
+ *   unsupported fields. The factory does not pass through arbitrary
+ *   keys — `.with()` can override the documented fields only.
+ *   (Sanity note; included to prevent future API drift.)
+ *   - Source: XLS-38 §2.2.2.1 fields table (lines 347–352); no other
+ *     amount-bearing fields.
+ *   - Source: xrpl.org `xchainmodifybridge.md` Fields table
+ *     (lines 45–50); no other fields.
+ */
+import type { XChainBridge } from '../../types/common.js';
+import type { XChainModifyBridgeFlagsInterface } from '../../types/flags.js';
+export interface XchainModifyBridgeProps {
+    /** The unique address of the transaction sender — the door account
+     *  on the chain the bridge was created on. For a locking-chain
+     *  submission, this MUST equal `XChainBridge.LockingChainDoor`
+     *  (xrpl.org line 15, rippled preflight). */
+    Account: string;
+    /** The bridge (door accounts and assets) to modify. Required;
+     *  must be a fully-shaped `XChainBridge` (4 keys, two valid XRPL
+     *  doors, two valid Issue forms). */
+    XChainBridge: XChainBridge;
+    /** The total amount to pay the witness servers for their
+     *  signatures (XRP drops, ≥ 0). Factory treats this as required
+     *  even though XLS-38 marks it optional — see Divergences for
+     *  rationale. */
+    SignatureReward: string;
+    /** Optional. The minimum amount, in XRP, required for a
+     *  `XChainAccountCreateCommit` transaction against this bridge.
+     *  May only be present on XRP-XRP bridges; defaults to 0 when
+     *  omitted. To explicitly clear a previously-set value, use the
+     *  `tfClearAccountCreateAmount` flag instead. */
+    MinAccountCreateAmount?: string | undefined;
+    /** Bit-flags for this transaction. Accepts a numeric bitmask or
+     *  the `XChainModifyBridgeFlagsInterface` boolean-map form. The
+     *  transaction-specific flag is `tfClearAccountCreateAmount`
+     *  (`0x00010000`); setting it clears the bridge's stored
+     *  `MinAccountCreateAmount`. */
+    Flags?: number | XChainModifyBridgeFlagsInterface | undefined;
+    /** Fee in drops. */
+    Fee?: string | undefined;
+    /** Account sequence number. */
+    Sequence?: number | undefined;
+}
+export interface XchainModifyBridge extends Readonly<XchainModifyBridgeProps> {
+    readonly TransactionType: 'XChainModifyBridge';
+    validate(): void;
+    toJSON(): Record<string, unknown>;
+    with(overrides: Partial<XchainModifyBridgeProps>): XchainModifyBridge;
+}
+export declare function xchainModifyBridge(props: XchainModifyBridgeProps): XchainModifyBridge;
+//# sourceMappingURL=xchain-modify-bridge.d.ts.map

package/dist/fp/factories/xchain-modify-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xchain-modify-bridge.d.ts","sourceRoot":"","sources":["../../../src/fp/factories/xchain-modify-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2JG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC;AAoD7E,MAAM,WAAW,uBAAuB;IACtC;;;iDAG6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB;;yCAEqC;IACrC,YAAY,EAAE,YAAY,CAAC;IAC3B;;;qBAGiB;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;qDAIiD;IACjD,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;oCAIgC;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,gCAAgC,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,kBACf,SAAQ,QAAQ,CAAC,uBAAuB,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC;IAC/C,QAAQ,IAAI,IAAI,CAAC;IACjB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,kBAAkB,CAAC;CACvE;AAID,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAkFpB"}

package/dist/fp/factories/xchain-modify-bridge.js

@@ -0,0 +1,102 @@
+import { isAccount, isString, isXChainBridge } from '../../validation/helpers.js';
+import { ValidationError } from '../../errors.js';
+import { buildFrozenTx, mergeForWith, require } from '../shape.js';
+// ─── Spec constants ──────────────────────────────────────────────────
+// ─── Helpers ─────────────────────────────────────────────────────────
+const XRP_DROPS_REGEX = /^[0-9]+$/u;
+/**
+ * Non-negative XRP drops Amount. Accepts the canonical XRPL wire form
+ * (decimal integer string with no exponent, no decimal point) and
+ * rejects leading zeros (e.g. `'01'`, `'00100'`) so the form matches
+ * what rippled's `STAmount` parser will accept. `'0'` itself is the
+ * only valid zero.
+ *
+ * For XChainModifyBridge, both `SignatureReward` and
+ * `MinAccountCreateAmount` may legitimately be `'0'`: a zero
+ * `SignatureReward` is permitted (bridge may opt out of witness
+ * payment); a zero `MinAccountCreateAmount` is the default value when
+ * the field is omitted. Zero is therefore allowed.
+ */
+function isNonNegativeXrpAmount(value) {
+    if (!isString(value))
+        return false;
+    if (!XRP_DROPS_REGEX.test(value))
+        return false;
+    if (value.length > 1 && value.startsWith('0'))
+        return false;
+    return true;
+}
+/**
+ * Validate XChainBridge object shape: 4 keys with both doors as valid
+ * XRPL classic/X addresses and both issues as valid Issue forms. The
+ * local `isXChainBridge` helper checks the structural 4-key + Issue
+ * shape; we add XRPL-account format validation on the two doors.
+ */
+function assertValidXChainBridge(bridge) {
+    if (!isAccount(bridge.LockingChainDoor)) {
+        throw new ValidationError('XChainModifyBridge: XChainBridge.LockingChainDoor must be a valid XRPL account address');
+    }
+    if (!isAccount(bridge.IssuingChainDoor)) {
+        throw new ValidationError('XChainModifyBridge: XChainBridge.IssuingChainDoor must be a valid XRPL account address');
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────
+export function xchainModifyBridge(props) {
+    // ── Account ── required, must be a valid XRPL classic or X-address.
+    require(props.Account, 'XChainModifyBridge: Account is required', isAccount);
+    // ── XChainBridge ── required, full shape (4 keys, both doors valid
+    //    XRPL accounts, both issues valid Issue forms). The factory uses
+    //    the local `isXChainBridge` helper for the structural shape
+    //    (see validation/helpers.ts lines 168–177) and additionally
+    //    verifies the door strings are valid XRPL accounts.
+    require(props.XChainBridge, 'XChainModifyBridge: XChainBridge is required and must have shape {LockingChainDoor, LockingChainIssue, IssuingChainDoor, IssuingChainIssue}', isXChainBridge);
+    assertValidXChainBridge(props.XChainBridge);
+    // ── Account must equal LockingChainDoor (locking-chain submission).
+    //    xrpl.org line 15: "This transaction must be sent by the door
+    //    account." The example JSON shows `Account === LockingChainDoor`.
+    if (props.Account !== props.XChainBridge.LockingChainDoor) {
+        throw new ValidationError('XChainModifyBridge: Account must equal XChainBridge.LockingChainDoor (transaction must be submitted by the locking-chain door account)');
+    }
+    // ── SignatureReward ── required, non-negative XRP drops string.
+    if (!isNonNegativeXrpAmount(props.SignatureReward)) {
+        throw new ValidationError('XChainModifyBridge: SignatureReward must be a non-negative XRP drops string (in XRP, ≥ 0; XLS-38 §2.1.1.1.3 line 200)');
+    }
+    // ── MinAccountCreateAmount ── optional. When present, must be a
+    //    non-negative XRP drops string. The spec limits this field to
+    //    XRP-XRP bridges (xrpl.org line 48 / XLS-38 §2.1.1.1.4 line 204).
+    //    We do not detect IOU-IOU bridges here; the IOU form of the
+    //    amount is rejected by the XRP-drops format check.
+    if (props.MinAccountCreateAmount !== undefined) {
+        if (!isNonNegativeXrpAmount(props.MinAccountCreateAmount)) {
+            throw new ValidationError('XChainModifyBridge: MinAccountCreateAmount must be a non-negative XRP drops string (in XRP, ≥ 0; XRP-XRP bridges only — xrpl.org line 48)');
+        }
+    }
+    // ── Flags ── optional. We accept both numeric and boolean-map
+    //    forms. The factory stores the original form (numeric or object)
+    //    so `.with({ Flags: { tfClearAccountCreateAmount: true } })`
+    //    round-trips verbatim. We do NOT enforce a specific value or
+    //    require the field (parity with sibling factories such as
+    //    `nftokenMint` and `vaultCreate`). Note: XLS-38 §2.2.2.1 marks
+    //    Flags as required; we keep it optional here for parity with
+    //    the rest of the fp codebase — see Spec Ambiguities #3.
+    return buildFrozenTx('XChainModifyBridge', 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 xchainModifyBridge(mergeForWith(this, overrides));
+        },
+    });
+}
+//# sourceMappingURL=xchain-modify-bridge.js.map

package/dist/fp/factories/xchain-modify-bridge.js.map

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