commit 834d040e8f46dc2923a36b85762c656814c85ff5
parent 844f99a01ebc8a44d96ea399c82f90246e2c5e49
Author: Florian Dold <dold@taler.net>
Date: Sun, 19 Jul 2026 02:00:11 +0200
db: document WalletDbTransaction methods
Diffstat:
1 file changed, 126 insertions(+), 12 deletions(-)
diff --git a/packages/taler-wallet-core/src/dbtx.ts b/packages/taler-wallet-core/src/dbtx.ts
@@ -104,14 +104,17 @@ export interface StoreCurrencyInfoDbRequest {
}
export interface WalletDbTransaction {
+ /** Get the currency specification for a scope, if one is stored. */
getCurrencyInfo(
scopeInfo: ScopeInfo,
): Promise<GetCurrencyInfoDbResult | undefined>;
+ /** Get a config record by key. The result type narrows to the key. */
getConfig<T extends ConfigRecord["key"]>(
key: T,
): Promise<Extract<ConfigRecord, { key: T }> | undefined>;
+ /** Create or update a config record. */
upsertConfig(record: ConfigRecord): Promise<void>;
/**
@@ -121,31 +124,41 @@ export interface WalletDbTransaction {
*/
upsertCurrencyInfo(req: StoreCurrencyInfoDbRequest): Promise<void>;
+ /** Store currency info for a scope, keeping any existing entry. */
insertCurrencyInfoUnlessExists(
req: StoreCurrencyInfoDbRequest,
): Promise<void>;
+ /** Create or update a contact, keyed by (alias, aliasType). */
addContact(contact: ContactEntry): Promise<void>;
+ /** Delete a contact by alias and alias type. */
deleteContact(alias: string, aliasType: string): Promise<void>;
+ /** List all stored contacts. */
listContacts(): Promise<ContactEntry[]>;
+ /** Create or update a mailbox message. */
upsertMailboxMessage(message: MailboxMessageRecord): Promise<void>;
+ /** Delete a mailbox message by origin mailbox and taler URI. */
deleteMailboxMessage(
originMailboxBaseUrl: string,
talerUri: string,
): Promise<void>;
+ /** List all stored mailbox messages. */
listMailboxMessages(): Promise<MailboxMessageRecord[]>;
+ /** Get the configuration for a mailbox, if one is stored. */
getMailboxConfiguration(
mailboxBaseUrl: string,
): Promise<MailboxConfiguration | undefined>;
+ /** Create or update a mailbox configuration. */
upsertMailboxConfiguration(mailboxConf: MailboxConfiguration): Promise<void>;
+ /** Get a purchase by proposal ID. */
getPurchase(proposalId: string): Promise<WalletPurchase | undefined>;
/**
@@ -247,17 +260,10 @@ export interface WalletDbTransaction {
*/
upsertContractTerms(rec: WalletContractTerms): Promise<void>;
- /**
- * Get an exchange entry by its base URL.
- */
- /**
- * Get exchange details by the (baseUrl, currency, masterPub) pointer.
- */
- /**
- * Look up a denomination family by its parameters.
- */
+ /** Count an exchange's withdrawal groups, to decide whether it is in use. */
countWithdrawalGroupsByExchange(exchangeBaseUrl: string): Promise<number>;
+ /** Get an exchange's withdrawal groups so their base URL can be rewritten. */
getWithdrawalGroupsByExchangeForRekey(
exchangeBaseUrl: string,
): Promise<WalletWithdrawalGroup[]>;
@@ -290,12 +296,14 @@ export interface WalletDbTransaction {
exchangeMasterPub: string,
): Promise<WalletGlobalCurrencyExchange | undefined>;
+ /** Get the global-currency entry for an auditor, if it is trusted globally. */
getGlobalCurrencyAuditor(
currency: string,
auditorBaseUrl: string,
auditorPub: string,
): Promise<WalletGlobalCurrencyAuditor | undefined>;
+ /** List every denomination-loss event, in any state. */
listAllDenomLossEvents(): Promise<WalletDenomLossEvent[]>;
/**
@@ -341,24 +349,31 @@ export interface WalletDbTransaction {
/** Get all coins issued by an exchange. */
getCoinsByExchange(exchangeBaseUrl: string): Promise<WalletCoin[]>;
+ /** Count the coins issued by an exchange, to decide whether it is in use. */
countCoinsByExchange(exchangeBaseUrl: string): Promise<number>;
+ /** Get the coins of a given denomination. */
getCoinsByDenomPubHash(denomPubHash: string): Promise<WalletCoin[]>;
+ /** Delete a coin by its public key. */
deleteCoin(coinPub: string): Promise<void>;
+ /** Delete the recorded history of a coin. */
deleteCoinHistory(coinPub: string): Promise<void>;
+ /** Get the coin availability records of an exchange. */
getCoinAvailabilityByExchange(
exchangeBaseUrl: string,
): Promise<WalletCoinAvailability[]>;
+ /** Delete a coin availability record. */
deleteCoinAvailability(
exchangeBaseUrl: string,
denomPubHash: string,
maxAge: number,
): Promise<void>;
+ /** Get the recoup groups against an exchange. */
getRecoupGroupsByExchange(
exchangeBaseUrl: string,
): Promise<WalletRecoupGroup[]>;
@@ -377,20 +392,28 @@ export interface WalletDbTransaction {
*/
listAllDepositGroups(): Promise<WalletDepositGroup[]>;
+ /** List every refund group, in any state. */
listAllRefundGroups(): Promise<WalletRefundGroup[]>;
+ /** List every withdrawal group, in any state. */
listAllWithdrawalGroups(): Promise<WalletWithdrawalGroup[]>;
+ /** List every purchase, in any state. */
listAllPurchases(): Promise<WalletPurchase[]>;
+ /** List every incoming peer pull payment, in any state. */
listAllPeerPullCredits(): Promise<WalletPeerPullCredit[]>;
+ /** List every outgoing peer pull payment, in any state. */
listAllPeerPullDebits(): Promise<WalletPeerPullDebit[]>;
+ /** List every incoming peer push payment, in any state. */
listAllPeerPushCredits(): Promise<WalletPeerPushCredit[]>;
+ /** List every outgoing peer push payment, in any state. */
listAllPeerPushDebits(): Promise<WalletPeerPushDebit[]>;
+ /** Look up a denomination family by its value and fee parameters. */
getDenominationFamilyByParams(
params: WalletDenomFamilyParams,
): Promise<WalletDenominationFamily | undefined>;
@@ -403,25 +426,32 @@ export interface WalletDbTransaction {
*/
upsertDenominationFamily(rec: WalletDenominationFamily): Promise<number>;
+ /** Get the denomination families of an exchange. */
getDenominationFamiliesByExchange(
exchangeBaseUrl: string,
): Promise<WalletDenominationFamily[]>;
+ /** Delete a denomination family by serial. */
deleteDenominationFamily(denominationFamilySerial: number): Promise<void>;
+ /** Get a pending base-URL fixup for an exchange, if one is recorded. */
getExchangeBaseUrlFixup(
exchangeBaseUrl: string,
): Promise<WalletExchangeBaseUrlFixup | undefined>;
+ /** Record that an exchange base URL should be replaced. */
upsertExchangeBaseUrlFixup(rec: WalletExchangeBaseUrlFixup): Promise<void>;
+ /** Get the log entry for a base-URL migration, if it has run. */
getExchangeMigrationLog(
oldExchangeBaseUrl: string,
newExchangeBaseUrl: string,
): Promise<WalletExchangeMigrationLog | undefined>;
+ /** Record that a base-URL migration has run. */
upsertExchangeMigrationLog(rec: WalletExchangeMigrationLog): Promise<void>;
+ /** Get exchange details by the (baseUrl, currency, masterPub) pointer. */
getExchangeDetailsByPointer(
exchangeBaseUrl: string,
currency: string,
@@ -442,6 +472,7 @@ export interface WalletDbTransaction {
exchangeBaseUrl: string,
): Promise<WalletExchangeDetails[]>;
+ /** List every exchange details record, for all exchanges. */
listAllExchangeDetails(): Promise<WalletExchangeDetails[]>;
/**
@@ -452,61 +483,82 @@ export interface WalletDbTransaction {
*/
upsertExchangeDetails(rec: WalletExchangeDetails): Promise<number>;
+ /** Delete an exchange details record by row ID. */
deleteExchangeDetails(rowId: number): Promise<void>;
+ /** Get the signing keys attached to an exchange details record. */
getExchangeSignKeysByDetailsRowId(
exchangeDetailsRowId: number,
): Promise<WalletExchangeSignkeys[]>;
+ /** Create or update an exchange signing key. */
upsertExchangeSignKey(rec: WalletExchangeSignkeys): Promise<void>;
+ /** Delete an exchange signing key by details row ID and key. */
deleteExchangeSignKey(
exchangeDetailsRowId: number,
signkeyPub: string,
): Promise<void>;
+ /** Get a denomination-loss event by ID. */
getDenomLossEvent(
denomLossEventId: string,
): Promise<WalletDenomLossEvent | undefined>;
+ /** Create or update a denomination-loss event. */
upsertDenomLossEvent(rec: WalletDenomLossEvent): Promise<void>;
+ /** Delete a denomination-loss event by ID. */
deleteDenomLossEvent(denomLossEventId: string): Promise<void>;
+ /** Get an exchange entry by base URL. */
getExchange(baseUrl: string): Promise<WalletExchangeEntry | undefined>;
+ /** Create or update an exchange entry. */
upsertExchange(rec: WalletExchangeEntry): Promise<void>;
+ /** Delete an exchange entry by base URL. Does not touch related records. */
deleteExchange(baseUrl: string): Promise<void>;
+ /** Create or update a purchase. */
upsertPurchase(rec: WalletPurchase): Promise<void>;
+ /** Delete a purchase by proposal ID. */
deletePurchase(proposalId: string): Promise<void>;
+ /** Get the purchase for a merchant order, if there is exactly one. */
getPurchaseByUrlAndOrderId(
merchantBaseUrl: string,
orderId: string,
): Promise<WalletPurchase | undefined>;
+ /** Get every purchase for a merchant order, including repurchases. */
getPurchasesByUrlAndOrderId(
merchantBaseUrl: string,
orderId: string,
): Promise<WalletPurchase[]>;
+ /** Get purchases sharing a fulfillment URL, used to detect repurchases. */
getPurchasesByFulfillmentUrl(
fulfillmentUrl: string,
): Promise<WalletPurchase[]>;
+ /** Get purchases that involved a given exchange. */
getPurchasesByExchange(exchangeBaseUrl: string): Promise<WalletPurchase[]>;
+ /** Get a refund group by ID. */
getRefundGroup(refundGroupId: string): Promise<WalletRefundGroup | undefined>;
+ /** Create or update a refund group. */
upsertRefundGroup(rec: WalletRefundGroup): Promise<void>;
+ /** Delete a refund group by ID. */
deleteRefundGroup(refundGroupId: string): Promise<void>;
+ /** Get the refund groups belonging to a purchase. */
getRefundGroupsByProposal(proposalId: string): Promise<WalletRefundGroup[]>;
+ /** Get the refund items belonging to a refund group. */
getRefundItemsByGroup(refundGroupId: string): Promise<WalletRefundItem[]>;
/**
@@ -516,8 +568,10 @@ export interface WalletDbTransaction {
*/
upsertRefundItem(rec: WalletRefundItem): Promise<number>;
+ /** Delete a refund item by row ID. */
deleteRefundItem(id: number): Promise<void>;
+ /** Get the refund item for a coin and merchant refund transaction ID. */
getRefundItemByCoinAndRtxid(
coinPub: string,
rtxid: number,
@@ -533,60 +587,78 @@ export interface WalletDbTransaction {
repeatIndex: number,
): Promise<WalletSlate | undefined>;
+ /** Get the slates for a purchase and contract choice. */
getSlatesByPurchaseAndChoice(
purchaseId: string,
choiceIndex: number,
): Promise<WalletSlate[]>;
+ /** Create or update a slate. */
upsertSlate(rec: WalletSlate): Promise<void>;
+ /** Delete a slate by its token use public key. */
deleteSlate(tokenUsePub: string): Promise<void>;
+ /** Record a tombstone, marking a deleted transaction as not to be revived. */
upsertTombstone(rec: WalletTombstone): Promise<void>;
+ /** Get the donation summary for a donau, year and currency. */
getDonationSummary(
donauBaseUrl: string,
year: number,
currency: string,
): Promise<WalletDonationSummary | undefined>;
+ /** Create or update a donation summary. */
upsertDonationSummary(rec: WalletDonationSummary): Promise<void>;
+ /** Get a donation receipt by its unique donation identifier nonce. */
getDonationReceipt(
udiNonce: string,
): Promise<WalletDonationReceipt | undefined>;
+ /** Create or update a donation receipt. */
upsertDonationReceipt(rec: WalletDonationReceipt): Promise<void>;
+ /** Get donation receipts in a given status. */
getDonationReceiptsByStatus(
status: DonationReceiptStatus,
): Promise<WalletDonationReceipt[]>;
+ /** Get donation receipts in a given status for one donau. */
getDonationReceiptsByStatusAndDonau(
status: DonationReceiptStatus,
donauBaseUrl: string,
): Promise<WalletDonationReceipt[]>;
+ /** Create or update a donation planchet. */
upsertDonationPlanchet(rec: WalletDonationPlanchet): Promise<void>;
+ /** Get the donation planchets of a purchase. */
getDonationPlanchetsByProposal(
proposalId: string,
): Promise<WalletDonationPlanchet[]>;
+ /** Count the donation planchets of a purchase. */
countDonationPlanchetsByProposal(proposalId: string): Promise<number>;
+ /** Get a withdrawal group by ID. */
getWithdrawalGroup(
withdrawalGroupId: string,
): Promise<WalletWithdrawalGroup | undefined>;
+ /** Create or update a withdrawal group. */
upsertWithdrawalGroup(rec: WalletWithdrawalGroup): Promise<void>;
+ /** Delete a withdrawal group by ID. */
deleteWithdrawalGroup(withdrawalGroupId: string): Promise<void>;
+ /** Get the withdrawal group for a taler-withdraw URI, for idempotent starts. */
getWithdrawalGroupByTalerWithdrawUri(
talerWithdrawUri: string,
): Promise<WalletWithdrawalGroup | undefined>;
+ /** Get the withdrawal groups against an exchange. */
getWithdrawalGroupsByExchange(
exchangeBaseUrl: string,
): Promise<WalletWithdrawalGroup[]>;
@@ -604,12 +676,16 @@ export interface WalletDbTransaction {
*/
getPlanchet(coinPub: string): Promise<WalletPlanchet | undefined>;
+ /** Create or update a planchet. */
upsertPlanchet(rec: WalletPlanchet): Promise<void>;
+ /** Delete a planchet by coin public key. */
deletePlanchet(coinPub: string): Promise<void>;
+ /** Get the planchets of a withdrawal group. */
getPlanchetsByGroup(withdrawalGroupId: string): Promise<WalletPlanchet[]>;
+ /** Count the planchets of a withdrawal group. */
countPlanchetsByGroup(withdrawalGroupId: string): Promise<number>;
/**
@@ -617,38 +693,49 @@ export interface WalletDbTransaction {
*/
deletePlanchetsByGroup(withdrawalGroupId: string): Promise<void>;
+ /** Get a refresh group by ID. */
getRefreshGroup(
refreshGroupId: string,
): Promise<WalletRefreshGroup | undefined>;
+ /** Create or update a refresh group. */
upsertRefreshGroup(rec: WalletRefreshGroup): Promise<void>;
+ /** Delete a refresh group by ID. */
deleteRefreshGroup(refreshGroupId: string): Promise<void>;
+ /** Get the refresh groups spawned by a transaction. */
getRefreshGroupsByOriginatingTransaction(
transactionId: string,
): Promise<WalletRefreshGroup[]>;
+ /** Get the refresh session for a group and coin index. */
getRefreshSession(
refreshGroupId: string,
coinIndex: number,
): Promise<WalletRefreshSession | undefined>;
+ /** Create or update a refresh session. */
upsertRefreshSession(rec: WalletRefreshSession): Promise<void>;
+ /** Delete the refresh session for a group and coin index. */
deleteRefreshSession(
refreshGroupId: string,
coinIndex: number,
): Promise<void>;
+ /** Get the refresh sessions of a group. */
getRefreshSessionsByGroup(
refreshGroupId: string,
): Promise<WalletRefreshSession[]>;
+ /** Get a recoup group by ID. */
getRecoupGroup(recoupGroupId: string): Promise<WalletRecoupGroup | undefined>;
+ /** Create or update a recoup group. */
upsertRecoupGroup(rec: WalletRecoupGroup): Promise<void>;
+ /** Delete a recoup group by ID. */
deleteRecoupGroup(recoupGroupId: string): Promise<void>;
/**
@@ -671,16 +758,21 @@ export interface WalletDbTransaction {
*/
upsertReserve(rec: WalletReserve): Promise<number>;
+ /** Get a deposit group by ID. */
getDepositGroup(
depositGroupId: string,
): Promise<WalletDepositGroup | undefined>;
+ /** Create or update a deposit group. */
upsertDepositGroup(rec: WalletDepositGroup): Promise<void>;
+ /** Delete a deposit group by ID. */
deleteDepositGroup(depositGroupId: string): Promise<void>;
+ /** Get a coin by its public key. */
getCoin(coinPub: string): Promise<WalletCoin | undefined>;
+ /** Create or update a coin. */
upsertCoin(coin: WalletCoin): Promise<void>;
/**
@@ -688,16 +780,20 @@ export interface WalletDbTransaction {
*/
getCoinsBySourceTransaction(transactionId: string): Promise<WalletCoin[]>;
+ /** Get the availability record for a denomination and age restriction. */
getCoinAvailability(
exchangeBaseUrl: string,
denomPubHash: string,
maxAge: number,
): Promise<WalletCoinAvailability | undefined>;
+ /** Create or update a coin availability record. */
upsertCoinAvailability(rec: WalletCoinAvailability): Promise<void>;
+ /** Get the recorded history of a coin. */
getCoinHistory(coinPub: string): Promise<WalletCoinHistory | undefined>;
+ /** Create or update the recorded history of a coin. */
upsertCoinHistory(rec: WalletCoinHistory): Promise<void>;
/**
@@ -807,17 +903,16 @@ export interface WalletDbTransaction {
contractPriv: string,
): Promise<WalletPeerPullDebit | undefined>;
+ /** Create or update a denomination. */
upsertDenomination(rec: WalletDenomination): Promise<void>;
+ /** Get a denomination by exchange base URL and public key hash. */
getDenomination(
exchangeBaseUrl: string,
denomPubHash: string,
): Promise<WalletDenomination | undefined>;
/**
- * Get all denominations offered by an exchange.
- */
- /**
* Find the first denomination of a family, scanning in withdraw-expiry order
* from the given timestamp, that satisfies the caller's predicate.
*
@@ -831,37 +926,50 @@ export interface WalletDbTransaction {
match: (d: WalletDenomination) => boolean,
): Promise<WalletDenomination | undefined>;
+ /** Get all denominations offered by an exchange. */
getDenominationsByExchange(
exchangeBaseUrl: string,
): Promise<WalletDenomination[]>;
+ /** Delete a denomination by exchange base URL and public key hash. */
deleteDenomination(
exchangeBaseUrl: string,
denomPubHash: string,
): Promise<void>;
+ /** Get denominations awaiting or failing signature verification. */
getDenominationsByVerificationStatus(
verificationStatus: DenominationVerificationStatus,
): Promise<WalletDenomination[]>;
+ /** List all donation summaries. */
getDonationSummaries(): Promise<WalletDonationSummary[]>;
+ /** List all exchange entries. */
getExchanges(): Promise<WalletExchangeEntry[]>;
+ /** List all coin availability records. */
getCoinAvailabilities(): Promise<WalletCoinAvailability[]>;
+ /** Get refresh groups in a non-final state. */
getActiveRefreshGroups(): Promise<WalletRefreshGroup[]>;
+ /** Get withdrawal groups in a non-final state. */
getActiveWithdrawalGroups(): Promise<WalletWithdrawalGroup[]>;
+ /** Get outgoing peer push payments in a non-final state. */
getActivePeerPushDebits(): Promise<WalletPeerPushDebit[]>;
+ /** Get incoming peer push payments in a non-final state. */
getActivePeerPushCredits(): Promise<WalletPeerPushCredit[]>;
+ /** Get incoming peer pull payments in a non-final state. */
getActivePeerPullCredits(): Promise<WalletPeerPullCredit[]>;
+ /** Get outgoing peer pull payments in a non-final state. */
getActivePeerPullDebits(): Promise<WalletPeerPullDebit[]>;
+ /** Get recoup groups in a non-final state. */
getActiveRecoupGroups(): Promise<WalletRecoupGroup[]>;
/**
@@ -869,21 +977,27 @@ export interface WalletDbTransaction {
*/
getPurchasesByStatus(status: PurchaseStatus): Promise<WalletPurchase[]>;
+ /** Get purchases in a non-final state. */
getActivePurchases(): Promise<WalletPurchase[]>;
+ /** Get the coins for a list of public keys, skipping any that are missing. */
getCoinsByPubs(coinPubs: string[]): Promise<WalletCoin[]>;
+ /** Get deposit groups in a non-final state. */
getActiveDepositGroups(): Promise<WalletDepositGroup[]>;
+ /** Get the details currently pointed to by an exchange entry. */
getExchangeDetails(
exchangeBaseUrl: string,
): Promise<WalletExchangeDetails | undefined>;
+ /** Check whether an exchange falls within a currency scope. */
checkExchangeInScope(
exchangeBaseUrl: string,
scope: ScopeInfo,
): Promise<boolean>;
+ /** Compute the scope (global, auditor or exchange) an exchange belongs to. */
getExchangeScopeInfo(
exchangeBaseUrl: string,
currency: string,
