@interlay/interbtc-api / Exports / DefaultVaultsAPI
• new DefaultVaultsAPI(api, electrsAPI, wrappedCurrency, governanceCurrency, tokensAPI, oracleAPI, feeAPI, rewardsAPI, systemAPI, transactionAPI): DefaultVaultsAPI
| Name | Type |
|---|---|
api |
ApiPromise |
electrsAPI |
ElectrsAPI |
wrappedCurrency |
Currency |
governanceCurrency |
Currency |
tokensAPI |
TokensAPI |
oracleAPI |
OracleAPI |
feeAPI |
FeeAPI |
rewardsAPI |
RewardsAPI |
systemAPI |
SystemAPI |
transactionAPI |
TransactionAPI |
• Private api: ApiPromise
• Private electrsAPI: ElectrsAPI
• Private feeAPI: FeeAPI
• Private governanceCurrency: Currency
• Private oracleAPI: OracleAPI
• Private rewardsAPI: RewardsAPI
• Private systemAPI: SystemAPI
• Private tokensAPI: TokensAPI
• Private transactionAPI: TransactionAPI
• Private wrappedCurrency: Currency
▸ backingCollateralProportion(vaultAccountId, nominatorId, collateralCurrency): Promise<Big>
| Name | Type |
|---|---|
vaultAccountId |
AccountId |
nominatorId |
AccountId |
collateralCurrency |
CollateralCurrencyExt |
Promise<Big>
▸ buildAcceptNewIssuesExtrinsic(collateralCurrency, acceptNewIssues): SubmittableExtrinsic<"promise", ISubmittableResult>
Build accept new issues extrinsic without sending it.
| Name | Type | Description |
|---|---|---|
collateralCurrency |
CollateralCurrencyExt |
the collateral currency for which to change the accepting status, |
acceptNewIssues |
boolean |
Boolean denoting whether issuing should be enabled or not |
SubmittableExtrinsic<"promise", ISubmittableResult>
An accept new issues submittable extrinsic.
VaultsAPI.buildAcceptNewIssuesExtrinsic
▸ buildDepositCollateralExtrinsic(amount): SubmittableExtrinsic<"promise", ISubmittableResult>
Build deposit collateral extrinsic (transaction) without sending it.
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<CollateralCurrencyExt> |
The amount of extra collateral to lock |
SubmittableExtrinsic<"promise", ISubmittableResult>
A deposit collateral submittable extrinsic.
VaultsAPI.buildDepositCollateralExtrinsic
▸ buildRegisterPublicKeyExtrinsic(publicKey): SubmittableExtrinsic<"promise", ISubmittableResult>
Build extrinsic to register a public key.
This extrinsic can be used together with a register vault extrinsic (see: buildRegisterVaultExtrinsic) to register the first vault for the logged in account id.
Registering the public key should only be done once per account id when it is not associated with a running vault, yet.
| Name | Type | Description |
|---|---|---|
publicKey |
string |
The BTC public key of the vault to derive deposit keys with the On-Chain Key Derivation Scheme. |
SubmittableExtrinsic<"promise", ISubmittableResult>
A register vault submittable extrinsic.
VaultsAPI.buildRegisterPublicKeyExtrinsic
▸ buildRegisterVaultExtrinsic(collateralAmount): SubmittableExtrinsic<"promise", ISubmittableResult>
Build extrinsic to register a new vault.
| Name | Type | Description |
|---|---|---|
collateralAmount |
MonetaryAmount<CollateralCurrencyExt> |
The collateral amount to register the vault with - in the new collateral currency. |
SubmittableExtrinsic<"promise", ISubmittableResult>
A register vault submittable extrinsic.
VaultsAPI.buildRegisterVaultExtrinsic
▸ buildWithdrawAllCollateralExtrinsic(collateralCurrency): Promise<SubmittableExtrinsic<"promise", ISubmittableResult>>
Build withdraw collateral extrinsic (transaction) without sending it.
| Name | Type | Description |
|---|---|---|
collateralCurrency |
CollateralCurrencyExt |
The collateral currency for which to withdraw all |
Promise<SubmittableExtrinsic<"promise", ISubmittableResult>>
A withdraw collateral submittable extrinsic as promise.
VaultsAPI.buildWithdrawAllCollateralExtrinsic
▸ buildWithdrawCollateralExtrinsic(amount): Promise<SubmittableExtrinsic<"promise", ISubmittableResult>>
Build withdraw collateral extrinsic (transaction) without sending it.
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<CollateralCurrencyExt> |
The amount of collateral to withdraw |
Promise<SubmittableExtrinsic<"promise", ISubmittableResult>>
A withdraw collateral submittable extrinsic as promise.
VaultsAPI.buildWithdrawCollateralExtrinsic
▸ calculateCapacity(collateral): Promise<MonetaryAmount<Currency>>
| Name | Type | Description |
|---|---|---|
collateral |
MonetaryAmount<CollateralCurrencyExt> |
Amount of collateral to calculate issuable capacity for |
Promise<MonetaryAmount<Currency>>
Issuable amount by the vault, given the collateral amount
▸ computeBackingCollateral(vaultId, nonce?): Promise<MonetaryAmount<CollateralCurrencyExt>>
| Name | Type | Description |
|---|---|---|
vaultId |
InterbtcPrimitivesVaultId |
Vault ID object |
nonce? |
number |
Nonce of the staking pool |
Promise<MonetaryAmount<CollateralCurrencyExt>>
The entire collateral backing a vault’s issued tokens.
VaultsAPI.computeBackingCollateral
▸ computeReward(vaultAccountId, collateralCurrency, rewardCurrency): Promise<MonetaryAmount<Currency>>
Compute the total reward, including the staking (local) pool and the rewards (global) pool
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault ID whose reward pool to check |
collateralCurrency |
CollateralCurrencyExt |
- |
rewardCurrency |
Currency |
The reward currency, e.g. kBTC, KINT, interBTC, INTR |
Promise<MonetaryAmount<Currency>>
A Monetary.js amount object, representing the total reward in the given currency
▸ depositCollateral(amount): ExtrinsicData
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<CollateralCurrencyExt> |
The amount of extra collateral to lock |
A submittable extrinsic and an event that is emitted when extrinsic is submitted.
▸ get(vaultAccountId, collateralCurrency): Promise<VaultExt>
Get a vault by account ID and collateral currency. Rejects if no vault exists.
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The ID of the vault to fetch |
collateralCurrency |
CollateralCurrencyExt |
Collateral used by vault |
Promise<VaultExt>
A vault object, rejects if no vault with the given ID and currency pair exists
▸ getAPY(vaultAccountId, collateralCurrency): Promise<Big>
Get the total APY for a vault based on the income in wrapped and collateral tokens divided by the locked collateral.
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault account ID |
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<Big>
the APY as a percentage string
Note
this does not account for interest compounding
▸ getBlockRewardAPY(vaultAccountId, collateralCurrency): Promise<Big>
Gets the estimated APY for just the block rewards (in governance tokens).
| Name | Type |
|---|---|
vaultAccountId |
AccountId |
collateralCurrency |
CollateralCurrencyExt |
Promise<Big>
the APY as a percentage
▸ getCollateral(vaultAccountId, collateralCurrency): Promise<MonetaryAmount<CollateralCurrencyExt>>
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
- |
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<MonetaryAmount<CollateralCurrencyExt>>
The collateral of a vault, taking slashes into account.
▸ getCollateralizationFromVault(vaultId, onlyIssued?): Promise<Big>
| Name | Type | Default value |
|---|---|---|
vaultId |
InterbtcPrimitivesVaultId |
undefined |
onlyIssued |
boolean |
false |
Promise<Big>
▸ getCollateralizationFromVaultAndCollateral(vaultId, newCollateral, onlyIssued): Promise<Big>
| Name | Type |
|---|---|
vaultId |
InterbtcPrimitivesVaultId |
newCollateral |
MonetaryAmount<CollateralCurrencyExt> |
onlyIssued |
boolean |
Promise<Big>
▸ getExchangeRateForLiquidation(vaultAccountId, collateralCurrency): Promise<undefined | Big>
Get the target exchange rate at which a vault will be forced to liquidate, given its current locked collateral and issued as well as to be issued tokens.
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault’s account ID |
collateralCurrency |
CollateralCurrencyExt |
The collateral currency for the vault with the account id above |
Promise<undefined | Big>
The theoretical collateral per wrapped currency rate below which the vault would be liquidated. Returns undefined if a value cannot be calculated, eg. if the vault has no issued tokens.
VaultsAPI.getExchangeRateForLiquidation
▸ getGovernanceReward(vaultAccountId, vaultCollateral, governanceCurrency): Promise<MonetaryAmount<Currency>>
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault ID whose reward pool to check |
vaultCollateral |
CollateralCurrencyExt |
Collateral used by the vault |
governanceCurrency |
Currency |
The fee reward currency |
Promise<MonetaryAmount<Currency>>
The total reward collected by the vault
▸ getIssuableTokensFromVault(vaultAccountId, collateralCurrency): Promise<MonetaryAmount<Currency>>
Returns issuable amount for a given vault
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault account ID |
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<MonetaryAmount<Currency>>
The issuable amount of a vault
VaultsAPI.getIssuableTokensFromVault
▸ getIssuedAmount(vaultAccountId, collateralCurrency): Promise<MonetaryAmount<Currency>>
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault account ID |
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or `ForeignAsset |
Promise<MonetaryAmount<Currency>>
The amount of wrapped tokens issued by the given vault
▸ getLiquidationCollateralThreshold(collateralCurrency): Promise<Big>
| Name | Type |
|---|---|
collateralCurrency |
CollateralCurrencyExt |
Promise<Big>
The lower bound for vault collateralization. If a Vault’s collateral rate drops below this, automatic liquidation (forced Redeem) is triggered.
VaultsAPI.getLiquidationCollateralThreshold
▸ getLiquidationVault(collateralCurrency): Promise<SystemVaultExt>
| Name | Type |
|---|---|
collateralCurrency |
CollateralCurrencyExt |
Promise<SystemVaultExt>
A vault object representing the liquidation vault
▸ getMaxNominationRatio(collateralCurrency): Promise<Big>
| Name | Type | Description |
|---|---|---|
collateralCurrency |
CollateralCurrencyExt |
The collateral currency specification, a Monetary.js object or ForeignAsset |
Promise<Big>
The maximum collateral a vault can accept as nomination, as a ratio of its own collateral
VaultsAPI.getMaxNominationRatio
▸ getMinimumCollateral(collateralCurrency): Promise<MonetaryAmount<CollateralCurrencyExt>>
Get the minimum secured collateral amount required to activate a vault
| Name | Type | Description |
|---|---|---|
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<MonetaryAmount<CollateralCurrencyExt>>
the minimum collateral to register a vault
VaultsAPI.getMinimumCollateral
▸ getOrNull(vaultAccountId, collateralCurrency): Promise<null | VaultExt>
Get a vault by account ID and collateral currency. Does not reject if the vault does not exist, but returns null instead.
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The ID of the vault to fetch |
collateralCurrency |
CollateralCurrencyExt |
Collateral used by vault |
Promise<null | VaultExt>
A vault object, or null if no vault with the given ID and currency pair exists
▸ getPremiumRedeemThreshold(collateralCurrency): Promise<Big>
| Name | Type |
|---|---|
collateralCurrency |
CollateralCurrencyExt |
Promise<Big>
The collateral rate at which users receive a premium allocated from the Vault’s collateral, when performing a redeem with this Vault.
VaultsAPI.getPremiumRedeemThreshold
▸ getPremiumRedeemVaults(): Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Vaults below the premium redeem threshold, sorted in descending order of their redeemable tokens
VaultsAPI.getPremiumRedeemVaults
▸ getPunishmentFee(): Promise<Big>
Promise<Big>
Fee that a Vault has to pay, as a percentage, if it fails to execute redeem or replace requests (for redeem, on top of the slashed wrapped-token-to-collateral value of the request). The fee is paid in collateral currency based on the wrapped token amount at the current exchange rate.
▸ getRegisterVaultEvent(): AugmentedEvent<ApiTypes, AnyTuple>
AugmentedEvent<ApiTypes, AnyTuple>
▸ getRequiredCollateralForVault(vaultAccountId, currency): Promise<MonetaryAmount<CollateralCurrencyExt>>
Get the amount of collateral required for the given vault to be at the current SecureCollateralThreshold with the current exchange rate
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault account ID |
currency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<MonetaryAmount<CollateralCurrencyExt>>
The required collateral the vault needs to deposit to stay above the threshold limit
VaultsAPI.getRequiredCollateralForVault
▸ getRequiredCollateralForWrapped(wrappedAmount, currency): Promise<MonetaryAmount<CollateralCurrencyExt>>
| Name | Type |
|---|---|
wrappedAmount |
MonetaryAmount<Currency> |
currency |
CollateralCurrencyExt |
Promise<MonetaryAmount<CollateralCurrencyExt>>
▸ getSecureCollateralThreshold(collateralCurrency): Promise<Big>
Get the global secure collateral threshold.
| Name | Type |
|---|---|
collateralCurrency |
CollateralCurrencyExt |
Promise<Big>
The global over-collateralization rate for collateral locked by Vaults, necessary for issuing wrapped tokens
VaultsAPI.getSecureCollateralThreshold
▸ getStakingCapacity(vaultAccountId, collateralCurrency): Promise<MonetaryAmount<CollateralCurrencyExt>>
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault account ID |
collateralCurrency |
CollateralCurrencyExt |
The currency specification, a Monetary.js object or ForeignAsset |
Promise<MonetaryAmount<CollateralCurrencyExt>>
Staking capacity, as a collateral currency (e.g. DOT)
▸ getSystemCollateralization(): Promise<undefined | Big>
Promise<undefined | Big>
▸ getTotalIssuableAmount(): Promise<MonetaryAmount<Currency>>
Promise<MonetaryAmount<Currency>>
The total amount of wrapped tokens that can be issued, considering the collateral locked by the vaults
VaultsAPI.getTotalIssuableAmount
▸ getTotalIssuedAmount(): Promise<MonetaryAmount<Currency>>
Promise<MonetaryAmount<Currency>>
The total amount of wrapped tokens issued by the vaults
VaultsAPI.getTotalIssuedAmount
▸ getVaultCollateralization(vaultAccountId, collateralCurrency, newCollateral?, onlyIssued?): Promise<undefined | Big>
Get the collateralization of a single vault measured by dividing the value of issued (wrapped) tokens by the value of total locked collateral.
| Name | Type | Default value | Description |
|---|---|---|---|
vaultAccountId |
AccountId |
undefined |
the vault account id |
collateralCurrency |
CollateralCurrencyExt |
undefined |
Collateral used by vault |
newCollateral? |
MonetaryAmount<CollateralCurrencyExt> |
undefined |
use this instead of the vault’s actual collateral |
onlyIssued |
boolean |
false |
optional, defaults to false. Specifies whether the collateralization should only include the issued tokens, leaving out unsettled (“to-be-issued”) tokens |
Promise<undefined | Big>
the vault collateralization
Remarks
Undefined collateralization is handled as infinite collateralization in the UI.
If no tokens have been issued, the collateralFunds / issuedFunds ratio divides by zero,
which means collateralization is infinite.
VaultsAPI.getVaultCollateralization
▸ getVaultsEligibleForRedeeming(): Promise<VaultExt[]>
Promise<VaultExt[]>
▸ getVaultsWithIssuableTokens(): Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Vaults with issuable tokens, not sorted in any particular order.
Remarks
The result is not sorted as an attempt to randomize the assignment of requests to vaults.
VaultsAPI.getVaultsWithIssuableTokens
▸ getVaultsWithRedeemableTokens(): Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Promise<Map<InterbtcPrimitivesVaultId, MonetaryAmount<Currency>>>
Vaults with redeemable tokens, sorted in descending order.
VaultsAPI.getVaultsWithRedeemableTokens
▸ getWrappedCurrency(): Currency
Currency
The wrapped currency issued by the vaults
▸ getWrappedReward(vaultAccountId, collateralCurrency): Promise<MonetaryAmount<Currency>>
| Name | Type | Description |
|---|---|---|
vaultAccountId |
AccountId |
The vault ID whose reward pool to check |
collateralCurrency |
CollateralCurrencyExt |
Collateral used by the vault |
Promise<MonetaryAmount<Currency>>
The total reward collected by the vault
▸ isBelowPremiumThreshold(vaultId): Promise<boolean>
| Name | Type |
|---|---|
vaultId |
InterbtcPrimitivesVaultId |
Promise<boolean>
▸ isNoTokensIssuedError(e): boolean
| Name | Type |
|---|---|
e |
string |
boolean
▸ isVaultEligibleForRedeem(vault, activeBlockNumber): boolean
| Name | Type |
|---|---|
vault |
VaultExt |
activeBlockNumber |
number |
boolean
▸ isVaultFlaggedForTheft(vaultId, btcTxId): Promise<boolean>
| Name | Type | Description |
|---|---|---|
vaultId |
InterbtcPrimitivesVaultId |
The vault ID |
btcTxId |
string |
ID of the Bitcoin transaction to check |
Promise<boolean>
A bollean value
VaultsAPI.isVaultFlaggedForTheft
▸ list(atBlock?): Promise<VaultExt[]>
| Name | Type |
|---|---|
atBlock? |
BlockHash |
Promise<VaultExt[]>
An array containing the vaults with non-zero backing collateral
▸ parseVault(vault): Promise<VaultExt>
| Name | Type |
|---|---|
vault |
VaultRegistryVault |
Promise<VaultExt>
▸ parseVaultStatus(status): VaultStatusExt
| Name | Type |
|---|---|
status |
VaultRegistryVaultStatus |
▸ registerNewCollateralVault(collateralAmount): ExtrinsicData
Registers a new vault for the current account ID with a new collateral amount. Only applicable if the connected account ID already has a running vault with a different collateral currency.
Rejects with an Error if unable to register.
| Name | Type | Description |
|---|---|---|
collateralAmount |
MonetaryAmount<CollateralCurrencyExt> |
The collateral amount to register the vault with - in the new collateral currency |
A submittable extrinsic and an event that is emitted when extrinsic is submitted.
VaultsAPI.registerNewCollateralVault
▸ selectRandomVaultIssue(amount): Promise<InterbtcPrimitivesVaultId>
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<Currency> |
Wrapped tokens amount to issue |
Promise<InterbtcPrimitivesVaultId>
A vault that has sufficient collateral to issue the given amount
VaultsAPI.selectRandomVaultIssue
▸ selectRandomVaultRedeem(amount): Promise<InterbtcPrimitivesVaultId>
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<Currency> |
Wrapped tokens amount to redeem |
Promise<InterbtcPrimitivesVaultId>
A vault that has issued sufficient wrapped tokens to redeem the given amount
VaultsAPI.selectRandomVaultRedeem
▸ toggleIssueRequests(vaultId, acceptNewIssues): Promise<ExtrinsicData>
Enables or disables issue requests for given vault
| Name | Type | Description |
|---|---|---|
vaultId |
InterbtcPrimitivesVaultId |
The vault ID whose issuing will be toggled |
acceptNewIssues |
boolean |
Boolean denoting whether issuing should be enabled or not |
Promise<ExtrinsicData>
A submittable extrinsic and an event that is emitted when extrinsic is submitted.
▸ withdrawAllCollateral(collateralCurrency): Promise<ExtrinsicData>
| Name | Type | Description |
|---|---|---|
collateralCurrency |
CollateralCurrencyExt |
The collateral currency for which to withdraw all |
Promise<ExtrinsicData>
A submittable extrinsic and an event that is emitted when extrinsic is submitted.
VaultsAPI.withdrawAllCollateral
▸ withdrawCollateral(amount): Promise<ExtrinsicData>
| Name | Type | Description |
|---|---|---|
amount |
MonetaryAmount<CollateralCurrencyExt> |
The amount of collateral to withdraw |
Promise<ExtrinsicData>
A submittable extrinsic and an event that is emitted when extrinsic is submitted.