Data contracts

The three interfaces you implement to plug your data layer into the notifiers.

The package is deliberately agnostic about where data comes from. You provide three small interfaces:

Interface	Responsibility
EmbeddedWalletReadDataSource	Fetch wallets, balances, and transactions from your backend
EmbeddedWalletStorage	Persist and retrieve wallet lists and transaction data locally
EmbeddedWalletBalanceCache	Cache and retrieve the most recent balance per wallet

---

EmbeddedWalletReadDataSource

The network-facing contract. Implement it against the API or any backend:

abstract class EmbeddedWalletReadDataSource {
  Future<Either<EmbeddedFailure, EmbeddedWalletListResponse>> fetchWallets();

  Future<Either<EmbeddedFailure, EmbeddedWalletDetailResponse>> fetchWalletDetail(
    String walletId,
  );

  Future<Either<EmbeddedFailure, EmbeddedWalletBalanceResponse>> fetchBalance(
    String walletId,
  );

  Future<Either<EmbeddedFailure, EmbeddedWalletTransactionsResponse>> fetchTransactions(
    String walletId, {
    int? page,
    int? pageSize,
  });
}

---

EmbeddedWalletStorage

Local persistence for wallet list and transaction data:

abstract class EmbeddedWalletStorage {
  Future<void> saveWallets(List<EmbeddedWallet> wallets);
  Future<List<EmbeddedWallet>?> loadWallets();

  Future<void> saveTransactions(
    String walletId,
    List<EmbeddedWalletTransaction> transactions,
  );
  Future<List<EmbeddedWalletTransaction>?> loadTransactions(String walletId);
}

A minimal in-memory implementation for testing or prototyping:

class InMemoryEmbeddedWalletStorage implements EmbeddedWalletStorage {
  final Map<String, List<EmbeddedWallet>> _wallets = {};
  final Map<String, List<EmbeddedWalletTransaction>> _txs = {};

  @override
  Future<void> saveWallets(List<EmbeddedWallet> wallets) async =>
      _wallets['wallets'] = wallets;

  @override
  Future<List<EmbeddedWallet>?> loadWallets() async => _wallets['wallets'];

  @override
  Future<void> saveTransactions(
    String walletId,
    List<EmbeddedWalletTransaction> transactions,
  ) async => _txs[walletId] = transactions;

  @override
  Future<List<EmbeddedWalletTransaction>?> loadTransactions(String walletId) async =>
      _txs[walletId];
}

---

EmbeddedWalletBalanceCache

Fast in-memory or persisted cache for live balances:

abstract class EmbeddedWalletBalanceCache {
  Future<void> saveBalance(String walletId, double balance);
  Future<double?> loadBalance(String walletId);
  Future<void> clearAll();
}

---

Failures

All contract methods return Either<EmbeddedFailure, T>. The failure subtypes:

Class	When to use
EmbeddedServerFailure	5xx or unexpected server response
EmbeddedCacheFailure	Local storage read/write error
EmbeddedNetworkFailure	No connectivity or timeout
EmbeddedValidationFailure	Malformed request / response
EmbeddedRateLimitFailure	HTTP 429
EmbeddedNotFoundFailure	HTTP 404
EmbeddedAuthenticationFailure	HTTP 401 — unauthenticated
EmbeddedAuthorizationFailure	HTTP 403 — forbidden

All extend EmbeddedFailure, which extends Equatable and carries a message string.

---

EmbeddedWalletCacheKeys

Static string constants for storage keys — use them if you implement EmbeddedWalletStorage on top of a key-value store:

EmbeddedWalletCacheKeys.walletList          // 'embedded_wallet_list'
EmbeddedWalletCacheKeys.transactionPrefix   // 'embedded_txns_'