@admin-jigsaw/jigsaw-sdk
Version:
Returns predefined data for Jigsaw platform and exposes functionality to retrieve the necessary data
252 lines (165 loc) • 7.52 kB
Markdown
# Jigsaw SDK
Jigsaw SDK provides a streamlined interface for blockchain liquidators to manage insolvent loan positions. The SDK simplifies the complex process of liquidating positions where users have contributed collateral into various strategies.
## Installation
Install the SDK using npm:
```bash
npm install jigsaw-sdk
```
## Getting Started
To use the Jigsaw SDK, you need to import the `JigsawClient` class and initialize it. You can either use a default
configuration, provide a custom RPC URL, or use your own viem public client.
```typescript
import JigsawClient from "jigsaw-sdk";
// Initialize with default mainnet RPC
const client = new JigsawClient();
// Or initialize with custom RPC URL
const client = new JigsawClient("https://your-rpc-url.com");
// Or initialize with your own viem public client
import { createPublicClient, http } from "viem";
const customClient = createPublicClient({
chain: mainnet,
transport: http("https://your-rpc-url.com"),
});
const client = new JigsawClient(customClient);
```
## API Reference
### getUserStrategies(holdingAddress, assetSymbol?)
Retrieves the strategies associated with a user's holding contract. Optionally filters by asset symbol.
- **Parameters:**
- `holdingAddress` (Address): The address of the user's holding contract.
- `assetSymbol` (string, optional): The symbol of the asset to filter strategies.
- **Returns:** `Promise<Address[]>` - A list of strategy addresses or an empty array.
```typescript
const holdingAddress = "0x..."; // User's holding contract address
const strategies = await client.getUserStrategies(holdingAddress);
// Filter by asset symbol
const usdtStrategies = await client.getUserStrategies(holdingAddress, "USDT");
```
### getAllStrategies()
Retrieves all available strategies.
- **Returns:** `Strategy[]` - A list of all strategies.
```typescript
const strategies = client.getAllStrategies();
```
### getUserLiquidationInfo(holdingAddress, assetSymbol?)
Retrieves liquidation information for a user's position in a strategy.
- **Parameters:**
- `holdingAddress` (Address): The address of the user's holding contract.
- `assetSymbol` (string, optional): The symbol of the asset to filter strategies.
- **Returns:** `Promise<{ strategies: Address[]; callData: string[] }>` - A struct with two arrays needed for liquidation.
```typescript
const holdingAddress = "0x..."; // User's holding contract address
const info = await client.getUserLiquidationInfo(holdingAddress, "USDT");
```
### testConnection()
Tests the connection to the blockchain and retrieves the current block number.
- **Returns:** `Promise<string>` - The current block number as a string.
```typescript
const blockNumber = await client.testConnection();
console.log(`Connected to block ${blockNumber}`);
```
### getCurrentGasFee()
Retrieves the current gas price in ETH.
- **Returns:** `Promise<string>` - The current gas price in ETH.
```typescript
const gasFee = await client.getCurrentGasFee();
console.log(`Current gas price: ${gasFee} ETH`);
```
## Requirements
- Node.js
- TypeScript
- Viem
## Notes for Liquidators
- Liquidators can only liquidate insolvent loans
- It's the liquidator's responsibility to identify `_user`, `_collateral`, and `_jUsdAmount` values
- When users have contributed collateral into strategies, the contract must withdraw these contributions during liquidation
- If a user has no active strategies, the `strategies` array will be empty and the `strategiesData` will be an empty string
## Liquidation Process & Workflow
When a user's collateralization ratio drops and they become insolvent, liquidators can participate in the liquidation process. The primary purpose of this SDK is to simplify the generation of the `LiquidateCalldata` needed for liquidation.
The liquidation function signature is:
```solidity
function liquidate(
address _user,
address _collateral,
uint256 _jUsdAmount,
LiquidateCalldata calldata _data
)
```
The `LiquidateCalldata` struct has the following shape:
```solidity
struct LiquidateCalldata {
address[] strategies;
bytes[] strategiesData;
}
```
### Complete Liquidation Workflow
1. Identify an insolvent position
2. Determine the appropriate `_user`, `_collateral`, and `_jUsdAmount` values
3. Get the user's liquidation data (filter by token symbol if needed):
```typescript
const liquidationData = await client.getUserLiquidationInfo(userAddress);
```
4. Pass this data to the liquidate function along with other required parameters
5. Execute the liquidation transaction
When users have contributed collateral into strategies before becoming insolvent, the contract must withdraw these investments as part of liquidation. The SDK automatically generates the correct withdrawal calldata to ensure proper liquidation of loans associated with certain strategy positions.
Important notes for liquidators:
- Liquidators can only liquidate insolvent loans
- It's the liquidator's responsibility to identify `_user`, `_collateral`, and `_jUsdAmount` values
- If a user has no active strategies, the `strategies` array will be empty and the strategiesData will be an empty string
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes and updates.
## Development and Contribution
### Making Updates
When making updates to the SDK, follow these steps:
1. **Create a new branch**
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes**
Implement your features or fixes.
3. **Document your changes with Changeset**
```bash
npx changeset
```
- Follow the prompts to select which packages are affected
- Choose the appropriate semver bump (major, minor, patch)
- Provide a detailed description of your changes
- This will create a new file in the `.changeset` directory
4. **Build and test locally**
```bash
npm run build
npm test
```
5. **Commit your changes**
```bash
git add .
git commit -m "feat: your descriptive commit message"
```
6. **Push to the remote repository**
```bash
git push origin feature/your-feature-name
```
7. **Create a Pull Request**
- Open a PR to merge your branch into the main branch
- Ensure all CI checks pass
### Publishing a New Version
The publishing process is managed through changesets:
1. **Merge the approved feature PR to master**
2. **Merge automatically created changesets PR to master**
3. **New version is published automatically via a GitHub workflow**
### Versioning Guidelines
- **Patch** (`0.0.x`): Bug fixes and minor changes that don't affect the API
- **Minor** (`0.x.0`): New features added in a backward-compatible manner
- **Major** (`x.0.0`): Breaking changes that require API consumers to update their code
# Examples
Here is an example of node-js server integration and consumption, the source code can be found in examples/server
**Retrieving all info**
**Filtering by token symbol**
**Request liquidation info for all strategies the user has contributed into**
**Filtering liquidation info by token symbol**
