TS Utils

Hooks

This section provides guidance on using the React hooks available in the hyperion-sdk package.

$3

Fetches information about all liquidity pairs available in a specific Hyperion Swap factory contract.

Purpose:

Retrieves an array of PairInfo objects, each containing details about a liquidity pair, such as the contract address and the assets involved.

Usage:

``typescript
import { useAllPairs } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const factoryAddress = 'your_factory_contract_address'; // Replace with the actual factory address
const chainId = CHAIN_IDS.TITAN_TESTNET; // Or the relevant chain ID

const { data: pairs, isLoading, error } = useAllPairs({
factoryAddress,
chainId,
// Optional react-query options
options: {
staleTime: 5 60 1000, // 5 minutes
}
});

// Now you can use pairs, isLoading, and error variables.
`

Parameters:

* factoryAddress (string, required): The address of the Hyperion Swap factory contract to query.
* chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET). You'll need to import CHAIN_IDS from the constants.
* options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc. See @tanstack/react-query documentation for details.

Returns:

Returns a react-query query object containing:

* data (PairInfo[] | undefined): An array of PairInfo objects when the query is successful, otherwise undefined. The PairInfo type contains details like contractAddr, liquidityToken, and assetInfos (which contains transformed asset information).
* isLoading (boolean): True while the query is fetching data.
* error (Error | null): An error object if the query failed, otherwise null.
* ... other react-query properties (status, refetch, etc.).

$3

Fetches the registered decimal value for a specific native token from the factory contract.

Purpose:

Retrieves the number of decimals for a given native token's denomination (denom). This is useful for UI formatting and calculations.

Usage:

`typescript
import { useRegisteredNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const factoryAddress = 'your_factory_contract_address'; // Replace with the actual factory address
const chainId = CHAIN_IDS.TITAN_TESTNET; // Or the relevant chain ID
const denom = 'your_native_token_denom'; // The denom of the native token to look up

const { data: decimals, isLoading, error } = useRegisteredNativeTokenDecimals({
factoryAddress,
chainId,
denom,
// Optional react-query options
options: {
staleTime: 5 60 1000, // 5 minutes
}
});

// Now you can use decimals, isLoading, and error variables.
`

Parameters:

* factoryAddress (string, required): The address of the Hyperion Swap factory contract to query.
* chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET).
* denom (string, required): The denomination of the native token.
* options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc. See @tanstack/react-query documentation for details.

Returns:

Returns a react-query query object containing:

* data (number | undefined): The number of decimals for the token when the query is successful, otherwise undefined.
* isLoading (boolean): True while the query is fetching data.
* error (Error | null): An error object if the query failed, otherwise null.
* ... other react-query properties (status, refetch, etc.).

$3

Fetches a quote for a swap operation by simulating the swap on the Hyperion Swap router contract.

Purpose:

Retrieves simulation results for a potential swap operation, including the expected return amount and other swap details.

Usage:

`typescript
import { useQuote } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const {
data: simulateSwapOperations,
isLoading,
isFetching,
isError,
error,
} = useQuote({
chainId: CHAIN_IDS.TITAN_TESTNET,
routerContract: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
offerAmount: (1e18).toString(),
offerAsset: "atkx",
askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
});
`

Parameters:

* chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET).
* routerContract (string, required): The address of the Hyperion Swap router contract.
* offerAmount (string, required): The amount of the asset being offered for the swap, in string format.
* offerAsset (string, required): The identifier of the asset being offered (e.g., "atkx").
* askAsset (string, required): The identifier of the asset being requested in return.
* options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc.

Returns:

Returns a react-query query object containing:

* data (SimulationResponse | undefined): The simulation response containing swap details when the query is successful, otherwise undefined.
* isLoading (boolean): True while the query is fetching data.
* isFetching (boolean): True while the query is fetching data, even if there is cached data.
* isError (boolean): True if the query resulted in an error.
* error (Error | null): An error object if the query failed, otherwise null.
* ... other react-query properties (status, refetch, etc.).

$3

Simulates a swap operation to estimate the gas cost before executing the actual swap.

Purpose:

Estimates the gas cost (in bigint) for a potential swap operation without actually executing the transaction.

Usage:

`typescript
import { useSimulateSwap } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";

const {
mutate: simulateSwap,
data: estimatedGas,
isLoading,
isError,
error,
} = useSimulateSwap({
onSuccess: (gas) => {
console.log('Estimated gas:', gas);
},
});

// Call the simulation
simulateSwap({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
routerAddress: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
offerAmount: (1e18).toString(),
offerAsset: "atkx",
askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
minimumReceiveAmount: "1000000", // Minimum amount to receive from the swap
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Swap Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer who will execute the swap.
* routerAddress (string, required): The address of the Hyperion Swap router contract.
* offerAmount (string, required): The amount of the asset being offered for the swap.
* offerAsset (string, required): The identifier of the asset being offered.
* askAsset (string, required): The identifier of the asset being requested in return.
* minimumReceiveAmount (string, required): The minimum amount expected to receive from the swap.
* memo (string, optional): Optional memo for the transaction.
* to (string, optional): Optional recipient address for the swap.
* deadline (number, optional): Optional deadline timestamp for the swap.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the simulation with swap parameters.
* data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
* isLoading (boolean): True while the simulation is in progress.
* isError (boolean): True if the simulation resulted in an error.
* error (Error | null): An error object if the simulation failed, otherwise null.
* ... other react-query mutation properties.

$3

Executes a swap operation on the Hyperion Swap router contract.

Purpose:

Performs the actual swap transaction on the blockchain, returning the transaction response.

Usage:

`typescript
import { useExecuteSwap } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { StdFee } from "@titanlabjs/titan-types/types";

const {
mutate: executeSwap,
data: txResponse,
isLoading,
isError,
error,
} = useExecuteSwap({
onSuccess: (response) => {
console.log('Swap executed:', response);
},
});

// Execute the swap
executeSwap({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
routerAddress: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
offerAmount: (1e18).toString(),
offerAsset: "atkx",
askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
minimumReceiveAmount: "1000000", // Minimum amount to receive from the swap
fee: {
amount: [{ denom: "atkx", amount: "1000000" }],
gas: "200000"
}, // Required StdFee for the transaction
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Swap Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer who will execute the swap.
* routerAddress (string, required): The address of the Hyperion Swap router contract.
* offerAmount (string, required): The amount of the asset being offered for the swap.
* offerAsset (string, required): The identifier of the asset being offered.
* askAsset (string, required): The identifier of the asset being requested in return.
* minimumReceiveAmount (string, required): The minimum amount expected to receive from the swap.
* fee (StdFee, required): The fee configuration for the transaction.
* memo (string, optional): Optional memo for the transaction.
* to (string, optional): Optional recipient address for the swap.
* deadline (number, optional): Optional deadline timestamp for the swap.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the swap execution with swap parameters.
* data (DeliverTxResponse | undefined): The transaction response when the swap is successful, otherwise undefined.
* isLoading (boolean): True while the swap transaction is in progress.
* isError (boolean): True if the swap execution resulted in an error.
* error (Error | null): An error object if the swap failed, otherwise null.
* ... other react-query mutation properties.

$3

Simulates a create pair operation to estimate the gas cost before executing the actual creation.

Purpose:

Estimates the gas cost (in bigint) for creating a new liquidity pair without actually executing the transaction.

Usage:

`typescript
import { useSimulateCreatePair } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin } from "@titanlabjs/titan-types/types";

const {
mutate: simulateCreatePair,
data: estimatedGas,
isLoading,
isError,
error,
} = useSimulateCreatePair({
onSuccess: (gas) => {
console.log('Estimated gas:', gas);
},
});

// Call the simulation
simulateCreatePair({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
factoryAddress: "titan1...", // Factory contract address
assets: [
{
denom: "atkx",
amount: "0"
},
{
denom: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
amount: "0"
}
] as [Coin, Coin],
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Create Pair Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer who will create the pair.
* factoryAddress (string, required): The address of the Hyperion Swap factory contract.
* assets ([Coin, Coin], required): A tuple of two Coin objects representing the assets to create the pair with.
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the simulation with create pair parameters.
* data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
* isLoading (boolean): True while the simulation is in progress.
* isError (boolean): True if the simulation resulted in an error.
* error (Error | null): An error object if the simulation failed, otherwise null.
* ... other react-query mutation properties.

$3

Executes a create pair operation on the Hyperion Swap factory contract.

Purpose:

Creates a new liquidity pair on the blockchain, returning the transaction response.

Usage:

`typescript
import { useExecuteCreatePair } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin, StdFee } from "@titanlabjs/titan-types/types";

const {
mutate: executeCreatePair,
data: txResponse,
isLoading,
isError,
error,
} = useExecuteCreatePair({
onSuccess: (response) => {
console.log('Pair created:', response);
},
});

// Execute the create pair
executeCreatePair({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
factoryAddress: "titan1...", // Factory contract address
assets: [
{
denom: "atkx",
amount: "0"
},
{
denom: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
amount: "0"
}
] as [Coin, Coin],
fee: {
amount: [{ denom: "atkx", amount: "1000000" }],
gas: "200000"
}, // Required StdFee for the transaction
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Create Pair Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer who will create the pair.
* factoryAddress (string, required): The address of the Hyperion Swap factory contract.
* assets ([Coin, Coin], required): A tuple of two Coin objects representing the assets to create the pair with.
* fee (StdFee, required): The fee configuration for the transaction.
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the create pair execution with parameters.
* data (DeliverTxResponse | undefined): The transaction response when the pair creation is successful, otherwise undefined.
* isLoading (boolean): True while the create pair transaction is in progress.
* isError (boolean): True if the create pair execution resulted in an error.
* error (Error | null): An error object if the create pair failed, otherwise null.
* ... other react-query mutation properties.

$3

Simulates a provide liquidity operation to estimate the gas cost before executing the actual transaction.

Purpose:

Estimates the gas cost (in bigint) for providing liquidity to an existing pair without actually executing the transaction.

Usage:

`typescript
import { useSimulateProvideLiquidity } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin } from "@titanlabjs/titan-types/types";

const {
mutate: simulateProvideLiquidity,
data: estimatedGas,
isLoading,
isError,
error,
} = useSimulateProvideLiquidity({
onSuccess: (gas) => {
console.log('Estimated gas for providing liquidity:', gas);
},
});

// Call the simulation
// Note: The order of assets must match the order in the pair contract.
simulateProvideLiquidity({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
pairAddress: "titan1...pair_contract_address...", // Address of the pair contract
assets: [
{ denom: "token_A_denom", amount: "1000000" }, // Ensure this is asset1 of the pair
{ denom: "token_B_denom", amount: "500000" } // Ensure this is asset2 of the pair
] as [Coin, Coin],
memo: "Optional memo for the transaction",
// Optional: slippageTolerance, receiver, deadline
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Provide Liquidity Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer providing liquidity.
* pairAddress (string, required): The contract address of the liquidity pair.
* assets ([Coin, Coin], required): A tuple of two Coin objects representing the assets to provide. Important: The order of assets in this array must match the order of assets defined in the pair contract.
* slippageTolerance (string, optional): The maximum allowed slippage tolerance (as a decimal string, e.g., "0.01" for 1%).
* receiver (string, optional): An optional address to receive the LP tokens. Defaults to the signerAddress if not provided.
* deadline (number, optional): A Unix timestamp (in seconds) after which the transaction is no longer valid.
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the simulation with provide liquidity parameters.
* data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
* isLoading (boolean): True while the simulation is in progress.
* isError (boolean): True if the simulation resulted in an error.
* error (Error | null): An error object if the simulation failed, otherwise null.
* ... other react-query mutation properties.

$3

Executes a provide liquidity operation on the Hyperion Swap pair contract.

Purpose:

Adds liquidity to an existing pair on the blockchain, returning the transaction response.

Usage:

`typescript
import { useExecuteProvideLiquidity } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin, StdFee } from "@titanlabjs/titan-types/types";

const {
mutate: executeProvideLiquidity,
data: txResponse,
isLoading,
isError,
error,
} = useExecuteProvideLiquidity({
onSuccess: (response) => {
console.log('Liquidity provided:', response);
},
});

// Execute the provide liquidity
// Note: The order of assets must match the order in the pair contract.
executeProvideLiquidity({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
pairAddress: "titan1...pair_contract_address...", // Address of the pair contract
assets: [
{ denom: "token_A_denom", amount: "1000000" }, // Ensure this is asset1 of the pair
{ denom: "token_B_denom", amount: "500000" } // Ensure this is asset2 of the pair
] as [Coin, Coin],
fee: {
amount: [{ denom: "atkx", amount: "100000" }],
gas: "300000"
}, // Required StdFee for the transaction
memo: "Optional memo for the transaction",
// Optional: slippageTolerance, receiver, deadline
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Provide Liquidity Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer providing liquidity.
* pairAddress (string, required): The contract address of the liquidity pair.
* assets ([Coin, Coin], required): A tuple of two Coin objects representing the assets to provide. Important: The order of assets in this array must match the order of assets defined in the pair contract.
* fee (StdFee, required): The fee configuration for the transaction.
* slippageTolerance (string, optional): The maximum allowed slippage tolerance (as a decimal string, e.g., "0.01" for 1%).
* receiver (string, optional): An optional address to receive the LP tokens. Defaults to the signerAddress if not provided.
* deadline (number, optional): A Unix timestamp (in seconds) after which the transaction is no longer valid.
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the provide liquidity execution with parameters.
* data (DeliverTxResponse | undefined): The transaction response when liquidity provision is successful, otherwise undefined.
* isLoading (boolean): True while the transaction is in progress.
* isError (boolean): True if the execution resulted in an error.
* error (Error | null): An error object if the execution failed, otherwise null.
* ... other react-query mutation properties.

$3

Simulates an add_native_token_decimals operation to estimate the gas cost.

Purpose:

Estimates the gas cost (in bigint) for adding or updating the decimals for a native token in the factory/relevant contract without actually executing the transaction.

Usage:

`typescript
import { useSimulateAddNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";

const {
mutate: simulateAddNativeTokenDecimals,
data: estimatedGas,
isLoading,
isError,
error,
} = useSimulateAddNativeTokenDecimals({
onSuccess: (gas) => {
console.log('Estimated gas for adding native token decimals:', gas);
},
});

// Call the simulation
simulateAddNativeTokenDecimals({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
factoryAddress: "titan1...factory_contract_address...", // Address of the factory or relevant contract
denom: "newNativeToken",
decimals: 18,
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Add Native Token Decimals Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer performing the operation.
* factoryAddress (string, required): The contract address that handles the add_native_token_decimals message (e.g., a factory contract).
* denom (string, required): The denomination of the native token.
* decimals (number, required): The number of decimals for the token (uint8).
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the simulation.
* data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
* isLoading (boolean): True while the simulation is in progress.
* isError (boolean): True if the simulation resulted in an error.
* error (Error | null): An error object if the simulation failed, otherwise null.
* ... other react-query mutation properties.

$3

Executes an add_native_token_decimals operation on the relevant contract.

Purpose:

Adds or updates the decimals for a specified native token denomination in the factory or relevant contract.

Usage:

`typescript
import { useExecuteAddNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { StdFee } from "@titanlabjs/titan-types/types";

const {
mutate: executeAddNativeTokenDecimals,
data: txResponse,
isLoading,
isError,
error,
} = useExecuteAddNativeTokenDecimals({
onSuccess: (response) => {
console.log('Native token decimals added/updated:', response);
},
});

// Execute the operation
executeAddNativeTokenDecimals({
signingClient: signingClient, // SigningClient instance
signerAddress: "titan1...", // Address of the signer
factoryAddress: "titan1...factory_contract_address...", // Address of the factory or relevant contract
denom: "newNativeToken",
decimals: 18,
fee: {
amount: [{ denom: "atkx", amount: "50000" }],
gas: "200000"
}, // Required StdFee for the transaction
memo: "Optional memo for the transaction",
});
`

Parameters:

* options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Add Native Token Decimals Parameters:

* signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
* signerAddress (string, required): The address of the signer performing the operation.
* factoryAddress (string, required): The contract address that handles the add_native_token_decimals message (e.g., a factory contract).
* denom (string, required): The denomination of the native token.
* decimals (number, required): The number of decimals for the token (uint8).
* fee (StdFee, required): The fee configuration for the transaction.
* memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

* mutate (function): Function to trigger the execution.
* data (DeliverTxResponse | undefined): The transaction response when the operation is successful, otherwise undefined.
* isLoading (boolean): True while the transaction is in progress.
* isError (boolean): True if the execution resulted in an error.
* error (Error | null): An error object if the execution failed, otherwise null.
* ... other react-query` mutation properties.