zilswap-sdk / Exports / index / Zilswap
- addLiquidity
- addToken
- approveTokenTransferIfRequired
- callContract
- checkAppLoadedWithUser
- deadlineBlock
- deregisterZilo
- fetchContractInit
- getAppState
- getContract
- getCurrentBlock
- getObservedTxs
- getPool
- getRatesForInput
- getRatesForOutput
- initialize
- observeTx
- registerZilo
- removeLiquidity
- setDeadlineBlocks
- swapWithExactInput
- swapWithExactOutput
- teardown
- toUnit
- toUnitless
- txParams
• new Zilswap(network, walletProviderOrKey?, options?)
Creates the Zilswap SDK object. {@linkcode initalize} needs to be called after the object is created to begin watching the blockchain's state.
| Name | Type | Description |
|---|---|---|
network |
Network | the Network to use, either TestNet or MainNet. |
walletProviderOrKey? |
string | Pick<Zilliqa & { wallet: Wallet & { defaultAccount: { base16: string ; bech32: string } ; net: string } }, "provider" | "blockchain" | "network" | "contracts" | "transactions" | "wallet"> |
a Provider with Wallet or private key string to be used for signing txns. |
options? |
Options | a set of Options that will be used for all txns. |
• Readonly _txParams: TxParams
• Readonly contract: Contract
• Readonly contractAddress: string
• Readonly contractHash: string
• Readonly network: Network
• Readonly zilliqa: Zilliqa
• Readonly zilos: Object
▪ [address: string]: Zilo
▸ addLiquidity(tokenID, zilsToAddStr, tokensToAddStr, maxExchangeRateChange?): Promise<ObservedTx>
Adds liquidity to the pool with the given tokenID. The given zilsToAddHuman represents the exact quantity of ZIL
that will be contributed, while the given tokensToAddHuman represents the target quantity of ZRC-2 tokens to be
contributed.
To ensure the liquidity contributor does not lose value to arbitrage, the target token amount should be strictly
derived from the current exchange rate that can be found using getPool.
The maximum fluctuation in exchange rate from the given parameters can be controlled through maxExchangeRateChange,
to protect against changes in pool reserves between the txn submission and txn confirmation on the Zilliqa blockchain.
If the pool has no liquidity yet, the token amount given will be the exact quantity of tokens that will be contributed,
and the maxExchangeRateChange is ignored.
The transaction is added to the list of observedTxs, and the observer will be notified on change in tx status.
Note that all amounts should be given with decimals in it's human represented form, rather than as a unitless integer.
| Name | Type | Default value | Description |
|---|---|---|---|
tokenID |
string |
undefined |
is the token ID for the pool, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). |
zilsToAddStr |
string |
undefined |
is the exact amount of zilliqas to contribute to the pool in ZILs as a unitless string. |
tokensToAddStr |
string |
undefined |
is the target amount of tokens to contribute to the pool as a unitless string. |
maxExchangeRateChange |
number |
200 | is the maximum allowed exchange rate flucuation given in basis points. Defaults to 200 = 2.00% if not provided. |
Promise<ObservedTx>
▸ addToken(tokenAddress): Promise<boolean>
Adds a token which is not already loaded by the default tokens file to the SDK.
| Name | Type | Description |
|---|---|---|
tokenAddress |
string |
is the token address in base16 (0x...) or bech32 (zil...) form. |
Promise<boolean>
true if the token could be found, or false otherwise.
▸ approveTokenTransferIfRequired(tokenID, amountStrOrBN, spenderHash?): Promise<null | ObservedTx>
Approves allowing the Zilswap contract to transfer ZRC-2 token with tokenID, if the current
approved allowance is less than amount. If the allowance is sufficient, this method is a no-op.
The approval is done by calling IncreaseAllowance with the allowance amount as the entire
token supply. This is done so that the approval needs to only be done once per token contract,
reducing the number of approval transactions required for users conducting multiple swaps.
Non-custodial control of the token is ensured by the Zilswap contract itself, which does not allow for the transfer of tokens unless explicitly invoked by the sender.
The transaction is added to the list of observedTxs, and the observer will be notified on a confirmation or rejection event. The transation will be assumed to be expired after the default deadline buffer, even though there is no deadline block for this transaction.
| Name | Type | Description |
|---|---|---|
tokenID |
string |
is the token ID for the pool, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). |
amountStrOrBN |
string | BigNumber |
is the required allowance amount the Zilswap contract requires, below which the IncreaseAllowance transition is invoked, as a unitless string or BigNumber. |
spenderHash |
string |
(optional) is the spender contract address, defaults to the ZilSwap contract address. |
Promise<null | ObservedTx>
an ObservedTx if IncreaseAllowance was called, null if not.
▸ callContract(contract, transition, args, params, toDs?): Promise<Transaction>
| Name | Type |
|---|---|
contract |
Contract |
transition |
string |
args |
Value[] |
params |
Pick<TxParams, "version" | "amount" | "gasPrice" | "gasLimit" | "nonce" | "pubKey"> |
toDs? |
boolean |
Promise<Transaction>
▸ checkAppLoadedWithUser(): void
void
▸ deadlineBlock(): number
number
▸ deregisterZilo(address): void
Deregisters an existing Zilo instance. Does nothing if provided address is not already registered.
| Name | Type | Description |
|---|---|---|
address |
string |
is the Zilo contract address which can be given by either hash (0x...) or bech32 address (zil...). |
void
▸ fetchContractInit(contract): Promise<any>
| Name | Type |
|---|---|
contract |
Contract |
Promise<any>
▸ getAppState(): AppState
Gets the latest Zilswap app state.
▸ getContract(address): Contract
Gets the contract with the given address that can be called by the default account.
| Name | Type |
|---|---|
address |
string |
Contract
▸ getCurrentBlock(): number
number
▸ getObservedTxs(): Promise<ObservedTx[]>
Gets the currently observed transactions.
Promise<ObservedTx[]>
▸ getPool(tokenID): null | Pool
Gets the pool details for the given tokenID.
| Name | Type | Description |
|---|---|---|
tokenID |
string |
is the token ID for the pool, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). |
null | Pool
if pool exists, or null otherwise.
▸ getRatesForInput(tokenInID, tokenOutID, tokenInAmountStr): Rates
Gets the expected output amount and slippage for a particular set of ZRC-2 or ZIL tokens at the given input amount.
| Name | Type | Description |
|---|---|---|
tokenInID |
string |
is the token ID to be sent to Zilswap (sold), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutID |
string |
is the token ID to be taken from Zilswap (bought), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenInAmountStr |
string |
is the exact amount of tokens to be sent to Zilswap as a unitless representable string (without decimals). |
▸ getRatesForOutput(tokenInID, tokenOutID, tokenOutAmountStr): Rates
Gets the expected input amount and slippage for a particular set of ZRC-2 or ZIL tokens at the given output amount. Returns NaN values if the given output amount is larger than the pool reserve.
| Name | Type | Description |
|---|---|---|
tokenInID |
string |
is the token ID to be sent to Zilswap (sold), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutID |
string |
is the token ID to be taken from Zilswap (bought), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutAmountStr |
string |
is the exact amount of tokens to be received from Zilswap as a unitless representable string (without decimals). |
▸ initialize(subscription?, observeTxs?): Promise<void>
Intializes the SDK, fetching a cache of the Zilswap contract state and subscribing to subsequent state changes. You may optionally pass an array of ObservedTx's to subscribe to status changes on any of those txs.
| Name | Type | Default value | Description |
|---|---|---|---|
subscription? |
OnUpdate | undefined |
is the callback function to call when a tx state changes. |
observeTxs |
ObservedTx[] | [] | - |
Promise<void>
▸ observeTx(observedTx): Promise<void>
Observes the given transaction until the deadline block.
Calls the OnUpdate callback given during initialize with the updated ObservedTx
when a change has been observed.
| Name | Type | Description |
|---|---|---|
observedTx |
ObservedTx | is the txn hash of the txn to observe with the deadline block number. |
Promise<void>
▸ registerZilo(address, onStateUpdate?): Promise<Zilo>
Initializes a new Zilo instance and registers it to the ZilSwap SDK, subscribing to subsequent state changes in the Zilo instance. You may optionally pass a state observer to subscribe to state changes of this particular Zilo instance.
If the Zilo instance is already registered, no new instance will be created. If a new state observer is provided, it will overwrite the existing one.
| Name | Type | Description |
|---|---|---|
address |
string |
is the Zilo contract address which can be given by either hash (0x...) or bech32 address (zil...). |
onStateUpdate? |
OnStateUpdate | is the state observer which triggers when state updates |
Promise<Zilo>
▸ removeLiquidity(tokenID, contributionAmount, maxExchangeRateChange?): Promise<ObservedTx>
Removes contributionAmount worth of liquidity from the pool with the given tokenID.
The current user's contribution can be fetched in getPool, and the expected returned amounts at the
current prevailing exchange rates can be calculated by prorating the liquidity pool reserves by the fraction of
the user's current contribution against the pool's total contribution.
The maximum fluctuation in exchange rate from the given parameters can be controlled through maxExchangeRateChange,
to protect against changes in pool reserves between the txn submission and txn confirmation on the Zilliqa blockchain.
The transaction is added to the list of observedTxs, and the observer will be notified on change in tx status.
| Name | Type | Default value | Description |
|---|---|---|---|
tokenID |
string |
undefined |
is the token ID for the pool, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). |
contributionAmount |
string |
undefined |
is the exact amount of zilliqas to contribute to the pool in ZILs as a string. |
maxExchangeRateChange |
number |
200 | is the maximum allowed exchange rate flucuation given in basis points. Defaults to 200 = 2.00% if not provided. |
Promise<ObservedTx>
▸ setDeadlineBlocks(bufferBlocks): void
Sets the number of blocks to use as the allowable buffer duration before transactions are considered invalid.
When a transaction is signed, the deadline block by adding the buffer blocks to the latest confirmed block height.
| Name | Type | Description |
|---|---|---|
bufferBlocks |
number |
is the number of blocks to use as buffer for the deadline block. |
void
▸ swapWithExactInput(tokenInID, tokenOutID, tokenInAmountStr, maxAdditionalSlippage?, recipientAddress?): Promise<ObservedTx>
Swaps ZIL or a ZRC-2 token with tokenInID for a corresponding ZIL or ZRC-2 token with tokenOutID.
The exact amount of ZIL or ZRC-2 to be sent in (sold) is tokenInAmountHuman. The amount received is determined by the prevailing
exchange rate at the current AppState. The expected amount to be received can be given fetched by getExpectedOutput (NYI).
The maximum additional slippage incurred due to fluctuations in exchange rate from when the
transaction is signed and when it is processed by the Zilliqa blockchain can be bounded by the
maxAdditionalSlippage variable.
The transaction is added to the list of observedTxs, and the observer will be notified on change in tx status.
| Name | Type | Default value | Description |
|---|---|---|---|
tokenInID |
string |
undefined |
is the token ID to be sent to Zilswap (sold), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutID |
string |
undefined |
is the token ID to be taken from Zilswap (bought), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenInAmountStr |
string |
undefined |
is the exact amount of tokens to be sent to Zilswap as a unitless string (without decimals). |
maxAdditionalSlippage |
number |
200 | is the maximum additional slippage (on top of slippage due to constant product formula) that the transition will allow before reverting. |
recipientAddress |
null | string |
null | is an optional recipient address for receiving the output of the swap in base16 (0x...) or bech32 (zil...). Defaults to the sender address if null or undefined. |
Promise<ObservedTx>
▸ swapWithExactOutput(tokenInID, tokenOutID, tokenOutAmountStr, maxAdditionalSlippage?, recipientAddress?): Promise<ObservedTx>
Swaps ZIL or a ZRC-2 token with tokenInID for a corresponding ZIL or ZRC-2 token with tokenOutID.
The exact amount of ZIL or ZRC-2 to be received (bought) is tokenOutAmountHuman. The amount sent is determined by the prevailing
exchange rate at the current AppState. The expected amount to be sent can be given fetched by getExpectedInput (NYI).
The maximum additional slippage incurred due to fluctuations in exchange rate from when the
transaction is signed and when it is processed by the Zilliqa blockchain can be bounded by the
maxAdditionalSlippage variable.
The transaction is added to the list of observedTxs, and the observer will be notified on change in tx status.
| Name | Type | Default value | Description |
|---|---|---|---|
tokenInID |
string |
undefined |
is the token ID to be sent to Zilswap (sold), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutID |
string |
undefined |
is the token ID to be taken from Zilswap (bought), which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
tokenOutAmountStr |
string |
undefined |
is the exact amount of tokens to be received from Zilswap as a unitless string (withoout decimals). |
maxAdditionalSlippage |
number |
200 | is the maximum additional slippage (on top of slippage due to constant product formula) that the transition will allow before reverting. |
recipientAddress |
null | string |
null | is an optional recipient address for receiving the output of the swap in base16 (0x...) or bech32 (zil...). Defaults to the sender address if null or undefined. |
Promise<ObservedTx>
▸ teardown(): Promise<void>
Stops watching the Zilswap contract state.
Promise<void>
▸ toUnit(tokenID, amountStr): string
Converts an amount to it's human representation (with decimals based on token contract, or 12 decimals for ZIL) from it's unitless representation (integer, no decimals).
| Name | Type | Description |
|---|---|---|
tokenID |
string |
is the token ID related to the conversion amount, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
amountStr |
string |
is the unitless amount as a string (e.g. 42000000000000 for 42 ZILs) to be converted. |
string
▸ toUnitless(tokenID, amountHuman): string
Converts an amount to it's unitless representation (integer, no decimals) from it's human representation (with decimals based on token contract, or 12 decimals for ZIL).
| Name | Type | Description |
|---|---|---|
tokenID |
string |
is the token ID related to the conversion amount, which can be given by either it's symbol (defined in constants.ts), hash (0x...) or bech32 address (zil...). The hash for ZIL is represented by the ZIL_HASH constant. |
amountHuman |
string |
is the amount as a human string (e.g. 4.2 for 4.2 ZILs) to be converted. |
string
▸ txParams(): TxParams & { nonce: number }
TxParams & { nonce: number }