> ## Documentation Index
> Fetch the complete documentation index at: https://bkey.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/introduction) or any backend:

```dart theme={null}
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:

```dart theme={null}
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:

```dart theme={null}
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:

```dart theme={null}
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:

```dart theme={null}
EmbeddedWalletCacheKeys.walletList          // 'embedded_wallet_list'
EmbeddedWalletCacheKeys.transactionPrefix   // 'embedded_txns_'
```