Struct SupabaseWalletDatabase 

pub struct SupabaseWalletDatabase { /* private fields */ }

Supabase wallet database implementation

This database uses two types of authentication:

• api_key: The Supabase project API key (required, used in apikey header)
• jwt_token: An optional JWT token for user authentication (used in Authorization: Bearer header)

When jwt_token is set, requests will include both headers:

• apikey: <api_key>
• Authorization: Bearer <jwt_token>

When jwt_token is not set, the api_key is used for both headers (legacy behavior).

Authentication Providers

The database supports multiple authentication providers via AuthProvider:

• None: No automatic token refresh, use API key only
• SupabaseAuth: Uses Supabase’s GoTrue API for token refresh
• Oidc: Uses an external OIDC provider for token refresh

Implementations

impl SupabaseWalletDatabase

pub const REQUIRED_SCHEMA_VERSION: u32 = 7

The schema version required by this SDK version.

This must match the latest schema_version value set in the migration files. When adding new migrations, update this constant and set the same value in the new migration’s INSERT INTO schema_info statement.

pub async fn new(url: Url, api_key: String) -> Result<Self, Error>

Create a new SupabaseWalletDatabase with API key only (legacy behavior)

No automatic token refresh is configured.

Note: This does NOT run or check migrations automatically. After authentication, call [check_schema_compatibility()] to verify the database schema is ready. Migrations must be run separately by an administrator — see [get_schema_sql()] or use supabase db push.

pub async fn with_supabase_auth( url: Url, api_key: String, ) -> Result<Self, Error>

Create a new SupabaseWalletDatabase with Supabase Auth for token refresh

This uses Supabase’s built-in GoTrue authentication system. Token refresh uses POST /auth/v1/token with grant_type=refresh_token.

Note: This does NOT run or check migrations automatically. After authentication, call [check_schema_compatibility()] to verify the database schema is ready. Migrations must be run separately by an administrator — see [get_schema_sql()] or use supabase db push.

pub async fn with_oidc( url: Url, api_key: String, oidc_client: OidcClient, ) -> Result<Self, Error>

Create a new SupabaseWalletDatabase with external OIDC client for auth

This uses an external OIDC provider (e.g., Keycloak, Auth0) for token refresh. The OIDC provider must be configured in Supabase to validate the JWTs.

Note: This does NOT run or check migrations automatically. After authentication, call [check_schema_compatibility()] to verify the database schema is ready. Migrations must be run separately by an administrator — see [get_schema_sql()] or use supabase db push.

pub fn get_schema_sql() -> String

Get the full database schema SQL

Returns the concatenated SQL of all migration files.

Use this to set up or update the database schema by running the output through the Supabase Dashboard SQL editor or supabase db push. This is an admin-only operation — never run this from a client app.

pub async fn check_schema_compatibility(&self) -> Result<(), Error>

Check that the database schema is compatible with this SDK version

This is the recommended client-side startup check. It queries the schema_info table (which is readable by all authenticated users) to verify the database has the required schema version.

Errors

• Error::SchemaNotInitialized if the schema_info table doesn’t exist (database was never set up or is running a pre-v4 schema).
• Error::SchemaMismatch if the database schema version is older than what this SDK version requires.

Example

// Call after authentication, before using the database
db.check_schema_compatibility().await?;
// Database is ready for use

pub async fn set_jwt_token(&self, token: Option<String>)

Set or update the JWT token for authentication

pub async fn set_refresh_token(&self, token: Option<String>)

Set refresh token

pub async fn set_encryption_password(&self, password: &str) -> Result<(), Error>

Derives an AES-256-GCM encryption key from password via scrypt.

pub async fn refresh_access_token(&self) -> Result<(), Error>

Refresh the access token using the stored refresh token

This method handles different authentication providers:

• SupabaseAuth: Uses POST /auth/v1/token with grant_type=refresh_token
• Oidc: Uses the OIDC provider’s token endpoint
• None: Returns an error (no provider configured)

pub async fn signup( &self, email: &str, password: &str, ) -> Result<SupabaseAuthResponse, Error>

Sign up a new user and automatically set tokens if returned

pub async fn signin( &self, email: &str, password: &str, ) -> Result<SupabaseAuthResponse, Error>

Sign in a user and automatically set tokens on the database instance

pub async fn get_jwt_token(&self) -> Option<String>

Get the current JWT token if set

pub async fn call_rpc( &self, function_name: &str, params_json: &str, ) -> Result<String, Error>

Call a Supabase RPC function with JSON parameters

pub fn join_url(&self, path: &str) -> Result<Url, DatabaseError>

Join the base URL with a path

Trait Implementations

impl Clone for SupabaseWalletDatabase

fn clone(&self) -> SupabaseWalletDatabase

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Database<Error> for SupabaseWalletDatabase

fn get_mint<'life0, 'async_trait>( &'life0 self, mint_url: MintUrl, ) -> Pin<Box<dyn Future<Output = Result<Option<MintInfo>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get mint from storage

fn get_mints<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<HashMap<MintUrl, Option<MintInfo>>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get all mints from storage

fn get_mint_keysets<'life0, 'async_trait>( &'life0 self, mint_url: MintUrl, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<KeySetInfo>>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get mint keysets for mint url

fn get_keyset_by_id<'life0, 'life1, 'async_trait>( &'life0 self, keyset_id: &'life1 Id, ) -> Pin<Box<dyn Future<Output = Result<Option<KeySetInfo>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get mint keyset by id

fn get_mint_quote<'life0, 'life1, 'async_trait>( &'life0 self, quote_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MintQuote>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get mint quote from storage

fn get_mint_quotes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<MintQuote>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get mint quotes from storage

fn get_unissued_mint_quotes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<MintQuote>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get unissued mint quotes from storage Returns bolt11 quotes where nothing has been issued yet (amount_issued = 0) and all bolt12 quotes. Includes unpaid bolt11 quotes to allow checking with the mint if they’ve been paid (wallet state may be outdated).

fn get_melt_quote<'life0, 'life1, 'async_trait>( &'life0 self, quote_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MeltQuote>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get melt quote from storage

fn get_melt_quotes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<MeltQuote>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get melt quotes from storage

fn get_keys<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 Id, ) -> Pin<Box<dyn Future<Output = Result<Option<Keys>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get Keys from storage

fn get_proofs<'life0, 'async_trait>( &'life0 self, mint_url: Option<MintUrl>, unit: Option<CurrencyUnit>, state: Option<Vec<State>>, spending_conditions: Option<Vec<SpendingConditions>>, ) -> Pin<Box<dyn Future<Output = Result<Vec<ProofInfo>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get proofs from storage

fn get_proofs_by_ys<'life0, 'async_trait>( &'life0 self, ys: Vec<PublicKey>, ) -> Pin<Box<dyn Future<Output = Result<Vec<ProofInfo>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get proofs by Y values

fn get_balance<'life0, 'async_trait>( &'life0 self, mint_url: Option<MintUrl>, unit: Option<CurrencyUnit>, state: Option<Vec<State>>, ) -> Pin<Box<dyn Future<Output = Result<u64, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get balance

fn get_transaction<'life0, 'async_trait>( &'life0 self, transaction_id: TransactionId, ) -> Pin<Box<dyn Future<Output = Result<Option<Transaction>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get transaction from storage

fn list_transactions<'life0, 'async_trait>( &'life0 self, mint_url: Option<MintUrl>, direction: Option<TransactionDirection>, unit: Option<CurrencyUnit>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Transaction>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List transactions from storage

fn update_proofs<'life0, 'async_trait>( &'life0 self, added: Vec<ProofInfo>, removed_ys: Vec<PublicKey>, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update the proofs in storage by adding new proofs or removing proofs by their Y value

fn update_proofs_state<'life0, 'async_trait>( &'life0 self, ys: Vec<PublicKey>, state: State, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update proofs state in storage

fn add_transaction<'life0, 'async_trait>( &'life0 self, transaction: Transaction, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add transaction to storage

fn remove_transaction<'life0, 'async_trait>( &'life0 self, transaction_id: TransactionId, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Remove transaction from storage

fn update_mint_url<'life0, 'async_trait>( &'life0 self, old_mint_url: MintUrl, new_mint_url: MintUrl, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update mint url

fn increment_keyset_counter<'life0, 'life1, 'async_trait>( &'life0 self, keyset_id: &'life1 Id, count: u32, ) -> Pin<Box<dyn Future<Output = Result<u32, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Atomically increment Keyset counter and return new value

fn add_mint<'life0, 'async_trait>( &'life0 self, mint_url: MintUrl, mint_info: Option<MintInfo>, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add Mint to storage

fn remove_mint<'life0, 'async_trait>( &'life0 self, mint_url: MintUrl, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Remove Mint from storage

fn add_mint_keysets<'life0, 'async_trait>( &'life0 self, mint_url: MintUrl, keysets: Vec<KeySetInfo>, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add mint keyset to storage

fn add_mint_quote<'life0, 'async_trait>( &'life0 self, quote: MintQuote, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add mint quote to storage

fn remove_mint_quote<'life0, 'life1, 'async_trait>( &'life0 self, quote_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove mint quote from storage

fn add_melt_quote<'life0, 'async_trait>( &'life0 self, quote: MeltQuote, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add melt quote to storage

fn remove_melt_quote<'life0, 'life1, 'async_trait>( &'life0 self, quote_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove melt quote from storage

fn add_keys<'life0, 'async_trait>( &'life0 self, keyset: KeySet, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add Keys to storage

fn remove_keys<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 Id, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove Keys from storage

fn kv_write<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, key: &'life3 str, value: &'life4 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Write a value to the key-value store

fn kv_remove<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, key: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Remove a value from the key-value store

fn kv_read<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, key: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Read a value from the key-value store

fn kv_list<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

List keys in a namespace

fn add_saga<'life0, 'async_trait>( &'life0 self, saga: WalletSaga, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Add a wallet saga to storage.

fn get_saga<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<Option<WalletSaga>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get a wallet saga by ID.

fn update_saga<'life0, 'async_trait>( &'life0 self, saga: WalletSaga, ) -> Pin<Box<dyn Future<Output = Result<bool, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Update a wallet saga with optimistic locking.

fn delete_saga<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete a wallet saga.

fn get_incomplete_sagas<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<WalletSaga>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get all incomplete sagas.

fn reserve_proofs<'life0, 'life1, 'async_trait>( &'life0 self, ys: Vec<PublicKey>, operation_id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Reserve proofs for an operation

fn release_proofs<'life0, 'life1, 'async_trait>( &'life0 self, operation_id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Release proofs reserved by an operation

fn get_reserved_proofs<'life0, 'life1, 'async_trait>( &'life0 self, operation_id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<Vec<ProofInfo>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get proofs reserved by an operation

fn reserve_melt_quote<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, quote_id: &'life1 str, operation_id: &'life2 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Reserve a melt quote for an operation.

fn release_melt_quote<'life0, 'life1, 'async_trait>( &'life0 self, operation_id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Release a melt quote reserved by an operation.

fn reserve_mint_quote<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, quote_id: &'life1 str, operation_id: &'life2 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Reserve a mint quote for an operation.

fn release_mint_quote<'life0, 'life1, 'async_trait>( &'life0 self, operation_id: &'life1 Uuid, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Release a mint quote reserved by an operation.

fn add_p2pk_key<'life0, 'life1, 'async_trait>( &'life0 self, pubkey: &'life1 PublicKey, derivation_path: DerivationPath, derivation_index: u32, ) -> Pin<Box<dyn Future<Output = Result<(), DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Store a P2PK signing key for the wallet

fn get_p2pk_key<'life0, 'life1, 'async_trait>( &'life0 self, pubkey: &'life1 PublicKey, ) -> Pin<Box<dyn Future<Output = Result<Option<P2PKSigningKey>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get a stored P2PK signing key by pubkey.

fn list_p2pk_keys<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<P2PKSigningKey>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List all stored P2PK signing keys.

fn latest_p2pk<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<P2PKSigningKey>, DatabaseError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Tries to get the latest p2pk key generated

impl Debug for SupabaseWalletDatabase

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl KVStoreDatabase for SupabaseWalletDatabase

type Err = Error

KV Store Database Error

fn kv_read<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, key: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, Self::Err>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Read value from key-value store

fn kv_list<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, primary_namespace: &'life1 str, secondary_namespace: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, Self::Err>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

List keys in a namespace