refactor: update according to code review

src/parachain/amm.ts

@@ -111,7 +111,7 @@ export interface AMMAPI {
      * @param {MonetaryAmount<CurrencyExt>} minimumAmountOut Minimum output amount to be received.
      * @param {AddressOrPair} recipient Recipient address.
      * @param {number | string} deadline Deadline block for the swap transaction.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     swap(
         trade: Trade,
@@ -129,7 +129,7 @@ export interface AMMAPI {
      * @param {number} maxSlippage Maximum allowed slippage.
      * @param {number} deadline Deadline block number.
      * @param {AddressOrPair} recipient Recipient of the liquidity pool token.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     addLiquidity(
         amounts: PooledCurrencies,
@@ -147,7 +147,7 @@ export interface AMMAPI {
      * @param {number} maxSlippage Maximum allowed slippage.
      * @param {number} deadline Deadline block number.
      * @param {AddressOrPair} recipient Recipient of the pooled currencies.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @note Removes `amount` of liquidity in LP token, breaks it down and transfers to account.
      */
     removeLiquidity(
@@ -163,7 +163,7 @@ export interface AMMAPI {
      *
      * @param claimableRewards Map of LpToken -> Array of reward monetary amounts -> supposed to be
      *                         output of `getClaimableFarmingRewards`
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     claimFarmingRewards(claimableRewards: Map<LpCurrency, Array<MonetaryAmount<CurrencyExt>>>): ExtrinsicData;
 }

src/parachain/escrow.ts

@@ -30,7 +30,7 @@ export interface EscrowAPI {
     /**
      * @param amount Governance token amount to lock (e.g. KINT or INTR)
      * @param unlockHeight Block number to lock until
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks The amount can't be less than the max period (`getMaxPeriod` getter) to prevent rounding errors
      */
     createLock(amount: MonetaryAmount<GovernanceCurrency>, unlockHeight: number): ExtrinsicData;
@@ -47,7 +47,7 @@ export interface EscrowAPI {
      */
     getTotalStakedBalance(): Promise<MonetaryAmount<GovernanceCurrency>>;
     /**
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks Withdraws all locked governance currency
      */
     withdraw(): ExtrinsicData;
@@ -60,19 +60,19 @@ export interface EscrowAPI {
      */
     getMaxPeriod(): Promise<BN>;
     /**
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks Withdraws stake-to-vote rewards
      */
     withdrawRewards(): ExtrinsicData;
     /**
      * @param amount Governance token amount to lock (e.g. KINT or INTR)
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     increaseAmount(amount: MonetaryAmount<GovernanceCurrency>): ExtrinsicData;
 
     /**
      * @param unlockHeight The unlock height to increase by.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     increaseUnlockHeight(unlockHeight: number): ExtrinsicData;
     /**

src/parachain/issue.ts

@@ -79,7 +79,7 @@ export interface IssueAPI {
      * @param amountsPerVault A mapping of vaults to issue from, and wrapped token amounts to issue using each vault
      * @param atomic Whether the issue request should be handled atomically or not. Only makes a difference if more than
      * one vault is needed to fulfil it.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     requestAdvanced(
         amountsPerVault: Map<InterbtcPrimitivesVaultId, MonetaryAmount<WrappedCurrency>>,
@@ -104,7 +104,7 @@ export interface IssueAPI {
      *
      * @param issueId The ID returned by the issue request transaction
      * @param btcTxId Bitcoin transaction ID
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     execute(requestId: string, btcTxId: string): Promise<ExtrinsicData>;
 
@@ -121,15 +121,15 @@ export interface IssueAPI {
      * the issuance request can be cancelled. As a result, the griefing collateral
      * of the requester will be slashed and sent to the vault that had prepared to issue.
      * @param issueId The ID returned by the issue request transaction
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     cancel(issueId: string): ExtrinsicData;
     /**
      * @remarks Testnet utility function
      * @param blocks The time difference in number of blocks between an issue request is created
      * and required completion time by a user. The issue period has an upper limit
      * to prevent griefing of vault collateral.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     setIssuePeriod(blocks: number): ExtrinsicData;
     /**

src/parachain/loans.ts

@@ -102,7 +102,7 @@ export interface LoansAPI {
      *
      * @param {CurrencyExt} underlyingCurrency  Currency to lend.
      * @param {MonetaryAmount<CurrencyExt>} amount Amount of currency to lend.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is not active market for `underlyingCurrency`.
      * @throws If `amount` is exceeding available balance of account.
      */
@@ -113,7 +113,7 @@ export interface LoansAPI {
      *
      * @param {CurrencyExt} underlyingCurrency Currency to witdhraw.
      * @param {MonetaryAmount<CurrencyExt>} amount Amount of currency to withdraw.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is not active market for `underlyingCurrency`.
      * @throws If `amount` is exceeding lent amount of account.
      * @throws If `underlyingCurrency` is used as collateral and withdrawal of
@@ -127,15 +127,15 @@ export interface LoansAPI {
      * Same as `withdraw`, but exits full position.
      *
      * @param underlyingCurrency Currency to fully withdraw.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     withdrawAll(underlyingCurrency: CurrencyExt): Promise<ExtrinsicData>;
 
     /**
      * Enable lend position of account as collateral for borrowing.
      *
      * @param underlyingCurrency Currency to enable as collateral.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is no existing lend position for `currency`.
      */
     enableAsCollateral(underlyingCurrency: CurrencyExt): Promise<ExtrinsicData>;
@@ -144,7 +144,7 @@ export interface LoansAPI {
      * Enable lend position of account as collateral for borrowing.
      *
      * @param underlyingCurrency Currency to enable as collateral.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is no existing lend position for `currency`.
      * @throws If disabling lend position of `currency` would bring
      * account under collateral threshold.
@@ -153,7 +153,7 @@ export interface LoansAPI {
 
     /**
      * Claim subsidy rewards for all markets available for account.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     claimAllSubsidyRewards(): ExtrinsicData;
 
@@ -162,7 +162,7 @@ export interface LoansAPI {
      *
      * @param underlyingCurrency Currency to borrow.
      * @param amount Amount of currency to borrow.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is no active market for `underlyingCurrency`.
      * @throws If there is not enough collateral provided by account for
      * `amount` of `underlyingCurrency`.
@@ -176,7 +176,7 @@ export interface LoansAPI {
      *
      * @param underlyingCurrency Currency to repay.
      * @param amount Amount of currency to repay.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws If there is no active market for `underlyingCurrency`.
      * @throws If `amount` is higher than available balance of account.
      * @throws If `amount` is higher than outstanding loan.
@@ -187,7 +187,7 @@ export interface LoansAPI {
      * Same as `repay`, but repays full loan.
      *
      * @param underlyingCurrency Currency to repay.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     repayAll(underlyingCurrency: CurrencyExt): Promise<ExtrinsicData>;
 
@@ -198,7 +198,7 @@ export interface LoansAPI {
      * @param liquidationCurrency Currency of position that will be liquidated.
      * @param repayAmount Amount to be repaid.
      * @param collateralCurrency Collateral currency which will be claimed by liquidator.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     liquidateBorrowPosition(
         borrower: AccountId,

src/parachain/nomination.ts

@@ -42,32 +42,32 @@ export interface NominationAPI {
     /**
      * @param vaultAccountId Vault to nominate collateral to
      * @param amount Amount to deposit, as a `Monetary.js` object or `ForeignAsset`
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     depositCollateral(vaultAccountId: AccountId, amount: MonetaryAmount<CollateralCurrencyExt>): ExtrinsicData;
     /**
      * @param vaultAccountId Vault that collateral was nominated to
      * @param amount Amount to withdraw, as a `Monetary.js` object or `ForeignAsset`
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     withdrawCollateral(
         vaultAccountId: AccountId,
         amount: MonetaryAmount<CollateralCurrencyExt>
     ): Promise<ExtrinsicData>;
     /**
      * @param collateralCurrency Currency to accept as nomination
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks Function callable by vaults to opt in to the nomination feature
      */
     optIn(collateralCurrency: CollateralCurrencyExt): ExtrinsicData;
     /**
      * @param collateralCurrency Currency to stop accepting as nomination
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks Function callable by vaults to opt out of the nomination feature
      */
     optOut(collateralCurrency: CollateralCurrencyExt): ExtrinsicData;
     /**
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @remarks Testnet utility function
      */
     setNominationEnabled(enabled: boolean): ExtrinsicData;

src/parachain/oracle.ts

@@ -53,13 +53,13 @@ export interface OracleAPI {
     /**
      * Create a transaction to set the exchange rate between Bitcoin and a collateral currency
      * @param exchangeRate The rate to set
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     setExchangeRate(exchangeRate: ExchangeRate<Bitcoin, CurrencyExt>): ExtrinsicData;
     /**
      * Create a transaction to set the current fee estimate for BTC transactions
      * @param fees Estimated Satoshis per bytes to get a transaction included
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     setBitcoinFees(fees: Big): ExtrinsicData;
     /**

src/parachain/redeem.ts

@@ -60,7 +60,7 @@ export interface RedeemAPI {
      * @param atomic (optional) Whether the request should be handled atomically or not. Only makes a difference
      * if more than one vault is needed to fulfil it. Defaults to false.
      * @param availableVaults (optional) A list of all vaults usable for redeem. If not provided, will fetch from the parachain.
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     request(
         amount: MonetaryAmount<WrappedCurrency>,
@@ -76,7 +76,7 @@ export interface RedeemAPI {
      * @param btcAddressEnc Bitcoin address where the redeemed BTC should be sent
      * @param atomic Whether the issue request should be handled atomically or not. Only makes a difference if more than
      * one vault is needed to fulfil it.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      * @throws Rejects the promise if none of the requests succeeded (or if at least one failed, when atomic=true).
      */
     requestAdvanced(
@@ -103,7 +103,7 @@ export interface RedeemAPI {
      *
      * @param redeemId The ID generated by the redeem request transaction
      * @param btcTxId Bitcoin transaction ID
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     execute(requestId: string, btcTxId: string): Promise<ExtrinsicData>;
 
@@ -129,7 +129,7 @@ export interface RedeemAPI {
      * @param reimburse (Optional) In case of redeem failure:
      *  - (Default) `false` = retry redeeming, with a different Vault
      *  - `true` = accept reimbursement in wrapped token
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     cancel(redeemId: string, reimburse?: boolean): ExtrinsicData;
     /**
@@ -138,7 +138,7 @@ export interface RedeemAPI {
      * is created and required completion time by a vault.
      * The redeem period has an upper limit to ensure the user gets their BTC in time
      * and to potentially punish a vault for inactivity or stealing BTC.
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     setRedeemPeriod(blocks: number): ExtrinsicData;
     /**
@@ -191,7 +191,7 @@ export interface RedeemAPI {
      * Burn wrapped tokens for a premium
      * @param amount The amount of wrapped tokens to burn
      * @param collateralCurrency Liquidated collateral currency to use when burning wrapped tokens
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     burn(amount: MonetaryAmount<WrappedCurrency>, collateralCurrency: CollateralCurrencyExt): ExtrinsicData;
     /**

src/parachain/replace.ts

@@ -62,7 +62,7 @@ export interface ReplaceAPI {
     /**
      * @param amount Amount issued, denoted in Bitcoin, to have replaced by another vault
      * @param collateralCurrency Collateral currency to have replaced
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     request(amount: MonetaryAmount<WrappedCurrency>, collateralCurrency: CollateralCurrencyExt): ExtrinsicData;
 
@@ -84,7 +84,7 @@ export interface ReplaceAPI {
      * @param amount The amount of wrapped tokens to withdraw from the amount
      * requested to have replaced.
      * @param collateralCurrency Collateral currency of the request
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     withdraw(amount: MonetaryAmount<WrappedCurrency>, collateralCurrency: CollateralCurrencyExt): ExtrinsicData;
 
@@ -110,7 +110,7 @@ export interface ReplaceAPI {
      * @param amount Amount of issued tokens to be replaced
      * @param collateral The collateral for replacement
      * @param btcAddress The address that old-vault should transfer the btc to
-     * @returns {ExtrinsicData} A submittable extrinsic and event.
+     * @returns {ExtrinsicData} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     accept(
         oldVault: AccountId,
@@ -137,7 +137,7 @@ export interface ReplaceAPI {
      *
      * @param requestId The ID generated by the replace request transaction
      * @param btcTxId Bitcoin transaction ID
-     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and event.
+     * @returns {Promise<ExtrinsicData>} A submittable extrinsic and an event that is emitted when extrinsic is submitted.
      */
     execute(requestId: string, btcTxId: string): Promise<ExtrinsicData>;
     /**