import { XrplNetwork, Wallet } from 'xpring-common-js'; import { GrpcNetworkClientInterface } from './network-clients/grpc-network-client-interface'; import TransactionResult from './shared/transaction-result'; import GatewayBalances from './shared/gateway-balances'; import TrustLine from './shared/trustline'; import { TransactionResponse } from './shared/rippled-web-socket-schema'; import { WebSocketNetworkClientInterface } from './network-clients/web-socket-network-client-interface'; import IssuedCurrency from './shared/issued-currency'; /** * IssuedCurrencyClient is a client for working with Issued Currencies on the XRPL. * @see https://xrpl.org/issued-currencies-overview.html */ export default class IssuedCurrencyClient { readonly webSocketNetworkClient: WebSocketNetworkClientInterface; readonly network: XrplNetwork; private coreXrplClient; /** * Create a new IssuedCurrencyClient. * * The IssuedCurrencyClient will use gRPC to communicate with the given endpoint. * * @param grpcUrl The URL of the gRPC instance to connect to. * @param network The network this IssuedCurrencyClient is connecting to. * @param forceWeb If `true`, then we will use the gRPC-Web client even when on Node. Defaults to false. This is mainly for testing and in the future will be removed when we have browser testing. */ static issuedCurrencyClientWithEndpoint(grpcUrl: string, webSocketUrl: string, handleWebSocketErrorMessage: (data: string) => void, network: XrplNetwork, forceWeb?: boolean): IssuedCurrencyClient; /** * Create a new IssuedCurrencyClient with a custom network client implementation. * * In general, clients should prefer to call `issuedCurrencyClientWithEndpoint`. This constructor is provided to improve testability of this class. * * @param networkClient A network client which will manage remote RPCs to Rippled. * @param network The network this IssuedCurrencyClient is connecting to. */ constructor(grpcNetworkClient: GrpcNetworkClientInterface, webSocketNetworkClient: WebSocketNetworkClientInterface, network: XrplNetwork); /** * Retrieves information about an account's trust lines, which maintain balances of all non-XRP currencies and assets. * @see https://xrpl.org/trust-lines-and-issuing.html * * @param account The account for which to retrieve associated trust lines, encoded as an X-Address. * @param peerAccount (Optional) The address of a second account, encoded as an X-Address. * If provided, show only trust lines connecting the two accounts. * @see https://xrpaddress.info/ * @returns An array of TrustLine objects, representing all trust lines associated with this account. */ getTrustLines(account: string, peerAccount?: string): Promise>; /** * Returns information about the total balances issued by a given account, * optionally excluding amounts held by operational addresses. * @see https://xrpl.org/issuing-and-operational-addresses.html * * @param account The account for which to retrieve balance information, encoded as an X-Address. * @param accountsToExclude (Optional) An array of operational addresses to exclude from the balances issued, encoded as X-Addresses. * @see https://xrpaddress.info/ * @returns A GatewayBalances object containing information about an account's balances. */ getGatewayBalances(account: string, accountsToExclude?: Array): Promise; /** * Subscribes to all transactions that affect the specified account, and triggers a callback upon * receiving each transaction. * @see https://xrpl.org/monitor-incoming-payments-with-websocket.html * @see https://xrpl.org/subscribe.html * * @param account The account for which to subscribe to relevant transactions, encoded as an X-Address. * @param callback The function to trigger upon receiving a transaction event from the ledger. * @returns Whether the request to subscribe succeeded. */ monitorAccountTransactions(account: string, callback: (data: TransactionResponse) => void): Promise; /** * Unsubscribes from transactions that affect the specified account. * @see https://xrpl.org/unsubscribe.html * * @param account The account from which to unsubscribe from, encoded as an X-Address. * @returns Whether the request to unsubscribe succeeded. */ stopMonitoringAccountTransactions(account: string): Promise; /** * Enable Require Authorization for this XRPL account. * * @see https://xrpl.org/become-an-xrp-ledger-gateway.html#require-auth * * @param wallet The wallet associated with the XRPL account enabling Require Authorization and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ requireAuthorizedTrustlines(wallet: Wallet): Promise; /** * Disable Require Authorization for this XRPL account. * * @see https://xrpl.org/become-an-xrp-ledger-gateway.html#require-auth * * @param wallet The wallet associated with the XRPL account disabling Require Authorization and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ allowUnauthorizedTrustlines(wallet: Wallet): Promise; /** * Enable Default Ripple for this XRPL account. * * @see https://xrpl.org/become-an-xrp-ledger-gateway.html#default-ripple * * @param wallet The wallet associated with the XRPL account enabling Default Ripple and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ enableRippling(wallet: Wallet): Promise; /** * Enable Disallow XRP for this XRPL account. * Note that the meaning of this flag is not enforced by rippled, and is only intended for use by client applications. * * @see https://xrpl.org/become-an-xrp-ledger-gateway.html#disallow-xrp * * @param wallet The wallet associated with the XRPL account enabling Disallow XRP and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ disallowIncomingXrp(wallet: Wallet): Promise; /** * Disable Disallow XRP for this XRPL account. * Note that the meaning of this flag is not enforced by rippled, and is only intended for use by client applications. * * @see https://xrpl.org/become-an-xrp-ledger-gateway.html#disallow-xrp * * @param wallet The wallet associated with the XRPL account disabling Disallow XRP and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ allowIncomingXrp(wallet: Wallet): Promise; /** * Enable Require Destination Tags for this XRPL account. * * @see https://xrpl.org/require-destination-tags.html * * @param wallet The wallet associated with the XRPL account enabling Require Destination Tags and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ requireDestinationTags(wallet: Wallet): Promise; /** * Disable Require Destination for this XRPL account. * * @see https://xrpl.org/require-destination-tags.html * * @param wallet The wallet associated with the XRPL account disabling Require Destination and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ allowNoDestinationTag(wallet: Wallet): Promise; /** * Get the Transfer Fees for a given issuing account. * The Transfer Fee is a percentage to charge when two users transfer an issuer's IOUs on the XRPL. * * @see https://xrpl.org/transfer-fees.html * * @param address The X-address for which the transfer rate is requested. * @returns A promise which resolves to a number that represents the transfer fee associated with that issuing account, * or undefined if one is not specified. */ getTransferFee(address: string): Promise; /** * Set the Transfer Fees for an issuing account. * The Transfer Fee is a percentage to charge when two users transfer an issuer's IOUs on the XRPL. * * @see https://xrpl.org/transfer-fees.html * * @param transferFee The amount you must send for the recipient to get 1 billion units of the same currency. * It cannot be set to less than 1000000000 or more than 2000000000. * @param wallet The wallet associated with the issuing account, and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ setTransferFee(transferFee: number, wallet: Wallet): Promise; /** * Enable Global Freeze for this XRPL account. * * @see https://xrpl.org/freezes.html#global-freeze * * @param wallet The wallet associated with the XRPL account enabling Global Freeze and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ enableGlobalFreeze(wallet: Wallet): Promise; /** * Disable Global Freeze for this XRPL account. * * @see https://xrpl.org/freezes.html#global-freeze * * @param wallet The wallet associated with the XRPL account disabling Global Freeze and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ disableGlobalFreeze(wallet: Wallet): Promise; /** * Permanently enable No Freeze for this XRPL account. * * @see https://xrpl.org/freezes.html#no-freeze * * @param wallet The wallet associated with the XRPL account enabling No Freeze and that will sign the request. * @returns A promise which resolves to a TransactionResult object that represents the result of this transaction. */ enableNoFreeze(wallet: Wallet): Promise; /** * Creates a trust line between this XRPL account and an issuer of an IssuedCurrency. * * @see https://xrpl.org/trustset.html * * @param issuerXAddress The X-Address of the issuer to extend trust to. * @param currencyName The currency this trust line applies to, as a three-letter ISO 4217 Currency Code or a 160-bit hex value according to currency format. * @param amount Decimal representation of the limit to set on this trust line. * @param wallet The wallet creating the trustline. * @param qualityIn (Optional) Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. * A value of 0 is shorthand for treating balances at face value. * @param qualityOut (Optional) Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. * A value of 0 is shorthand for treating balances at face value. */ createTrustLine(issuerXAddress: string, currencyName: string, amount: string, wallet: Wallet, qualityIn?: number, qualityOut?: number): Promise; /** * Creates an authorized trust line between this XRPL account (issuing account) and another account. * Note that the other account must also create a trust line to this issuing account in order to establish a trust line with a non-zero limit. * If this method is called before the other account creates a trust line, a trust line with a limit of 0 is created. * However, this is only true if this issuing account has already required Authorized Trustlines (see https://xrpl.org/authorized-trust-lines.html), * otherwise no trust line is created. * * @see https://xrpl.org/authorized-trust-lines.html * * @param accountToAuthorize The X-Address of the address with which to authorize a trust line. * @param currencyName The currency to authorize a trust line for. * @param wallet The wallet creating the authorized trust line. */ authorizeTrustLine(accountToAuthorize: string, currencyName: string, wallet: Wallet): Promise; /** * Freezes the trust line between this account (issuing account) and another account. * Note that the trust line's limit is set to 0. * * @see https://xrpl.org/freezes.html#enabling-or-disabling-individual-freeze * * @param trustLinePeerAccount The X-Address of the account involved in the trust line being frozen. * @param currencyName The currency of the trust line to freeze. * @param wallet The wallet freezing the trust line. */ freezeTrustLine(trustLinePeerAccount: string, currencyName: string, wallet: Wallet): Promise; /** * Unfreezes the trust line between this account (issuing account) and another account. * Note that the trust line's limit is set to 0. * * @see https://xrpl.org/freezes.html#enabling-or-disabling-individual-freeze * * @param trustLinePeerAccount The X-Address of the account involved in the trust line being unfrozen. * @param currencyName The currency of the trust line to unfreeze. * @param wallet The wallet unfreezing the trust line. */ unfreezeTrustLine(trustLinePeerAccount: string, currencyName: string, wallet: Wallet): Promise; /** * Disables rippling on the trust line between this account (issuing account) and another account. * * @see https://xrpl.org/rippling.html#enabling-disabling-no-ripple * * @param trustLinePeerAccount The X-Address of the account involved in the trust line being disabled to ripple. * @param currencyName The currency of the trust line being disbaled to ripple. * @param amount The maximum amount of debt to allow on this trust line. * @param wallet The wallet disabling rippling on the trust line. */ disableRipplingForTrustLine(trustLinePeerAccount: string, currencyName: string, amount: string, wallet: Wallet): Promise; /** * Re-enables rippling on the trust line between this account (issuing account) and another account. * * @see https://xrpl.org/rippling.html#enabling-disabling-no-ripple * * @param trustLinePeerAccount trustLinePeerAccount The X-Address of the account involved in the trust line being re-enabled to ripple. * @param currencyName The currency of the trust line being re-enabled to ripple. * @param amount The maximum amount of debt to allow on this trust line. * @param wallet The wallet re-enabling rippling on the trust line. */ enableRipplingForTrustLine(trustLinePeerAccount: string, currencyName: string, amount: string, wallet: Wallet): Promise; private sendTrustSetTransaction; /** * Prepares a TrustSet transaction to be sent and executed on the XRPL. * * @param accountToTrust The account to extend trust to with a trust line. * @param currencyName The name of the currency to create a trust line for. * @param amount The maximum amount of debt to allow on this trust line. * @param wallet A wallet associated with the account extending trust. * @param qualityIn (Optional) Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. * A value of 0 is shorthand for treating balances at face value. * @param qualityOut (Optional) Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. * A value of 0 is shorthand for treating balances at face value. */ private prepareTrustSetTransaction; /** * Creates new issued currency on a trustline to the destination account. Note that the destination account must have a trustline * extended to the sender of this transaction (the "issuer" of this issued currency) or no issued currency will be created. * * @param sender The Wallet creating the issued currency, and that will sign the transaction. * @param destination The destination address (recipient) of the issued currency, encoded as an X-address (see https://xrpaddress.info/). * @param currency The three-letter currency code of the issued currency being created. * @param amount The amount of issued currency to create. */ createIssuedCurrency(sender: Wallet, destination: string, currency: string, amount: string): Promise; /** * Redeems issued currency back to the original issuer. * Typically, this should trigger off-ledger action by the issuing institution. * * @param sender The Wallet redeeming the issued currency, and that will sign the transaction. * @param issuer The original issuer of the issued currency, encoded as an X-address (see https://xrpaddress.info/). * @param currency The three-letter currency code of the issued currency being redeemed. * @param amount The amount of issued currency to redeem. */ redeemIssuedCurrency(sender: Wallet, issuedCurrency: IssuedCurrency): Promise; /** * Sends issued currency from one (non-issuing) account to another. * * @param sender The Wallet from which issued currency will be sent, and that will sign the transaction. * @param destination The destination address for the payment, encoded as an X-address (see https://xrpaddress.info/). * @param issuedCurrency The issued currency being sent. * @param transferFee (Optional) The transfer fee associated with the issuing account, expressed as a percentage. (i.e. a value of .5 indicates * a 0.5% transfer fee). Supply this field for automatic calculation of the sendMax value for this payment. * Either this or sendMaxvalue may be specified, but not both. * @param sendMaxValue (Optional) A manual specification of the maximum amount of source currency this payment is allowed to cost, * including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting * the transaction. Either this or transferFee may be specified, but not both. */ sendIssuedCurrencyPayment(sender: Wallet, destination: string, issuedCurrency: IssuedCurrency, transferFee?: number, sendMaxValue?: string): Promise; /** * Send a cross-currency payment. Note that the source and destination currencies cannot both be XRP. * The XRPL is queried for viable paths as part of transaction construction. If no paths are found, * an error is thrown and no transaction is submitted. * * @see https://xrpl.org/cross-currency-payments.html * * @param sender The wallet from which currency will be sent, and that will sign the transaction. * @param destination The address of the payment's recipient, encoded as an X-Address. * @param maxSourceAmount Highest amount of source currency this transaction is allowed to cost, including transfer fees, * exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. * For XRP, specify amount as a string of drops. * For issued currencies, specify an IssuedCurrency object with currency, issuer, and value fields. * @param deliverAmount The amount of currency to deliver. For XRP, specify amount as a string of drops. For issued currencies, * specify an IssuedCurrency object with currency, issuer, and value fields. */ sendCrossCurrencyPayment(sender: Wallet, destination: string, maxSourceAmount: string | IssuedCurrency, deliverAmount: string | IssuedCurrency): Promise; /** * Sends issued currency from one account to another. This method can be used to create issued currency, dispense issued currency from * an operational address, send issued currency from one XRPL account to another (as long as the payment only involves a single currency, * i.e. is not cross-currency), or to redeem issued currency at the issuing address. * The specific case being executed is determined by the relationship among the parameters. * * @param sender The Wallet from which issued currency will be sent, and that will sign the transaction. * @param destination The destination address (recipient) for the payment, encoded as an X-address (see https://xrpaddress.info/). * @param issuedCurrency The issued currency being sent. * @param transferFee (Optional) The transfer fee associated with the issuing account, expressed as a percentage. (i.e. a value of .5 indicates * a 0.5% transfer fee). Supply this field for automatic calculation of the sendMax value for this payment. * Either this or sendMaxvalue may be specified, but not both. * @param sendMaxValue (Optional) A manual specification of the maximum amount of source currency this payment is allowed to cost, * including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting \ * the transaction. Either this or transferFee may be specified, but not both. */ issuedCurrencyPayment(sender: Wallet, destination: string, issuedCurrency: IssuedCurrency, transferFee?: number, sendMaxValue?: string): Promise; /** * Calculates the sendMaxValue by applying the transferFee to the amount being sent and ensuring the total amount * fits within maximum decimal precision. * @see https://xrpl.org/currency-formats.html#issued-currency-precision * * @param amount The amount of issued currency to pay to the destination. * @param transferFee The transfer fee associated with the issuing account, expressed as a percentage. * (i.e. a value of .5 indicates a 0.5% transfer fee). */ calculateSendMaxValue(amount: string, transferFee: number): string; /** * Creates an offer on the XRP Ledger. * @see https://xrpl.org/offers.html * @see https://xrpl.org/offercreate.html#offercreate * * @param sender The Wallet creating this offer, and that will sign the transaction. * @param takerGetsAmount The amount and type of currency being provided by the offer creator. * Use a string to specify XRP, or an IssuedCurrency object to specify an issued currency. * @param takerPaysAmount The amount and type of currency being requested by the offer creator. * Use a string to specify XRP, or an IssuedCurrency object to specify an issued currency. * @param offerSequence (Optional) An offer to delete first, specified by the sequence number of a previous OfferCreate transaction. * If specified, cancel any offer object in the ledger that was created by that transaction. * It is not considered an error if the offer specified does not exist. * @param expiration (Optional) Time after which the offer is no longer active, in seconds since the Ripple Epoch. * (See https://xrpl.org/basic-data-types.html#specifying-time) * @param passive (Optional, defaults to false) If enabled, the offer does not consume offers that exactly match it, and instead becomes * an Offer object in the ledger. It still consumes offers that cross it. * @param immediateOrCancel (Optional, defaults to false) Treat the offer as an Immediate or Cancel order. If enabled, the offer never becomes * a ledger object: it only tries to match existing offers in the ledger. If the offer cannot match any offers * immediately, it executes "successfully" without trading any currency. In this case, the transaction has the * result code tesSUCCESS, but creates no Offer objects in the ledger. * (see https://en.wikipedia.org/wiki/Immediate_or_cancel) * @param fillOrKill (Optional, defaults to false) Treat the offer as a Fill or Kill order. Only try to match existing offers in the ledger, * and only do so if the entire TakerPays quantity can be obtained. If the fix1578 amendment is enabled and * the offer cannot be executed when placed, the transaction has the result code tecKILLED; otherwise, the * transaction uses the result code tesSUCCESS even when it was killed without trading any currency. * (see https://en.wikipedia.org/wiki/Fill_or_kill) * @param sell (Optional, defaults to false) Exchange the entire TakerGets amount, even if it means obtaining more than the TakerPays amount in exchange. */ createOffer(sender: Wallet, takerGetsAmount: string | IssuedCurrency, takerPaysAmount: string | IssuedCurrency, offerSequence?: number, expiration?: number, passive?: boolean, immediateOrCancel?: boolean, fillOrKill?: boolean, sell?: boolean): Promise; /** * Cancels an offer on the XRP Ledger. * @see https://xrpl.org/offers.html * @see https://xrpl.org/offercancel.html#offercancel * * @param sender The Wallet cancelling this offer, and that will sign the transaction. * @param offerSequence The sequence number of a previous OfferCreate transaction. * If specified, cancel any offer object in the ledger that was created by that transaction. * It is not considered an error if the offer specified does not exist. */ cancelOffer(sender: Wallet, offerSequence: number): Promise; /** * Constructs and returns a CurrencyAmount protobuf that represents either an XRP drops amount or Issued Currency amount, which can then be * assigned to a higher order protobuf that requires a CurrencyAmount. * * @param amount The string (for XRP amounts) or IssuedCurrency object (for issued currencies) from which to construct a CurrencyAmount protobuf. */ private createCurrencyAmount; /** * Constructs and returns an Amount protocol buffer object with all sub-objects such as an XRPDropsAmount or IssuedCurrencyAmount. * * @param amount The string (for XRP amounts) or IssuedCurrency object (for issued currencies) from which to construct a Amount protobuf. */ private createAmount; }