xrpl 2.11.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xrpl",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "license": "ISC",
   "description": "A TypeScript/JavaScript API for interacting with the XRP Ledger in Node.js and the browser",
   "files": [
@@ -28,9 +28,9 @@
     "bip39": "^3.0.4",
     "https-proxy-agent": "^5.0.0",
     "lodash": "^4.17.4",
-    "ripple-address-codec": "^4.3.0",
-    "ripple-binary-codec": "^1.9.0",
-    "ripple-keypairs": "^1.3.0",
+    "ripple-address-codec": "^4.3.1",
+    "ripple-binary-codec": "^1.10.0",
+    "ripple-keypairs": "^1.3.1",
     "ws": "^8.2.2",
     "xrpl-secret-numbers": "^0.3.3"
   },
@@ -47,7 +47,7 @@
     "karma-webpack": "^5.0.0",
     "node-polyfill-webpack-plugin": "^2.0.1",
     "react": "^18.2.0",
-    "typedoc": "^0.24.6"
+    "typedoc": "^0.25.0"
   },
   "resolutions": {
     "elliptic": "^6.5.4"
@@ -82,6 +82,5 @@
   "readmeFilename": "README.md",
   "engines": {
     "node": ">=10.13.0"
-  },
-  "gitHead": "37fbc03584f4671317576a97ad2cdb3f6c1e1bed"
+  }
 }

package/src/models/common/index.ts

@@ -2,6 +2,7 @@ export type LedgerIndex = number | ('validated' | 'closed' | 'current')
 
 export interface XRP {
   currency: 'XRP'
+  issuer?: never
 }
 
 export interface IssuedCurrency {
@@ -144,6 +145,13 @@ export interface NFToken {
 
 export interface AuthAccount {
   AuthAccount: {
-    account: string
+    Account: string
   }
 }
+
+export interface XChainBridge {
+  LockingChainDoor: string
+  LockingChainIssue: Currency
+  IssuingChainDoor: string
+  IssuingChainIssue: Currency
+}

package/src/models/ledger/AMM.ts

@@ -1,4 +1,4 @@
-import { AuthAccount, Currency } from '../common'
+import { AuthAccount, Currency, IssuedCurrencyAmount } from '../common'
 
 import BaseLedgerEntry from './BaseLedgerEntry'
 
@@ -20,7 +20,7 @@ export default interface AMM extends BaseLedgerEntry {
   /**
    * The address of the special account that holds this AMM's assets.
    */
-  AMMAccount: string
+  Account: string
   /**
    * The definition for one of the two assets this AMM holds.
    */
@@ -53,7 +53,7 @@ export default interface AMM extends BaseLedgerEntry {
     /**
      * The amount the auction owner paid to win this slot, in LP Tokens.
      */
-    Price: Currency
+    Price: IssuedCurrencyAmount
   }
   /**
    * The total outstanding balance of liquidity provider tokens from this AMM instance.
@@ -75,4 +75,12 @@ export default interface AMM extends BaseLedgerEntry {
    * type, so this value is always 0.
    */
   Flags: 0
+  /**
+   * This field is missing on AMM but is present on all other account_object returned objects.
+   */
+  PreviousTxnID: never
+  /**
+   * This field is missing on AMM but is present on all other account_object returned objects.
+   */
+  PreviousTxnLgrSeq: never
 }

package/src/models/ledger/AccountRoot.ts

@@ -38,6 +38,12 @@ export default interface AccountRoot extends BaseLedgerEntry {
    * `asfAccountTxnID` flag enabled.
    */
   AccountTxnID?: string
+  /**
+   * The ledger entry ID of the corresponding AMM ledger entry.
+   * Set during account creation; cannot be modified.
+   * If present, indicates that this is a special AMM AccountRoot; always omitted on non-AMM accounts.
+   */
+  AMMID?: string
   /**
    * A domain associated with this account. In JSON, this is the hexadecimal
    * for the ASCII representation of the domain.

package/src/models/ledger/Bridge.ts

@@ -0,0 +1,84 @@
+import { Amount, XChainBridge } from '../common'
+
+import BaseLedgerEntry from './BaseLedgerEntry'
+
+/**
+ * A Bridge objects represents a cross-chain bridge and includes information about
+ * the door accounts, assets, signature rewards, and the minimum account create
+ * amount.
+ *
+ * @category Ledger Entries
+ */
+export default interface Bridge extends BaseLedgerEntry {
+  LedgerEntryType: 'Bridge'
+
+  /** The door account that owns the bridge. */
+  Account: string
+
+  /**
+   * The total amount, in XRP, to be rewarded for providing a signature for
+   * cross-chain transfer or for signing for the cross-chain reward. This amount
+   * will be split among the signers.
+   */
+  SignatureReward: Amount
+
+  /**
+   * The minimum amount, in XRP, required for an {@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?: string
+
+  /**
+   * The door accounts and assets of the bridge this object correlates to.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The value of the next XChainClaimID to be created.
+   */
+  XChainClaimID: string
+
+  /**
+   * A counter used to order the execution of account create transactions. It is
+   * incremented every time a successful {@link XChainAccountCreateCommit}
+   * transaction is run for the source chain.
+   */
+  XChainAccountCreateCount: string
+
+  /**
+   * A counter used to order the execution of account create transactions. It is
+   * incremented every time a {@link XChainAccountCreateCommit} transaction is
+   * "claimed" on the destination chain. When the "claim" transaction is run on
+   * the destination chain, the XChainAccountClaimCount must match the value that
+   * the XChainAccountCreateCount had at the time the XChainAccountClaimCount was
+   * run on the source chain. This orders the claims so that they run in the same
+   * order that the XChainAccountCreateCommit transactions ran on the source chain,
+   * to prevent transaction replay.
+   */
+  XChainAccountClaimCount: string
+
+  /**
+   * A bit-map of boolean flags. No flags are defined for Bridges, so this value
+   * is always 0.
+   */
+  Flags: 0
+
+  /**
+   * A hint indicating which page of the sender's owner directory links to this
+   * object, in case the directory consists of multiple pages.
+   */
+  OwnerNode: string
+
+  /**
+   * The identifying hash of the transaction that most recently modified this
+   * object.
+   */
+  PreviousTxnID: string
+
+  /**
+   * The index of the ledger that contains the transaction that most recently
+   * modified this object.
+   */
+  PreviousTxnLgrSeq: number
+}

package/src/models/ledger/LedgerEntry.ts

@@ -1,6 +1,7 @@
 import AccountRoot from './AccountRoot'
 import Amendments from './Amendments'
 import AMM from './AMM'
+import Bridge from './Bridge'
 import Check from './Check'
 import DepositPreauth from './DepositPreauth'
 import DirectoryNode from './DirectoryNode'
@@ -13,11 +14,14 @@ import PayChannel from './PayChannel'
 import RippleState from './RippleState'
 import SignerList from './SignerList'
 import Ticket from './Ticket'
+import XChainOwnedClaimID from './XChainOwnedClaimID'
+import XChainOwnedCreateAccountClaimID from './XChainOwnedCreateAccountClaimID'
 
 type LedgerEntry =
   | AccountRoot
   | Amendments
   | AMM
+  | Bridge
   | Check
   | DepositPreauth
   | DirectoryNode
@@ -30,5 +34,7 @@ type LedgerEntry =
   | RippleState
   | SignerList
   | Ticket
+  | XChainOwnedClaimID
+  | XChainOwnedCreateAccountClaimID
 
 export default LedgerEntry

package/src/models/ledger/XChainOwnedClaimID.ts

@@ -0,0 +1,89 @@
+import { Amount } from 'ripple-binary-codec/dist/types'
+
+import { XChainBridge } from '../common'
+
+import BaseLedgerEntry from './BaseLedgerEntry'
+
+/**
+ * An XChainOwnedClaimID object represents one cross-chain transfer of value
+ * and includes information of the account on the source chain that locks or
+ * burns the funds on the source chain.
+ *
+ * @category Ledger Entries
+ */
+export default interface XChainOwnedClaimID extends BaseLedgerEntry {
+  LedgerEntryType: 'XChainOwnedClaimID'
+
+  /** The account that checked out this unique claim ID value. */
+  Account: string
+
+  /**
+   * The door accounts and assets of the bridge this object correlates to.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * The unique sequence number for a cross-chain transfer.
+   */
+  XChainClaimID: string
+
+  /**
+   * The account that must send the corresponding {@link XChainCommit} on the
+   * source chain. The destination may be specified in the {@link XChainCommit}
+   * transaction, which means that if the OtherChainSource isn't specified,
+   * another account can try to specify a different destination and steal the
+   * funds. This also allows tracking only a single set of signatures, since we
+   * know which account will send the {@link XChainCommit} transaction.
+   */
+  OtherChainSource: string
+
+  /**
+   * Attestations collected from the witness servers. This includes the parameters
+   * needed to recreate the message that was signed, including the amount, which
+   * chain (locking or issuing), optional destination, and reward account for that
+   * signature.
+   */
+  XChainClaimAttestations: Array<{
+    // TODO: add docs
+    XChainClaimProofSig: {
+      Amount: Amount
+
+      AttestationRewardAccount: string
+
+      AttestationSignerAccount: string
+
+      Destination?: string
+
+      PublicKey: string
+
+      WasLockingChainSend: 0 | 1
+    }
+  }>
+
+  /**
+   * The total amount to pay the witness servers for their signatures. It must be at
+   * least the value of the SignatureReward in the {@link Bridge} ledger object.
+   */
+  SignatureReward: string
+
+  /**
+   * A bit-map of boolean flags. No flags are defined for XChainOwnedClaimIDs,
+   * so this value is always 0.
+   */
+  Flags: 0
+  /**
+   * A hint indicating which page of the sender's owner directory links to this
+   * object, in case the directory consists of multiple pages.
+   */
+  OwnerNode: string
+  /**
+   * The identifying hash of the transaction that most recently modified this
+   * object.
+   */
+  PreviousTxnID: string
+  /**
+   * The index of the ledger that contains the transaction that most recently
+   * modified this object.
+   */
+  PreviousTxnLgrSeq: number
+}

package/src/models/ledger/XChainOwnedCreateAccountClaimID.ts

@@ -0,0 +1,74 @@
+import { XChainBridge } from '../common'
+
+import BaseLedgerEntry from './BaseLedgerEntry'
+
+/**
+ * The XChainOwnedCreateAccountClaimID ledger object is used to collect attestations
+ * for creating an account via a cross-chain transfer.
+ *
+ * @category Ledger Entries
+ */
+export default interface XChainOwnedCreateAccountClaimID
+  extends BaseLedgerEntry {
+  LedgerEntryType: 'XChainOwnedCreateAccountClaimID'
+
+  /** The account that owns this object. */
+  Account: string
+
+  /**
+   * The door accounts and assets of the bridge this object correlates to.
+   */
+  XChainBridge: XChainBridge
+
+  /**
+   * An integer that determines the order that accounts created through
+   * cross-chain transfers must be performed. Smaller numbers must execute
+   * before larger numbers.
+   */
+  XChainAccountCreateCount: number
+
+  /**
+   * Attestations collected from the witness servers. This includes the parameters
+   * needed to recreate the message that was signed, including the amount, destination,
+   * signature reward amount, and reward account for that signature. With the
+   * exception of the reward account, all signatures must sign the message created with
+   * common parameters.
+   */
+  XChainCreateAccountAttestations: Array<{
+    // TODO: add docs
+    XChainCreateAccountProofSig: {
+      Amount: string
+
+      AttestationRewardAccount: string
+
+      AttestationSignerAccount: string
+
+      Destination: string
+
+      PublicKey: string
+
+      WasLockingChainSend: 0 | 1
+    }
+  }>
+
+  /**
+   * A bit-map of boolean flags. No flags are defined for,
+   * XChainOwnedCreateAccountClaimIDs, so this value is always 0.
+   */
+  Flags: 0
+  /**
+   * A hint indicating which page of the sender's owner directory links to this
+   * object, in case the directory consists of multiple pages.
+   */
+  OwnerNode: string
+  /**
+   * The identifying hash of the transaction that most recently modified this
+   * object.
+   */
+  PreviousTxnID: string
+  /**
+   * The index of the ledger that contains the transaction that most recently
+   * modified this object.
+   */
+  PreviousTxnLgrSeq: number
+}

package/src/models/ledger/index.ts

@@ -3,6 +3,8 @@ import AccountRoot, {
   AccountRootFlagsInterface,
 } from './AccountRoot'
 import Amendments, { Majority, AMENDMENTS_ID } from './Amendments'
+import AMM, { VoteSlot } from './AMM'
+import Bridge from './Bridge'
 import Check from './Check'
 import DepositPreauth from './DepositPreauth'
 import DirectoryNode from './DirectoryNode'
@@ -23,6 +25,8 @@ import PayChannel from './PayChannel'
 import RippleState, { RippleStateFlags } from './RippleState'
 import SignerList, { SignerListFlags } from './SignerList'
 import Ticket from './Ticket'
+import XChainOwnedClaimID from './XChainOwnedClaimID'
+import XChainOwnedCreateAccountClaimID from './XChainOwnedCreateAccountClaimID'
 
 export {
   AccountRoot,
@@ -30,6 +34,8 @@ export {
   AccountRootFlagsInterface,
   AMENDMENTS_ID,
   Amendments,
+  AMM,
+  Bridge,
   Check,
   DepositPreauth,
   DirectoryNode,
@@ -55,4 +61,7 @@ export {
   SignerList,
   SignerListFlags,
   Ticket,
+  XChainOwnedClaimID,
+  XChainOwnedCreateAccountClaimID,
+  VoteSlot,
 }

package/src/models/methods/accountObjects.ts

@@ -1,4 +1,6 @@
 import {
+  AMM,
+  Bridge,
   Check,
   DepositPreauth,
   Escrow,
@@ -7,11 +9,15 @@ import {
   RippleState,
   SignerList,
   Ticket,
+  XChainOwnedClaimID,
+  XChainOwnedCreateAccountClaimID,
 } from '../ledger'
 
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
 
 export type AccountObjectType =
+  | 'amm'
+  | 'bridge'
   | 'check'
   | 'deposit_preauth'
   | 'escrow'
@@ -21,6 +27,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 +72,8 @@ export interface AccountObjectsRequest
  * PayChannel, a SignerList, a Ticket, or a RippleState.
  */
 export type AccountObject =
+  | AMM
+  | Bridge
   | Check
   | DepositPreauth
   | Escrow
@@ -72,6 +82,8 @@ export type AccountObject =
   | SignerList
   | RippleState
   | Ticket
+  | XChainOwnedClaimID
+  | XChainOwnedCreateAccountClaimID
 
 /**
  * Response expected from an {@link AccountObjectsRequest}.

package/src/models/methods/ammInfo.ts

@@ -11,15 +11,20 @@ import { BaseRequest, BaseResponse } from './baseMethod'
 export interface AMMInfoRequest extends BaseRequest {
   command: 'amm_info'
 
+  /**
+   * The address of the AMM Account to look up.
+   */
+  amm_account?: string
+
   /**
    * One of the assets of the AMM pool to look up.
    */
-  asset: Currency
+  asset?: Currency
 
   /**
    * The other asset of the AMM pool.
    */
-  asset2: Currency
+  asset2?: Currency
 }
 
 /**
@@ -93,7 +98,7 @@ export interface AMMInfoResponse extends BaseResponse {
          * The amount, in LP Tokens, that the auction slot holder paid to win the auction slot.
          * This affects the price to outbid the current slot holder.
          */
-        price: Amount
+        price: IssuedCurrencyAmount
 
         /**
          * The current 72-minute time interval this auction slot is in, from 0 to 19.

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_owned_claim_id?:
+    | {
+        locking_chain_door: string
+        locking_chain_issue: Currency
+        issuing_chain_door: string
+        issuing_chain_issue: Currency
+        xchain_owned_claim_id: string | number
+      }
+    | string
+
+  xchain_owned_create_account_claim_id?:
+    | {
+        locking_chain_door: string
+        locking_chain_issue: Currency
+        issuing_chain_door: string
+        issuing_chain_issue: Currency
+        xchain_owned_create_account_claim_id: string | number
+      }
+    | string
 }
 
 /**

package/src/models/methods/serverInfo.ts

@@ -33,6 +33,22 @@ export interface JobType {
   in_progress?: number
 }
 
+export type protocol =
+  | 'http'
+  | 'https'
+  | 'grpc'
+  | 'peer'
+  | 'ws'
+  | 'ws2'
+  | 'wss'
+  | 'wss2'
+
+export interface ServerPort {
+  port: string
+  /** The values in protocol are sorted in alphabetical order */
+  protocol: protocol[]
+}
+
 // The states for validating and proposing do not exist in the field state_accounting
 // See https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/misc/NetworkOPs.cpp#L4545
 // https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/misc/NetworkOPs.h#L66
@@ -181,6 +197,11 @@ export interface ServerInfoResponse extends BaseResponse {
       network_ledger?: 'waiting'
       /** How many other rippled servers this one is currently connected to. */
       peers: number
+      /**
+       * What Websocket/RPC ports rippled is listening on. This allows crawlers to build a richer topology without needing to
+       * port-scan nodes. For non-admin users (including peers), info about admin ports is excluded.
+       */
+      ports: ServerPort[]
       /**
        * Public key used to verify this server for peer-to-peer communications.
        * This node key pair is automatically generated by the server the first

package/src/models/transactions/AMMBid.ts

@@ -1,6 +1,5 @@
-/* eslint-disable complexity -- required for validateAMMBid */
 import { ValidationError } from '../../errors'
-import { Amount, AuthAccount, Currency } from '../common'
+import { AuthAccount, Currency, IssuedCurrencyAmount } from '../common'
 
 import {
   BaseTransaction,
@@ -33,18 +32,18 @@ export interface AMMBid extends BaseTransaction {
   Asset2: Currency
 
   /**
-   * Pay at least this amount for the slot.
+   * Pay at least this LPToken amount for the slot.
    * Setting this value higher makes it harder for others to outbid you.
    * If omitted, pay the minimum necessary to win the bid.
    */
-  BidMin?: Amount
+  BidMin?: IssuedCurrencyAmount
 
   /**
-   * Pay at most this amount for the slot.
+   * Pay at most this LPToken amount for the slot.
    * If the cost to win the bid is higher than this amount, the transaction fails.
    * If omitted, pay as much as necessary to win the bid.
    */
-  BidMax?: Amount
+  BidMax?: IssuedCurrencyAmount
 
   /**
    * A list of up to 4 additional accounts that you allow to trade at the discounted fee.

package/src/models/transactions/AMMDeposit.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- required for validateAMMDeposit */
 import { ValidationError } from '../../errors'
 import { Amount, Currency, IssuedCurrencyAmount } from '../common'
 

package/src/models/transactions/AMMWithdraw.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- required for validateAMMWithdraw */
 import { ValidationError } from '../../errors'
 import { Amount, Currency, IssuedCurrencyAmount } from '../common'
 

package/src/models/transactions/XChainAccountCreateCommit.ts

@@ -0,0 +1,69 @@
+import { isString } from 'lodash'
+
+import { Amount, XChainBridge } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isXChainBridge,
+  validateBaseTransaction,
+  validateRequiredField,
+} 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 an XChainAccountCreateCommit at runtime.
+ *
+ * @param tx - An XChainAccountCreateCommit Transaction.
+ * @throws When the XChainAccountCreateCommit is malformed.
+ */
+export function validateXChainAccountCreateCommit(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'XChainBridge', isXChainBridge)
+
+  validateRequiredField(tx, 'SignatureReward', isAmount)
+
+  validateRequiredField(tx, 'Destination', isString)
+
+  validateRequiredField(tx, 'Amount', isAmount)
+}