Structuring States & Intents

In BalloonDogs’ SDK, an Intent defines how an asset or position changes across different blockchains. Intents are built from two main components: the From state (the current condition of the asset) and the To state (the desired condition after the transaction).

State Definition

A State represents the position of an asset and is categorized into types.

Parameters:

Each State object includes key parameters such as:

• address: The contract address associated with the asset, loan, or staking protocol (e.g., Aave, Lido)

• asset: The token address associated with the transaction

• amount: The number of tokens or assets involved. It can be optional depending on the context (e.g., staking)

• chainId: The ID of the blockchain network where the asset resides (e.g., Ethereum, BNB Chain)

Examples

Declaring an Asset

const assetState = new Asset({
  address: TOKENS.ETH.address, // ERC-20 address for the token
  amount: amountToBigInt(0.1, TOKENS.ETH.decimal), // Asset amount
  chainId: toBigInt(CHAINS.Ethereum), // Ethereum chain
})

Declaring a Loan

const loanState = new Loan({
  address: PROJECTS.Aave, // The Aave protocol address
  amount: amountToBigInt(0.1, TOKENS.ETH.decimal), // Loan amount
  asset: "0x...", // The address of the asset being lent (e.g., USDC, DAI, etc.)
  chainId: toBigInt(CHAINS.Ethereum), // The chain ID where Aave is deployed
});

Declaring a Stake

const stakeState = new Stake({
  address: PROJECTS.Lido, // Staking service address (e.g., Lido)
  amount: amountToBigInt(0.1, TOKENS.ETH.decimal), // Amount to stake
  chainId: toBigInt(CHAINS.Ethereum), // Ethereum chain
});

Defining an Intent

An Intent defines a transaction or operation that transforms a From state into a To state.

1. From (Source State)

The From section defines the specific portion of the user’s current assets or position that will be used in the intent. This allocation can include a variety of DeFi positions, such as swapping a portion of tokens, unstaking a part of an asset, or moving some NFTs.

This is an example for declaring a From of type "Token":

const fromState = new Asset({
  address: TOKENS.USDT.address,
  amount: amountToBigInt(500, TOKENS.USDT.decimal),
  chainId: toBigInt(CHAINS.BNBChain),
});

2. To (Desired State)

The To state specifies the desired outcome after executing the intent.

For example, you can declare the token you want to hold at the end of the execution or specify where you want your assets to be deposited or staked.

const toState = new Stake({
  address: PROJECTS.Lido,
  amount: amountToBigInt(500, TOKENS.USDT.decimal),
  chainId: toBigInt(CHAINS.Ethereum),
});

In this example, 500 USDT is moved from the BNB Chain to be staked on Ethereum via Lido.