xrpl 2.11.0 → 2.12.0-beta.0

package/src/models/transactions/XChainCommit.ts

@@ -0,0 +1,95 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainCommit is the second step in a cross-chain transfer. It puts assets
+ * into trust on the locking chain so that they can be wrapped on the issuing
+ * chain, or burns wrapped assets on the issuing chain so that they can be returned
+ * on the locking chain.
+ *
+ * @category Transaction Models
+ */
+export interface XChainCommit extends BaseTransaction {
+  TransactionType: 'XChainCommit'
+
+  /**
+   * The bridge to use to transfer funds.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The unique integer ID for a cross-chain transfer. This must be acquired on
+   * the destination chain (via a {@link XChainCreateClaimID} transaction) and
+   * checked from a validated ledger before submitting this transaction. If an
+   * incorrect sequence number is specified, the funds will be lost.
+   */
+  XChainClaimID: number | string
+
+  /**
+   * The destination account on the destination chain. If this is not specified,
+   * the account that submitted the {@link XChainCreateClaimID} transaction on the
+   * destination chain will need to submit a {@link XChainClaim} transaction to
+   * claim the funds.
+   */
+  OtherChainDestination?: string
+
+  /**
+   * The asset to commit, and the quantity. This must match the door account's
+   * LockingChainIssue (if on the locking chain) or the door account's
+   * IssuingChainIssue (if on the issuing chain).
+   */
+  Amount: Amount
+}
+
+/**
+ * Verify the form and type of a XChainCommit at runtime.
+ *
+ * @param tx - A XChainCommit Transaction.
+ * @throws When the XChainCommit is malformed.
+ */
+export function validateXChainCommit(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError('XChainCommit: missing field XChainBridge')
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError('XChainCommit: invalid field XChainBridge')
+  }
+
+  if (tx.XChainClaimID == null) {
+    throw new ValidationError('XChainCommit: missing field XChainClaimID')
+  }
+
+  if (
+    typeof tx.XChainClaimID !== 'number' &&
+    typeof tx.XChainClaimID !== 'string'
+  ) {
+    throw new ValidationError('XChainCommit: invalid field XChainClaimID')
+  }
+
+  if (
+    tx.OtherChainDestination !== undefined &&
+    typeof tx.OtherChainDestination !== 'string'
+  ) {
+    throw new ValidationError(
+      'XChainCommit: invalid field OtherChainDestination',
+    )
+  }
+
+  if (tx.Amount == null) {
+    throw new ValidationError('XChainCommit: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('XChainCommit: invalid field Amount')
+  }
+}

package/src/models/transactions/XChainCreateBridge.ts

@@ -0,0 +1,78 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainCreateBridge transaction creates a new {@link Bridge} ledger object
+ * and defines a new cross-chain bridge entrance on the chain that the transaction
+ * is submitted on. It includes information about door accounts and assets for the
+ * bridge.
+ *
+ * @category Transaction Models
+ */
+export interface XChainCreateBridge extends BaseTransaction {
+  TransactionType: 'XChainCreateBridge'
+
+  /**
+   * The bridge (door accounts and assets) to create.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The total amount to pay the witness servers for their signatures. This amount
+   * will be split among the signers.
+   */
+  SignatureReward: Amount
+
+  /**
+   * The minimum amount, in XRP, required for a {@link XChainAccountCreateCommit}
+   * transaction. If this isn't present, the {@link XChainAccountCreateCommit}
+   * transaction will fail. This field can only be present on XRP-XRP bridges.
+   */
+  MinAccountCreateAmount?: Amount
+}
+
+/**
+ * Verify the form and type of a XChainCreateBridge at runtime.
+ *
+ * @param tx - A XChainCreateBridge Transaction.
+ * @throws When the XChainCreateBridge is malformed.
+ */
+export function validateXChainCreateBridge(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError('XChainCreateBridge: missing field XChainBridge')
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError('XChainCreateBridge: invalid field XChainBridge')
+  }
+
+  if (tx.SignatureReward == null) {
+    throw new ValidationError(
+      'XChainCreateBridge: missing field SignatureReward',
+    )
+  }
+
+  if (!isAmount(tx.SignatureReward)) {
+    throw new ValidationError(
+      'XChainCreateBridge: invalid field SignatureReward',
+    )
+  }
+
+  if (
+    tx.MinAccountCreateAmount !== undefined &&
+    !isAmount(tx.MinAccountCreateAmount)
+  ) {
+    throw new ValidationError(
+      'XChainCreateBridge: invalid field MinAccountCreateAmount',
+    )
+  }
+}

package/src/models/transactions/XChainCreateClaimID.ts

@@ -0,0 +1,78 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainCreateClaimID transaction creates a new cross-chain claim ID that is
+ * used for a cross-chain transfer. A cross-chain claim ID represents one
+ * cross-chain transfer of value.
+ *
+ * @category Transaction Models
+ */
+export interface XChainCreateClaimID extends BaseTransaction {
+  TransactionType: 'XChainCreateClaimID'
+
+  /**
+   * The bridge to create the claim ID for.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The amount, in XRP, to reward the witness servers for providing signatures.
+   * This must match the amount on the {@link Bridge} ledger object.
+   */
+  SignatureReward: Amount
+
+  /**
+   * The account that must send the {@link XChainCommit} transaction on the source chain.
+   */
+  OtherChainSource: string
+}
+
+/**
+ * Verify the form and type of a XChainCreateClaimID at runtime.
+ *
+ * @param tx - A XChainCreateClaimID Transaction.
+ * @throws When the XChainCreateClaimID is malformed.
+ */
+export function validateXChainCreateClaimID(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError('XChainCreateClaimID: missing field XChainBridge')
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError('XChainCreateClaimID: invalid field XChainBridge')
+  }
+
+  if (tx.SignatureReward == null) {
+    throw new ValidationError(
+      'XChainCreateClaimID: missing field SignatureReward',
+    )
+  }
+
+  if (!isAmount(tx.SignatureReward)) {
+    throw new ValidationError(
+      'XChainCreateClaimID: invalid field SignatureReward',
+    )
+  }
+
+  if (tx.OtherChainSource == null) {
+    throw new ValidationError(
+      'XChainCreateClaimID: missing field OtherChainSource',
+    )
+  }
+
+  if (typeof tx.OtherChainSource !== 'string') {
+    throw new ValidationError(
+      'XChainCreateClaimID: invalid field OtherChainSource',
+    )
+  }
+}

package/src/models/transactions/XChainModifyBridge.ts

@@ -0,0 +1,93 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * Enum representing values of {@link XChainModifyBridge} transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum XChainModifyBridgeFlags {
+  /** Clears the MinAccountCreateAmount of the bridge. */
+  tfClearAccountCreateAmount = 0x00010000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link XChainModifyBridge} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface XChainModifyBridgeFlagsInterface extends GlobalFlags {
+  /** Clears the MinAccountCreateAmount of the bridge. */
+  tfClearAccountCreateAmount?: boolean
+}
+
+/**
+ * The XChainModifyBridge transaction allows bridge managers to modify the parameters
+ * of the bridge.
+ *
+ * @category Transaction Models
+ */
+export interface XChainModifyBridge extends BaseTransaction {
+  TransactionType: 'XChainModifyBridge'
+
+  /**
+   * The bridge to modify.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The signature reward split between the witnesses for submitting attestations.
+   */
+  SignatureReward?: Amount
+
+  /**
+   * The minimum amount, in XRP, required for a {@link XChainAccountCreateCommit}
+   * transaction. If this is not present, the {@link XChainAccountCreateCommit}
+   * transaction will fail. This field can only be present on XRP-XRP bridges.
+   */
+  MinAccountCreateAmount?: Amount
+
+  Flags?: number | XChainModifyBridgeFlagsInterface
+}
+
+/**
+ * Verify the form and type of a XChainModifyBridge at runtime.
+ *
+ * @param tx - A XChainModifyBridge Transaction.
+ * @throws When the XChainModifyBridge is malformed.
+ */
+export function validateXChainModifyBridge(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError('XChainModifyBridge: missing field XChainBridge')
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError('XChainModifyBridge: invalid field XChainBridge')
+  }
+
+  if (tx.SignatureReward !== undefined && !isAmount(tx.SignatureReward)) {
+    throw new ValidationError(
+      'XChainModifyBridge: invalid field SignatureReward',
+    )
+  }
+
+  if (
+    tx.MinAccountCreateAmount !== undefined &&
+    !isAmount(tx.MinAccountCreateAmount)
+  ) {
+    throw new ValidationError(
+      'XChainModifyBridge: invalid field MinAccountCreateAmount',
+    )
+  }
+}

package/src/models/transactions/common.ts

@@ -4,7 +4,14 @@
 import { TRANSACTION_TYPES } from 'ripple-binary-codec'
 
 import { ValidationError } from '../../errors'
-import { Amount, Currency, IssuedCurrencyAmount, Memo, Signer } from '../common'
+import {
+  Amount,
+  Currency,
+  IssuedCurrencyAmount,
+  Memo,
+  Signer,
+  XChainBridge,
+} from '../common'
 import { onlyHasFields } from '../utils'
 
 const MEMO_SIZE = 3
@@ -53,6 +60,7 @@ function isSigner(obj: unknown): boolean {
 const XRP_CURRENCY_SIZE = 1
 const ISSUE_SIZE = 2
 const ISSUED_CURRENCY_SIZE = 3
+const XCHAIN_BRIDGE_SIZE = 4
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object'
@@ -103,6 +111,23 @@ export function isAmount(amount: unknown): amount is Amount {
   return typeof amount === 'string' || isIssuedCurrency(amount)
 }
 
+/**
+ * Verify the form and type of an XChainBridge at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the XChainBridge is properly formed.
+ */
+export function isXChainBridge(input: unknown): input is XChainBridge {
+  return (
+    isRecord(input) &&
+    Object.keys(input).length === XCHAIN_BRIDGE_SIZE &&
+    typeof input.LockingChainDoor === 'string' &&
+    isCurrency(input.LockingChainIssue) &&
+    typeof input.IssuingChainDoor === 'string' &&
+    isCurrency(input.IssuingChainIssue)
+  )
+}
+
 // eslint-disable-next-line @typescript-eslint/no-empty-interface -- no global flags right now, so this is fine
 export interface GlobalFlags {}
 

package/src/models/transactions/index.ts

@@ -25,6 +25,7 @@ export {
 export { CheckCancel } from './checkCancel'
 export { CheckCash } from './checkCash'
 export { CheckCreate } from './checkCreate'
+export { Clawback } from './clawback'
 export { DepositPreauth } from './depositPreauth'
 export { EscrowCancel } from './escrowCancel'
 export { EscrowCreate } from './escrowCreate'
@@ -63,4 +64,15 @@ export { SignerListSet } from './signerListSet'
 export { TicketCreate } from './ticketCreate'
 export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet'
 export { UNLModify } from './UNLModify'
-export { Clawback } from './clawback'
+export { XChainAddAccountCreateAttestation } from './XChainAddAccountCreateAttestation'
+export { XChainAddClaimAttestation } from './XChainAddClaimAttestation'
+export { XChainClaim } from './XChainClaim'
+export { XChainCommit } from './XChainCommit'
+export { XChainCreateBridge } from './XChainCreateBridge'
+export { XChainCreateClaimID } from './XChainCreateClaimID'
+export { XChainAccountCreateCommit } from './XChainAccountCreateCommit'
+export {
+  XChainModifyBridge,
+  XChainModifyBridgeFlags,
+  XChainModifyBridgeFlagsInterface,
+} from './XChainModifyBridge'

package/src/models/transactions/transaction.ts

@@ -1,4 +1,5 @@
-/* eslint-disable complexity -- verifies 19 tx types hence a lot of checks needed */
+/* eslint-disable max-lines -- need to work with a lot of transactions in a switch statement */
+/* eslint-disable complexity -- verifies many tx types hence a lot of checks needed */
 /* eslint-disable max-lines-per-function -- need to work with a lot of Tx verifications */
 
 import { ValidationError } from '../../errors'
@@ -57,6 +58,32 @@ import { SetRegularKey, validateSetRegularKey } from './setRegularKey'
 import { SignerListSet, validateSignerListSet } from './signerListSet'
 import { TicketCreate, validateTicketCreate } from './ticketCreate'
 import { TrustSet, validateTrustSet } from './trustSet'
+import {
+  XChainAccountCreateCommit,
+  validateXChainAccountCreateCommit,
+} from './XChainAccountCreateCommit'
+import {
+  XChainAddAccountCreateAttestation,
+  validateXChainAddAccountCreateAttestation,
+} from './XChainAddAccountCreateAttestation'
+import {
+  XChainAddClaimAttestation,
+  validateXChainAddClaimAttestation,
+} from './XChainAddClaimAttestation'
+import { XChainClaim, validateXChainClaim } from './XChainClaim'
+import { XChainCommit, validateXChainCommit } from './XChainCommit'
+import {
+  XChainCreateBridge,
+  validateXChainCreateBridge,
+} from './XChainCreateBridge'
+import {
+  XChainCreateClaimID,
+  validateXChainCreateClaimID,
+} from './XChainCreateClaimID'
+import {
+  XChainModifyBridge,
+  validateXChainModifyBridge,
+} from './XChainModifyBridge'
 
 /**
  * @category Transaction Models
@@ -93,6 +120,14 @@ export type Transaction =
   | SignerListSet
   | TicketCreate
   | TrustSet
+  | XChainAddAccountCreateAttestation
+  | XChainAddClaimAttestation
+  | XChainClaim
+  | XChainCommit
+  | XChainCreateBridge
+  | XChainCreateClaimID
+  | XChainAccountCreateCommit
+  | XChainModifyBridge
 
 /**
  * @category Transaction Models
@@ -295,6 +330,38 @@ export function validate(transaction: Record<string, unknown>): void {
       validateTrustSet(tx)
       break
 
+    case 'XChainAddAccountCreateAttestation':
+      validateXChainAddAccountCreateAttestation(tx)
+      break
+
+    case 'XChainAddClaimAttestation':
+      validateXChainAddClaimAttestation(tx)
+      break
+
+    case 'XChainClaim':
+      validateXChainClaim(tx)
+      break
+
+    case 'XChainCommit':
+      validateXChainCommit(tx)
+      break
+
+    case 'XChainCreateBridge':
+      validateXChainCreateBridge(tx)
+      break
+
+    case 'XChainCreateClaimID':
+      validateXChainCreateClaimID(tx)
+      break
+
+    case 'XChainAccountCreateCommit':
+      validateXChainAccountCreateCommit(tx)
+      break
+
+    case 'XChainModifyBridge':
+      validateXChainModifyBridge(tx)
+      break
+
     default:
       throw new ValidationError(
         `Invalid field TransactionType: ${tx.TransactionType}`,

package/src/models/utils/flags.ts

@@ -15,6 +15,7 @@ import { PaymentFlags } from '../transactions/payment'
 import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
 import type { Transaction } from '../transactions/transaction'
 import { TrustSetFlags } from '../transactions/trustSet'
+import { XChainModifyBridgeFlags } from '../transactions/XChainModifyBridge'
 
 import { isFlagEnabled } from '.'
 
@@ -47,6 +48,7 @@ export function parseAccountRootFlags(
  *
  * @param tx - A transaction to set its flags to its numeric representation.
  */
+// eslint-disable-next-line complexity -- there's a lot of txs with flags
 export function setTransactionFlagsToNumber(tx: Transaction): void {
   if (tx.Flags == null) {
     tx.Flags = 0
@@ -78,6 +80,9 @@ export function setTransactionFlagsToNumber(tx: Transaction): void {
     case 'TrustSet':
       tx.Flags = convertFlagsToNumber(tx.Flags, TrustSetFlags)
       return
+    case 'XChainModifyBridge':
+      tx.Flags = convertFlagsToNumber(tx.Flags, XChainModifyBridgeFlags)
+      return
     default:
       tx.Flags = 0
   }