xrpl 2.11.0 → 2.12.0-beta.0

package/src/models/methods/accountObjects.ts

@@ -1,4 +1,5 @@
 import {
+  Bridge,
   Check,
   DepositPreauth,
   Escrow,
@@ -7,11 +8,14 @@ import {
   RippleState,
   SignerList,
   Ticket,
+  XChainOwnedClaimID,
+  XChainOwnedCreateAccountClaimID,
 } from '../ledger'
 
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
 
 export type AccountObjectType =
+  | 'bridge'
   | 'check'
   | 'deposit_preauth'
   | 'escrow'
@@ -21,6 +25,8 @@ export type AccountObjectType =
   | 'signer_list'
   | 'state'
   | 'ticket'
+  | 'xchain_owned_create_account_claim_id'
+  | 'xchain_owned_claim_id'
 
 /**
  * The account_objects command returns the raw ledger format for all objects
@@ -64,6 +70,7 @@ export interface AccountObjectsRequest
  * PayChannel, a SignerList, a Ticket, or a RippleState.
  */
 export type AccountObject =
+  | Bridge
   | Check
   | DepositPreauth
   | Escrow
@@ -72,6 +79,8 @@ export type AccountObject =
   | SignerList
   | RippleState
   | Ticket
+  | XChainOwnedClaimID
+  | XChainOwnedCreateAccountClaimID
 
 /**
  * Response expected from an {@link AccountObjectsRequest}.

package/src/models/methods/ledgerEntry.ts

@@ -1,3 +1,4 @@
+import { Currency, XChainBridge } from '../common'
 import { LedgerEntry } from '../ledger'
 
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
@@ -152,6 +153,30 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
    * Must be the object ID of the NFToken page, as hexadecimal
    */
   nft_page?: string
+
+  bridge_account?: string
+
+  bridge?: XChainBridge
+
+  xchain_claim_id?:
+    | {
+        locking_chain_door: string
+        locking_chain_issue: Currency
+        issuing_chain_door: string
+        issuing_chain_issue: Currency
+        xchain_claim_id: string | number
+      }
+    | string
+
+  xchain_create_account_claim_id?:
+    | {
+        locking_chain_door: string
+        locking_chain_issue: Currency
+        issuing_chain_door: string
+        issuing_chain_issue: Currency
+        xchain_create_account_claim_id: string | number
+      }
+    | string
 }
 
 /**

package/src/models/transactions/XChainAccountCreateCommit.ts

@@ -0,0 +1,107 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainAccountCreateCommit transaction creates a new account on one of the
+ * chains a bridge connects, which serves as the bridge entrance for that chain.
+ *
+ * Warning: This transaction should only be executed if the witness attestations
+ * will be reliably delivered to the destination chain. If the signatures aren't
+ * delivered, then account creation will be blocked until attestations are received.
+ * This can be used maliciously; to disable this transaction on XRP-XRP bridges,
+ * the bridge's MinAccountCreateAmount shouldn't be present.
+ *
+ * @category Transaction Models
+ */
+export interface XChainAccountCreateCommit extends BaseTransaction {
+  TransactionType: 'XChainAccountCreateCommit'
+
+  /**
+   * The bridge to create accounts for.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The amount, in XRP, to be used to reward the witness servers for providing
+   * signatures. This must match the amount on the {@link Bridge} ledger object.
+   */
+  SignatureReward: Amount
+
+  /**
+   * The destination account on the destination chain.
+   */
+  Destination: string
+
+  /**
+   * The amount, in XRP, to use for account creation. This must be greater than or
+   * equal to the MinAccountCreateAmount specified in the {@link Bridge} ledger object.
+   */
+  Amount: Amount
+}
+
+/**
+ * Verify the form and type of a XChainAccountCreateCommit at runtime.
+ *
+ * @param tx - A XChainAccountCreateCommit Transaction.
+ * @throws When the XChainAccountCreateCommit is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function --  okay for this function, there's a lot of things to check
+export function validateXChainAccountCreateCommit(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: missing field XChainBridge',
+    )
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: invalid field XChainBridge',
+    )
+  }
+
+  if (tx.SignatureReward == null) {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: missing field SignatureReward',
+    )
+  }
+
+  if (
+    typeof tx.SignatureReward !== 'number' &&
+    typeof tx.SignatureReward !== 'string'
+  ) {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: invalid field SignatureReward',
+    )
+  }
+
+  if (tx.Destination == null) {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: missing field Destination',
+    )
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError(
+      'XChainAccountCreateCommit: invalid field Destination',
+    )
+  }
+
+  if (tx.Amount == null) {
+    throw new ValidationError('XChainAccountCreateCommit: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('XChainAccountCreateCommit: invalid field Amount')
+  }
+}

package/src/models/transactions/XChainAddAccountCreateAttestation.ts

@@ -0,0 +1,225 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainAddAccountCreateAttestation transaction provides an attestation
+ * from a witness server that a {@link XChainAccountCreateCommit} transaction
+ * occurred on the other chain.
+ *
+ * @category Transaction Models
+ */
+export interface XChainAddAccountCreateAttestation extends BaseTransaction {
+  TransactionType: 'XChainAddAccountCreateAttestation'
+
+  /**
+   * The amount committed by the {@link XChainAccountCreateCommit} transaction
+   * on the source chain.
+   */
+  Amount: Amount
+
+  /**
+   * The account that should receive this signer's share of the SignatureReward.
+   */
+  AttestationRewardAccount: string
+
+  /**
+   * The account on the door account's signer list that is signing the transaction.
+   */
+  AttestationSignerAccount: string
+
+  /**
+   * The destination account for the funds on the destination chain.
+   */
+  Destination: string
+
+  /**
+   * The account on the source chain that submitted the {@link XChainAccountCreateCommit}
+   * transaction that triggered the event associated with the attestation.
+   */
+  OtherChainSource: string
+
+  /**
+   * The public key used to verify the signature.
+   */
+  PublicKey: string
+
+  /**
+   * The signature attesting to the event on the other chain.
+   */
+  Signature: string
+
+  /**
+   * The signature reward paid in the {@link XChainAccountCreateCommit} transaction.
+   */
+  SignatureReward: Amount
+
+  /**
+   * A boolean representing the chain where the event occurred.
+   */
+  WasLockingChainSend: 0 | 1
+
+  /**
+   * The counter that represents the order that the claims must be processed in.
+   */
+  XChainAccountCreateCount: number | string
+
+  /**
+   * The bridge associated with the attestation.
+   */
+  XChainBridge: XChainBridge
+}
+
+/**
+ * Verify the form and type of a XChainAddAccountCreateAttestation at runtime.
+ *
+ * @param tx - A XChainAddAccountCreateAttestation Transaction.
+ * @throws When the XChainAddAccountCreateAttestation is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function, max-statements, complexity -- okay for this function, lots of things to check
+export function validateXChainAddAccountCreateAttestation(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field Amount',
+    )
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field Amount',
+    )
+  }
+
+  if (tx.AttestationRewardAccount == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field AttestationRewardAccount',
+    )
+  }
+
+  if (typeof tx.AttestationRewardAccount !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field AttestationRewardAccount',
+    )
+  }
+
+  if (tx.AttestationSignerAccount == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field AttestationSignerAccount',
+    )
+  }
+
+  if (typeof tx.AttestationSignerAccount !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field AttestationSignerAccount',
+    )
+  }
+
+  if (tx.Destination == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field Destination',
+    )
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field Destination',
+    )
+  }
+
+  if (tx.OtherChainSource == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field OtherChainSource',
+    )
+  }
+
+  if (typeof tx.OtherChainSource !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field OtherChainSource',
+    )
+  }
+
+  if (tx.PublicKey == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field PublicKey',
+    )
+  }
+
+  if (typeof tx.PublicKey !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field PublicKey',
+    )
+  }
+
+  if (tx.Signature == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field Signature',
+    )
+  }
+
+  if (typeof tx.Signature !== 'string') {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field Signature',
+    )
+  }
+
+  if (tx.SignatureReward == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field SignatureReward',
+    )
+  }
+
+  if (!isAmount(tx.SignatureReward)) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field SignatureReward',
+    )
+  }
+
+  if (tx.WasLockingChainSend == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field WasLockingChainSend',
+    )
+  }
+
+  if (tx.WasLockingChainSend !== 0 && tx.WasLockingChainSend !== 1) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field WasLockingChainSend',
+    )
+  }
+
+  if (tx.XChainAccountCreateCount == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field XChainAccountCreateCount',
+    )
+  }
+
+  if (
+    typeof tx.XChainAccountCreateCount !== 'string' &&
+    typeof tx.XChainAccountCreateCount !== 'number'
+  ) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field XChainAccountCreateCount',
+    )
+  }
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: missing field XChainBridge',
+    )
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError(
+      'XChainAddAccountCreateAttestation: invalid field XChainBridge',
+    )
+  }
+}

package/src/models/transactions/XChainAddClaimAttestation.ts

@@ -0,0 +1,198 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainAddClaimAttestation transaction provides proof from a witness server,
+ * attesting to an {@link XChainCommit} transaction.
+ *
+ * @category Transaction Models
+ */
+export interface XChainAddClaimAttestation extends BaseTransaction {
+  TransactionType: 'XChainAddClaimAttestation'
+
+  /**
+   * The amount committed by the {@link XChainCommit} transaction on the source chain.
+   */
+  Amount: Amount
+
+  /**
+   * The account that should receive this signer's share of the SignatureReward.
+   */
+  AttestationRewardAccount: string
+
+  /**
+   * The account on the door account's signer list that is signing the transaction.
+   */
+  AttestationSignerAccount: string
+
+  /**
+   * The destination account for the funds on the destination chain (taken from
+   * the {@link XChainCommit} transaction).
+   */
+  Destination?: string
+
+  /**
+   * The account on the source chain that submitted the {@link XChainCommit}
+   * transaction that triggered the event associated with the attestation.
+   */
+  OtherChainSource: string
+
+  /**
+   * The public key used to verify the attestation signature.
+   */
+  PublicKey: string
+
+  /**
+   * The signature attesting to the event on the other chain.
+   */
+  Signature: string
+
+  /**
+   * A boolean representing the chain where the event occurred.
+   */
+  WasLockingChainSend: 0 | 1
+
+  /**
+   * The bridge to use to transfer funds.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The XChainClaimID associated with the transfer, which was included in the
+   * {@link XChainCommit} transaction.
+   */
+  XChainClaimID: number | string
+}
+
+/**
+ * Verify the form and type of a XChainAddClaimAttestation at runtime.
+ *
+ * @param tx - A XChainAddClaimAttestation Transaction.
+ * @throws When the XChainAddClaimAttestation is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function, max-statements, complexity -- okay for this function, lots of things to check
+export function validateXChainAddClaimAttestation(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null) {
+    throw new ValidationError('XChainAddClaimAttestation: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('XChainAddClaimAttestation: invalid field Amount')
+  }
+
+  if (tx.AttestationRewardAccount == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field AttestationRewardAccount',
+    )
+  }
+
+  if (typeof tx.AttestationRewardAccount !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field AttestationRewardAccount',
+    )
+  }
+
+  if (tx.AttestationSignerAccount == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field AttestationSignerAccount',
+    )
+  }
+
+  if (typeof tx.AttestationSignerAccount !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field AttestationSignerAccount',
+    )
+  }
+
+  if (tx.Destination !== undefined && typeof tx.Destination !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field Destination',
+    )
+  }
+
+  if (tx.OtherChainSource == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field OtherChainSource',
+    )
+  }
+
+  if (typeof tx.OtherChainSource !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field OtherChainSource',
+    )
+  }
+
+  if (tx.PublicKey == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field PublicKey',
+    )
+  }
+
+  if (typeof tx.PublicKey !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field PublicKey',
+    )
+  }
+
+  if (tx.Signature == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field Signature',
+    )
+  }
+
+  if (typeof tx.Signature !== 'string') {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field Signature',
+    )
+  }
+
+  if (tx.WasLockingChainSend == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field WasLockingChainSend',
+    )
+  }
+
+  if (tx.WasLockingChainSend !== 0 && tx.WasLockingChainSend !== 1) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field WasLockingChainSend',
+    )
+  }
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field XChainBridge',
+    )
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field XChainBridge',
+    )
+  }
+
+  if (tx.XChainClaimID == null) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: missing field XChainClaimID',
+    )
+  }
+
+  if (
+    typeof tx.XChainClaimID !== 'string' &&
+    typeof tx.XChainClaimID !== 'number'
+  ) {
+    throw new ValidationError(
+      'XChainAddClaimAttestation: invalid field XChainClaimID',
+    )
+  }
+}

package/src/models/transactions/XChainClaim.ts

@@ -0,0 +1,103 @@
+import { ValidationError } from '../../errors'
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * The XChainClaim transaction completes a cross-chain transfer of value. It
+ * allows a user to claim the value on the destination chain - the equivalent
+ * of the value locked on the source chain.
+ *
+ * @category Transaction Models
+ */
+export interface XChainClaim extends BaseTransaction {
+  TransactionType: 'XChainClaim'
+
+  /**
+   * The bridge to use for the transfer.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The unique integer ID for the cross-chain transfer that was referenced in the
+   * corresponding {@link XChainCommit} transaction.
+   */
+  XChainClaimID: number | string
+
+  /**
+   * The destination account on the destination chain. It must exist or the
+   * transaction will fail. However, if the transaction fails in this case, the
+   * sequence number and collected signatures won't be destroyed, and the
+   * transaction can be rerun with a different destination.
+   */
+  Destination: string
+
+  /**
+   * An integer destination tag.
+   */
+  DestinationTag?: number
+
+  /**
+   * The amount to claim on the destination chain. This must match the amount
+   * attested to on the attestations associated with this XChainClaimID.
+   */
+  Amount: Amount
+}
+
+/**
+ * Verify the form and type of a XChainClaim at runtime.
+ *
+ * @param tx - A XChainClaim Transaction.
+ * @throws When the XChainClaim is malformed.
+ */
+// eslint-disable-next-line complexity -- okay for this function, lots of things to check
+export function validateXChainClaim(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.XChainBridge == null) {
+    throw new ValidationError('XChainClaim: missing field XChainBridge')
+  }
+
+  if (!isXChainBridge(tx.XChainBridge)) {
+    throw new ValidationError('XChainClaim: invalid field XChainBridge')
+  }
+
+  if (tx.XChainClaimID == null) {
+    throw new ValidationError('XChainClaim: missing field XChainClaimID')
+  }
+
+  if (
+    typeof tx.XChainClaimID !== 'number' &&
+    typeof tx.XChainClaimID !== 'string'
+  ) {
+    throw new ValidationError('XChainClaim: invalid field XChainClaimID')
+  }
+
+  if (tx.Destination == null) {
+    throw new ValidationError('XChainClaim: missing field Destination')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError('XChainClaim: invalid field Destination')
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError('XChainClaim: invalid field DestinationTag')
+  }
+
+  if (tx.Amount == null) {
+    throw new ValidationError('XChainClaim: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('XChainClaim: invalid field Amount')
+  }
+}