Integrating the sui_scallop_sdk Flutter package: A step‑by‑step guide

Introduction

The sui_scallop_sdk Flutter package provides a ready‑made Dart SDK for the Scallop lending protocol on the Sui blockchain. It bundles market data, obligations, spools, and borrowing actions behind a clean state‑management API that works out of the box with Riverpod.

When should you consider using sui_scallop_sdk?

Use this package if your Flutter app needs any of the following:

• Real‑time market data from the Scallop protocol.
• Read‑only access to user obligations and spools.
• Convenient borrowing / lending actions without writing low‑level Sui RPC calls.
• A state‑management solution that integrates with Riverpod (v3.4.2+).

Because the SDK abstracts a specific domain, it is best kept behind a service layer in a clean architecture. UI widgets should depend on your own abstractions, not directly on the SDK.

Installation

Open a terminal in the root of your Flutter project and run:

flutter pub add sui_scallop_sdk

The package also declares a peer dependency on Riverpod. If you do not already have Riverpod in your project, add it as well:

flutter pub add riverpod ^3.4.2
flutter pub add riverpod_annotation ^4.0.6

Basic setup with Riverpod

Below is a minimal, runnable example that fetches the current Scallop market price for a given asset and exposes it through a StateNotifierProvider. The example assumes you have already generated Riverpod annotations (run flutter pub run build_runner build if you use riverpod_annotation).

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:sui_scallop_sdk/sui_scallop_sdk.dart';

// 1️⃣ Create a service that wraps the SDK.
class ScallopService {
  final ScallopClient _client;

  ScallopService(this._client);

  Future fetchUsdPrice(String assetSymbol) async {
    // The actual SDK method name may differ – check the README on pub.dev.
    final market = await _client.getMarketData(assetSymbol);
    return market.usdPrice;
  }
}

// 2️⃣ Provide the service via Riverpod.
final scallopServiceProvider = Provider((ref) {
  // The SDK typically requires a Sui RPC endpoint; replace with your own.
  final client = ScallopClient(rpcUrl: 'https://fullnode.testnet.sui.io:443');
  return ScallopService(client);
});

// 3️⃣ Create a StateNotifier to hold the price.
class PriceNotifier extends StateNotifier> {
  final ScallopService _service;

  PriceNotifier(this._service) : super(const AsyncValue.loading()) {
    _loadPrice();
  }

  Future _loadPrice() async {
    try {
      final price = await _service.fetchUsdPrice('SUI');
      state = AsyncValue.data(price);
    } catch (e, st) {
      state = AsyncValue.error(e, st);
    }
  }
}

final priceNotifierProvider = StateNotifierProvider>((ref) {
  final service = ref.watch(scallopServiceProvider);
  return PriceNotifier(service);
});

// 4️⃣ UI that consumes the provider.
class PriceScreen extends ConsumerWidget {
  const PriceScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final priceAsync = ref.watch(priceNotifierProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Scallop SUI Price')),
      body: Center(
        child: priceAsync.when(
          data: (price) => Text('SUI = \$${price.toStringAsFixed(2)}', style: Theme.of(context).textTheme.headlineMedium),
          loading: () => const CircularProgressIndicator(),
          error: (err, stack) => Text('Error: $err'),
        ),
      ),
    );
  }
}

void main() {
  runApp(const ProviderScope(child: MyApp()));
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'FlutterFever • Scallop Demo',
      theme: ThemeData.light(),
      home: const PriceScreen(),
    );
  }
}

💡 Tip: Keep all SDK calls inside a dedicated service (as shown above). This isolates third‑party dependencies and makes unit testing easier.

Configuration notes & common mistakes

• RPC endpoint: The SDK needs a valid Sui RPC URL. Using a testnet endpoint for development and switching to mainnet in production avoids accidental on‑chain transactions.
• Riverpod version mismatch: The package requires riverpod ^3.4.2. If your project uses an older version, upgrade before adding sui_scallop_sdk.
• Missing code generation: When you rely on riverpod_annotation, run the build runner after adding the package; otherwise you will see missing generated files.
• Ignoring error handling: Network calls to the Sui node can fail. Always wrap SDK calls in try/catch and surface errors to the UI, as demonstrated in the PriceNotifier.
• Version drift: The SDK’s public API may evolve. Pin the version you have tested (e.g., sui_scallop_sdk: ^1.2.0) and review the changelog before upgrading.

Testing the integration

Because the SDK communicates with an external node, consider abstracting the ScallopClient behind an interface. In unit tests you can then inject a mock that returns deterministic market data.

FAQ

• Q: Do I need a Sui wallet to use the SDK?
  A: For read‑only operations like fetching market data, a wallet is not required. Writing actions (e.g., borrowing) will need a signed transaction, which means you must integrate a wallet or key management solution.
• Q: Can I use the SDK with Provider instead of Riverpod?
  A: The package itself does not depend on a specific state‑management library, but the current version declares a peer dependency on Riverpod. Using Provider alone would require a fork or waiting for a future release that removes the Riverpod constraint.
• Q: How do I know which API methods are stable?
  A: Check the pub.dev page and the package’s README. Stable methods are usually marked as such, and the changelog highlights breaking changes.
• Q: Is the SDK compatible with Flutter web?
  A: The SDK relies on HTTP RPC calls, which work on web, but some native dependencies may be missing. Verify compatibility by running a simple web build and testing the network calls.

Conclusion

The sui_scallop_sdk Flutter package can dramatically reduce the amount of boilerplate you need to interact with the Scallop lending protocol. By installing it, wrapping its client in a service, and exposing data through Riverpod, you get a clean, testable architecture that scales as your app grows. Always validate the latest API on pub.dev before shipping to production.

Frequently Asked Questions

Do I need a Sui wallet to use the SDK?

For read‑only operations like fetching market data, a wallet is not required. Writing actions such as borrowing will need a signed transaction, so you must integrate a wallet or key management solution.

Can I use the SDK with Provider instead of Riverpod?

The current version declares a peer dependency on Riverpod (v3.4.2+). While the SDK itself is not tightly coupled to Riverpod, using it without Riverpod would require a fork or waiting for a future release that removes the Riverpod constraint.

How can I verify which API methods are stable?

Check the package's pub.dev page and README. Stable methods are usually marked as such, and the changelog highlights any breaking changes.

Is the SDK compatible with Flutter web?

The SDK uses HTTP RPC calls, which work on the web, but some native dependencies might be missing. Run a web build and test the network calls to confirm compatibility.