sui_scallop_sdk 1.0.2

A Dart SDK for the Scallop lending protocol on Sui - market data, obligations, spools, lending/borrowing actions, and naming.

Sui Scallop SDK (Dart)

A fully featured Dart toolkit for interacting with the Scallop lending protocol on the Sui network. It wraps Scallop's on-chain Move contracts, off-chain indexer APIs, price oracles, and transaction builders so you can build lending apps, portfolio dashboards, and automation in pure Dart.

Features

• Unified client that exposes builders, queries, utilities, and constants with a single initialization step.
• Read market state from on-chain RPC and the Scallop indexer with automatic fallback when the indexer is unavailable.
• Transaction builders for core lending flows (obligation management, supply, borrow, repay, stake, loyalty programs, xOracle updates, etc.).
• Utilities for working with Scallop metadata (addresses, whitelists, decimals), selecting and merging coins, and resolving price feeds from Pyth, Switchboard, and the Scallop price service.
• Portfolio helpers that aggregate user positions, TVL, borrow limits, rewards, and staking data in a single call.
• Built on top of sui_kit so you can plug in any signer, key derivation path, or full node rotation strategy that SuiKit supports.

Installation

Add the package to your project. Until the SDK is published on pub.dev, depend on the Git repository:

# pubspec.yaml
dependencies:
  sui_scallop_sdk: ^0.1.0

Then fetch dependencies with dart pub get or flutter pub get.

Quick Start

The SDK is composed of a few building blocks:

• ScallopSuiKit wraps a SuiKit signer/client and rate-limits RPC calls.
• ScallopConstants fetches the canonical list of package/object IDs, coin metadata, and whitelists.
• ScallopIndexer calls Scallop's REST indexer for cached market data.
• ScallopUtils ties the pieces together and exposes helpers (coin parsing, price feeds, coin selection).
• ScallopQuery provides read APIs across market, spool, loyalty, veSCA, and oracle contracts.
• ScallopBuilder enhances Sui transaction blocks with Scallop-specific Move calls.
• ScallopClient exposes high-level methods that sign and submit transactions.
• Scallop is a convenience wrapper that ensures the whole stack is initialized.

Bootstrap the client

import 'dart:io';
import 'package:sui_dart/sui.dart';
import 'package:sui_kit/sui_kit.dart';
import 'package:sui_scallop_sdk/sui_scallop_sdk.dart';

Future<Scallop> createScallop() async {
  final suiKit = SuiKit(
    SuiKitParams(
      networkType: NetworkType.mainnet,
      secretKey: Platform.environment['PRIVATE_KEY']!,
    ),
  );

  final scallop = Scallop(
    client: ScallopClient(
      ScallopClientParams(
        builder: ScallopBuilder(
          ScallopBuilderParams(
            query: ScallopQuery(
              ScallopQueryParams(
                indexer: ScallopIndexer(),
                utils: ScallopUtils(
                  scallopSuiKitParams: ScallopSuiKitParams(suiKit: suiKit),
                  // Optional overrides live in ScallopConstantsParams / ScallopUtils ctor
                ),
              ),
            ),
          ),
        ),
      ),
    ),
  );

  await scallop.init();
  return scallop;
}

Querying market data

final scallop = await createScallop();
final query = await scallop.createScallopQuery();

// Fetch pools (indexer first, fallback to RPC if needed).
final market = await query.getMarketPools(['sui', 'wusdc']);
final suiPool = market.pools['sui'];

// Inspect user balances and obligations.
final balances = await query.getCoinAmounts(['sui', 'wusdc']);
final obligations = await query.getObligations();

// Portfolio helper with staking and incentive data.
final lendings = await query.getLendings(poolCoinNames: ['sui', 'wusdc']);

Most query methods accept an indexer: true flag to force indexer usage. When indexer is true the SDK will try the REST API first, then silently fall back to direct on-chain reads if the request fails.

Submitting transactions

final scallop = await createScallop();
final client = await scallop.createScallopClient();

// Deposit 1 SUI as collateral (amounts are in MIST).
const oneSui = 1000000000; // 1e9
final response = await client.depositCollateral('sui', BigInt.from(oneSui));
print('Tx digest: ${response.txResponse?.digest}');

// Build an unsigned borrow transaction for sponsorship or custom signing.
final existing = await client.getObligations();
final obligation = existing.first;
final borrow = await client.borrow(
  'wusdc',
  BigInt.from(5000000),
  obligationId: obligation.id,
  obligationKey: obligation.keyId,
  sign: false,
);
final txBlock = borrow.txBlock!;
// ... hand `txBlock` to your own signing flow

ScallopClient covers the common flows (openObligation, deposit, withdraw, borrow, repay, stake, unstake, claim, flashloan, etc.). Each method supports sign: false so you can compose transactions or sponsor them before submitting. For lower-level control call createScallopBuilder() and work with the Move helpers exposed by ScallopBuilder/CoreQuickMethods.

Utility helpers

final scallop = await createScallop();
final utils = await scallop.createScallopUtils();

final coinType = utils.parseCoinType('wusdc');
final sCoinName = utils.parseSCoinName('sui'); // -> 'ssui'
final prices = await utils.getCoinPrices();
final selection = await utils.selectCoins(
  BigInt.from(5000000000),
  coinType: coinType,
  ownerAddress: utils.walletAddress,
);

Configuration

• Network selection: pass networkType to SuiKitParams. Switching the Sui full node at runtime is available through scallopSuiKit.switchFullNodes([...]).
• Indexer endpoint: override ScallopIndexerParams(indexerApiUrl: ...) if you host a custom API or want to point to staging environments.
• Addresses & constants: override defaults via ScallopConstantsParams to test against forks or local deployments. You can force custom address maps, whitelists, or cache TTLs.
• Oracle feeds: provide custom Pyth Hermes endpoints via the pythEndpoints parameter on ScallopUtils. The SDK also exposes builders for xOracle and Switchboard updates under src/builders/oracles.
• Rate limiting & caching: ScallopSuiKitParams(tokensPerSecond: ...) throttles RPC calls. Responses are cached in-memory by query key to reduce duplicate traffic.

Testing & Examples

The repository includes integration tests that exercise the query surface. Configure a .env file with PRIVATE_KEY=<hex_or_bech32_key> and run:

dart test

test/query_test.dart demonstrates how to fetch market, portfolio, spool, and incentive data end to end.

Troubleshooting

• Ensure your wallet address has the required coins before submitting transactions—the SDK surfaces underlying Sui RPC errors when the balance is insufficient.
• When working on devnet/testnet, supply a matching ScallopConstantsParams(addressId: ...) and network-specific indexer URL. The defaults target mainnet.
• Large portfolio queries aggregate multiple RPC requests; increase Timeout in your tests or adjust ScallopSuiKitParams(tokensPerSecond: ...) if you regularly hit rate limits.

Contributing

Issues and pull requests are welcome. Please lint and run the test suite before submitting changes.

License

Licensed under the Apache 2.0 license.