`: A promise that resolves to a transaction object.
### Usage Example
const tx = await sudoAPI.openPosition(
'USDC', // collateralToken
'SUI', // indexToken
5, // 5x leverage
1000, // 1000 USDC as collateral
myPositionConfig, // check getPositionConfig API
['0x123...', '0x456...'], // coinObjects
true, // long position
2, // indexPrice (SUI price in USD)
1, // collateralPrice (USDC price in USD)
0.001, // pricesSlippage (0.1%)
0.1, // collateralSlippage (10%)
false, // not a limit order
false, // not an IOC order
BigInt(2) // relayerFee
);
### Notes
* Ensure you have sufficient balance and have approved the necessary permissions before calling this function.
* The function uses the current oracle prices for the tokens. Ensure your frontend is updated with the latest prices before calling this function.
* The `pricesSlippage` and `collateralSlippage` parameters allow you to control the maximum allowed price movement. Adjust these based on market volatility and your risk tolerance.
* For limit orders, set `isLimitOrder` to `true`.
* The `relayerFee` is paid in SUI. Adjust this value based on the current network conditions and relayer requirements.
### Error Handling
This function may throw errors if:
* The input parameters are invalid
* There's insufficient balance
* The slippage tolerance is exceeded
* The position size is outside allowed limits
Always wrap the function call in a try-catch block and handle potential errors appropriately in your application.
# Decrease Position
The `decreasePosition` function allows users to reduce the size of an existing position.
#### Function Signature
```typescript
decreasePosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: bigint,
long: boolean,
indexPrice: number,
collateralPrice: number,
isTriggerOrder?: boolean,
isTakeProfitOrder?: boolean,
isIocOrder?: boolean,
pricesSlippage?: number,
collateralSlippage?: number,
relayerFee?: bigint
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to decrease
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount to decrease the position by
* `long`: Boolean indicating if this is a long (true) or short (false) position
* `indexPrice`: The current price of the index token
* `collateralPrice`: The current price of the collateral token
* `isTriggerOrder`: Boolean indicating if this is a trigger order (default: false)
* `isTakeProfitOrder`: Boolean indicating if this is a take profit order (default: true)
* `isIocOrder`: Boolean indicating if this is an IOC (Immediate-or-Cancel) order (default: false)
* `pricesSlippage`: Maximum allowed slippage for prices (default: 0.003 or 0.3%)
* `collateralSlippage`: Maximum allowed slippage for collateral (default: 0.5 or 50%)
* `relayerFee`: Fee paid to the relayer (default: 1)
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.decreasePosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
BigInt(500000), // amount (0.5 BTC if BTC has 6 decimals)
true, // long position
50000, // indexPrice (BTC price in USD)
1, // collateralPrice (USDC price in USD)
false, // not a trigger order
true, // is a take profit order
false, // not an IOC order
0.001, // pricesSlippage (0.1%)
0.1, // collateralSlippage (10%)
BigInt(2) // relayerFee
);
```
# Pledge In Position
The `pledgeInPosition` function allows users to add more collateral to an existing position.
#### Function Signature
```typescript
pledgeInPosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: number,
coinObjects: string[],
long: boolean
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to pledge into
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount of collateral to add
* `coinObjects`: Array of coin object IDs to use for the transaction
* `long`: Boolean indicating if this is a long (true) or short (false) position
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.pledgeInPosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
1000000, // amount (1 USDC if USDC has 6 decimals)
['0x456...', '0x789...'], // coinObjects
true // long position
);
```
# Redeem From Position
The `redeemFromPosition` function allows users to withdraw collateral from an existing position.
#### Function Signature
```typescript
redeemFromPosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: number,
long: boolean
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to redeem from
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount of collateral to withdraw
* `long`: Boolean indicating if this is a long (true) or short (false) position
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.redeemFromPosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
500000, // amount (0.5 USDC if USDC has 6 decimals)
true // long position
);
```
# Cancel Order
The `cancelOrder` function allows users to cancel an existing order.
#### Function Signature
```typescript
cancelOrder(
orderCapId: string,
collateralToken: string,
indexToken: string,
long: boolean,
type: string
): Promise
```
#### Parameters
* `orderCapId`: The ID of the order to cancel
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `long`: Boolean indicating if this is a long (true) or short (false) position
* `type`: The type of order ("OPEN\_POSITION" or "DECREASE\_POSITION")
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.cancelOrder(
'0x123...', // orderCapId
'USDC', // collateralToken
'BTC', // indexToken
true, // long position
'OPEN_POSITION' // order type
);
```
###
# getPositionCapInfoList
The `getPositionCapInfoList` function retrieves a list of position cap information for a given owner address.
#### Function Signature
```typescript
getPositionCapInfoList(owner: string): Promise
```
#### Parameters
* `owner`: A string representing the owner's address.
#### Return Value
Returns a `Promise` that resolves to an array of `IPositionCapInfo` objects. Each `IPositionCapInfo` object has the following structure:
```typescript
interface IPositionCapInfo {
positionCapId: string;
symbol0: string;
symbol1: string;
long: boolean;
}
```
* `positionCapId`: The ID of the position cap.
* `symbol0`: The first symbol in the trading pair.
* `symbol1`: The second symbol in the trading pair.
* `long`: A boolean indicating whether the position is long (true) or short (false).
#### Description
This function fetches all position caps owned by the specified address. It filters for objects of type `PositionCap` and extracts relevant information from each position cap.
#### Usage Example
```typescript
const owner = "0x1234..."; // Replace with actual owner address
const sudoAPI = new SudoAPI(network, provider);
try {
const positionCaps = await sudoAPI.getPositionCapInfoList(owner);
console.log("Position Caps:", positionCaps);
} catch (error) {
console.error("Error fetching position caps:", error);
}
```
# getPositionInfoList
The `getPositionInfoList` function retrieves detailed information about positions based on a list of position cap information.
#### Function Signature
```typescript
getPositionInfoList(
positionCapInfoList: IPositionCapInfo[],
owner: string
): Promise
```
#### Parameters
* `positionCapInfoList`: An array of `IPositionCapInfo` objects, typically obtained from `getPositionCapInfoList`.
* `owner`: A string representing the owner's address.
#### Return Value
Returns a `Promise` that resolves to an array of `IPositionInfo` objects. Each `IPositionInfo` object contains detailed information about a position, including:
```typescript
interface IPositionInfo {
id: string;
long: boolean;
owner: string;
version: number;
collateralToken: string;
indexToken: string;
collateralAmount: number;
positionAmount: number;
reservedAmount: number;
positionSize: number;
lastFundingRate: number;
lastReservingRate: number;
reservingFeeAmount: number;
fundingFeeValue: number;
closed: boolean;
openTimestamp: number;
protocol?: string;
}
```
#### Description
This function takes a list of position cap information and fetches detailed data for each position. It calculates additional information such as reserving fee amount and funding fee value for open positions.
#### Usage Example
```typescript
const owner = "0x1234..."; // Replace with actual owner address
const sudoAPI = new SudoAPI(provider);
try {
const positionCaps = await sudoAPI.getPositionCapInfoList(owner);
const positionInfoList = await sudoAPI.getPositionInfoList(positionCaps, owner);
console.log("Position Info List:", positionInfoList);
} catch (error) {
console.error("Error fetching position information:", error);
}
```
#### Notes
* The function sorts the returned positions by `openTimestamp` in ascending order.
* For open positions, the function calculates `reservingFeeAmount` and `fundingFeeValue` using separate API calls.
* If there's an error calculating `reservingFeeAmount` or `fundingFeeValue`, these values are set to 0 and the error is logged.
# getPositionConfig
Retrieves and parses the position configuration for a given index token and position type (long or short).
#### Function Signature
```typescript
getPositionConfig(
indexToken: string
long: boolean
): Promise
```
#### Parameters
* `indexToken` (string): The token for which to retrieve the position configuration.
* `long` (boolean): Indicates whether to retrieve the configuration for a long (true) or short (false) position.
#### Return Value
Returns a `Promise` that resolves to an `IPositionConfig` object. The object contains parsed position configuration, including:
```typescript
interface IPositionConfig {
decreaseFeeBps: number;
liquidationBonus: number;
liquidationThreshold: number;
maxLeverage: number;
minHoldingDuration: number;
openFeeBps: number;
maxReservedMultiplier: number;
minCollateralValue: number;
}
```
#### Description
This method fetches the position configuration data from the blockchain for a specified index token and position type. It performs the following steps:
#### Usage Example
```typescript
const sudoAPI = new SudoAPI(provider);
try {
const positionConfig = await sudoAPI.getPositionConfig('BTC', true);
console.log("Fetched position config:", positionConfig);
} catch (error) {
console.error("Error fetching position config:", error);
}
```
# OracleAPI
This section describes all APIs related to token prices.
# subOraclePrices
Subscribes to price feed updates for specified tokens.
#### Parameters
* `tokens` (string\[]): An array of token identifiers.
* `callback` ((price: PriceFeed) => void): A function to be called with each price update.
#### Returns
* `Promise`: A promise that resolves when the subscription is set up.
#### Description
This method establishes a subscription to price feed updates for the specified tokens. It maps the token identifiers to their corresponding Pyth object IDs and price feed IDs, then sets up a subscription using the Sui Price Service Connection.
When a price update is received, the method modifies the `price.id` to match the token identifier format used in the system, then calls the provided callback function with the updated price information.
#### Example Usage
```typescript
export function useTokenPrice(network: string) {
const [tokenPrice, setTokenPrice] = useState<{ [key: string]: number }>({});
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
if (isLoading) return;
setIsLoading(true);
const oracleAPI = new OracleAPI(network);
Promise.all([
oracleAPI.subOraclePrices(
Array.from(
new Set([...Object.keys(oracleAPI.consts.pythFeeder.feeder)]),
),
priceInfo => {
setTokenPrice(prevPrice => ({
...prevPrice,
[priceInfo.id]: priceInfo
.getPriceUnchecked()
.getPriceAsNumberUnchecked(),
}));
},
),
])
.then(() => {
setIsLoading(false);
})
.catch(err => {
console.error(err);
setError(err.message);
setIsLoading(false);
});
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [network]);
return {
tokenPrice,
isLoading,
error,
};
}
```
# Changelog
### # v0.0.2 -> v0.0.3
### Major Update
* Upgraded from "@mysten/sui.js": "0.54.1" to "@mysten/sui": "1.3.0"
### Key Changes
1. Parameter Updates:
* Removed: `size`, `collateralAmount`, `reserveAmount` (all bigint)
* Added: `leverage` (number), `collateral` (number), `positionConfig` (IPositionConfig)
2. Calculation Approach:
* Position size and reserve amount now calculated internally based on leverage and collateral
3. Return Type:
* Changed from `Promise` to implicit `Promise`
### Impact
* More intuitive position opening with leverage-based calculations
* Increased flexibility with `positionConfig`
* Less pre-processing and calculation required from the caller
* Potential breaking changes due to major Sui SDK upgrade
# Best Practices
When using the Sudo SDK, consider the following best practices:
1. **Error Handling**: Always implement proper error handling to manage potential issues gracefully.
2. **Price Updates**: Ensure you're using the most up-to-date price information when opening positions.
3. **Gas Management**: Be mindful of gas costs, especially when executing multiple transactions.
4. **Testing**: Thoroughly test your integration on a testnet before deploying to mainnet.
5. **Security**: Never expose your private keys. Use secure key management practices.
# Troubleshooting
# Algorithm Balanced Funding Rate (ABFR)
The fundamental principle underlying ABFR is to safeguard the interests of SLP holders by dynamically adapting the funding rate according to the specific direction of a trading pair. When traders exhibit net profitability in a given trading pair, fees are gathered from them and provided as support to LPs. When traders face an overall loss, fees are acquired from LPs and allocated to traders. This mechanism guarantees that the combined unrealized and realized PNL of each trading pair tends to balance out to approximately zero over the long run. In this way, LPs wouldn't experience excessive returns but rather would generate income from fees (transaction fee + borrowing interest). The subsequent steps outline the overall process for calculating these dynamic funding fees.
#### Calculate the total profit and loss of LP at time t on the the trading pair
$$\begin{aligned}sign&=\begin{cases}1\&short\\-1\&long\end{cases}\\\Delta\_t&=openAmount\_t \times price\_t - openSize\_t\pnl\_t&=realizedPnl+fundingFee+sign\times\Delta\_t\end{aligned}$$
{% hint style="info" %}
* Realized PNL signifies the actual profit and loss experienced by LPs due to changes in traders' positions, excluding the influence of fees.
* FundingFee embodies the cumulative funding fees that have been gathered or distributed.
{% endhint %}
When PNL\_t < 0:
$$ABFR\_t=\begin{aligned}min\left{K\_1\times log\left|PNL\_t\right|,R\_x\right}\end{aligned}$$
When PNL\_t > 0:
$$ABFR\_t=\begin{aligned}-min\left{K\_2\times log\left|PNL\_t\right|,R\_y\right}\end{aligned}$$
{% hint style="info" %}
K1, K2 are constant coefficients
{% endhint %}
* The reason for using the logarithm of pnl is to make ABFR change significantly when pnl is small and change slowly when pnl is large
* ABFR has upper and lower bounds, with corresponding upper and lower rate limits Rx, Ry when pnl < 0 and pnl > 0, respectively
If a trader opens a position at time t1 and closes it at time t2, with a position size of ***size*****,** the funding fee to be paid/received by the trader is
$$fundingFee=size\times\int\_{t\_1}^{t\_2}ABFR\_t\ dt$$
When the fee is positive, trader pays the funding fee to the LP
When the fee is negative, LP pays the funding fee to the trader
# Risk control
### Risk Control
Fluctuations in both the value of the collateral token and the token underlying the contract can lead to the potential liquidation of the position. Traders should vigilantly monitor both the position's profit and loss and any changes in the collateral's value.
A trader is required to establish a maximum margin size for the counterparty, which would also be the highest feasible profit excluding fees. If the position reaches this maximum profit, further profit won't be generated.
Opting for a larger counterparty margin also entails higher position maintenance fees. This is slightly different from the approach taken by other centralized exchanges. Those exchanges usually involve a contract borrow fee that is more closely tied to the position's value, influenced by its leverage. In contrast, Sudo's borrowing fee for perpetual contracts is predominantly determined by the potential maximum profit/loss of the position.
# FAQ
# Roadmap
#### ~~Milestone 1: Contract Implementation~~
* ~~Validate the feasibility of innovation points and implement smart contracts.~~
* ~~Expected Completion Date: 8/15/2023~~
* ~~Deliverables:~~
* ~~Feasibility of innovation points verified.~~
* ~~Smart contracts implemented.~~
#### ~~Milestone 2: Testnet launch~~
* ~~Launch Sudo on Sui Testnet~~
* ~~Expected Completion Date: 10/15/2023~~
* ~~Deliverables:~~
* ~~Make sudo available for testing on testnet to every degen~~
#### ~~Milestone 3: Mainnet launch~~
* ~~Launch Sudo on Mainnet~~
* ~~Expected Completion Date: 12/15/2023~~
* ~~Deliverables:~~
* ~~Mainnet launch completed.~~
* ~~Smart contract audited.~~
* ~~Onboarding documentation for sudo~~
* ~~Referral and loyalty program~~
* ~~Trading competition~~
~~2024 Q1 Milestone~~
* ~~Reach $10M in trading volume~~
* ~~Make over $50k in trading fee~~
* ~~Grow Users to 500+~~
* ~~Launch 10+ trading pairs~~
* ~~TVL $300k+~~
~~2024 Q2 Milestone~~
* ~~Reach $30M in trading volume~~
* ~~Make over $200k in trading fee~~
* ~~Grow Users to 800+~~
* ~~Launch 20+ trading pairs~~
* ~~Launch "S" Card~~
* ~~Launch "S" Card rebate~~
~~2024 Q3 Milestone~~
* ~~Reach $50M intrading volume~~
* ~~Make over $500k in trading fee~~
* ~~Grow Users to 1500+~~
* ~~Launch referral feature~~
* ~~Launch Sudo SDK~~
# On-chain program
Original Package:
{% embed url="" %}
Latest Package:
{% embed url="" %}
Audit Partner: MoveBit
Audit Report:
{% file src="/files/Vyar3aa9aRfThteydJE1" %}