diff options
author | Nic <nic@eigel.ch> | 2024-01-10 23:44:04 +0100 |
---|---|---|
committer | Nic <nic@eigel.ch> | 2024-01-10 23:44:04 +0100 |
commit | c699ababe7f5876788f8c4d1d6f8ede2238aa92c (patch) | |
tree | 1d349828d6cb0e88542fd67d91611ad2295cedd2 /core/api-auditor.rst | |
parent | aed8524df33feaaab47c6eba963dbbe2193505d2 (diff) | |
download | docs-c699ababe7f5876788f8c4d1d6f8ede2238aa92c.tar.gz docs-c699ababe7f5876788f8c4d1d6f8ede2238aa92c.tar.bz2 docs-c699ababe7f5876788f8c4d1d6f8ede2238aa92c.zip |
merging deposit confirmations and other small fixes
Diffstat (limited to 'core/api-auditor.rst')
-rw-r--r-- | core/api-auditor.rst | 269 |
1 files changed, 67 insertions, 202 deletions
diff --git a/core/api-auditor.rst b/core/api-auditor.rst index 117e1c78..3d465ed3 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -139,184 +139,12 @@ This API is used by auditor to obtain a list of all exchanges signing keys to be This API is still experimental (and is not yet implemented at the time of this writing). -.. _purses-list: - ------------------------ -Obtaining Purses List ------------------------ - -This API is used by auditor to obtain a list of all the purses and their respective balances that the auditor is aware of. - -.. http:get:: /purses - - Get a list of all purses and their respective balances known by the auditor. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a :ts:type:`PursesList` object. - - :http:statuscode:`204 No content`: - No purses found. - - **Details:** - - .. ts:def:: PursesList - - interface PursesList { - // Purse known by the auditor. - purse: PurseEntry[]; - } - - .. ts:def:: PurseEntry - - interface PurseEntry { - - // Public online signing key of the exchange. - purse_pub: EddsaPublicKey; - - // Time when online signing key will first be use. - balance: taler_amount; - - // Time when this online signing key will no longer be used. - target: taler_amount; - - // Time when this online signing key legally expires. - expiration_date: Timestamp; - } - - .. note:: - - This API is still experimental (and is not yet implemented at the - time of this writing). - -.. _purses-list: - ------------------------ -Obtaining Reserves List ------------------------ - -This API is used by auditor to obtain a list of all the customer reserves and their respective balances that the auditor is aware of. - -.. http:get:: /reserves - - Get a list of all the reserves and their respective balances known by the auditor. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a :ts:type:`ReservesList` object. - - :http:statuscode:`204 No content`: - No reserves found. - - **Details:** - - .. ts:def:: ReservesList - - interface ReservesList { - // Reserve known by the auditor. - reserve: ReserveEntry[]; - } - - .. ts:def:: ReserveEntry - - interface ReserveEntry { - - // Public online signing key of the reserve - reserve_pub: EddsaPublicKey; - - // Balance of respective reserve. - reserve_balance: taler_amount; - - // Loss of respective reserve. - reserve_loss: taler_amount; - - // Withdraw fee balance. - withdraw_fee_balance: taler_amount; - - // Closing fee balance. - close_fee_balance: taler_amount; - - // Purse fee balance. - purse_fee_balance: taler_amount; - - // Open fee balance. - open_fee_balance: taler_amount; - - // Time when this online signing key will no longer be used. - history_fee_balance: taler_amount; - - // Time when this reserve expires. - expiration_date: Timestamp; - } - - .. note:: - - This API is still experimental (and is not yet implemented at the - time of this writing). - -.. deposit-confirmation-list: +.. _deposit-confirmation: ----------------------- -Obtaining list of deposit confirmations to check +Deposit Confirmations ----------------------- -This API is used by the auditor to obtain a list of all deposit confirmations that need to be audited by -this auditor. - -.. http:get:: /deposit-confirmation - - Get a list of all deposit confirmations to be manually audited. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a :ts:type:`DepositConfirmationList` object. This request should - virtually always be successful. - - **Details:** - - .. ts:def:: DepositConfirmationList - - interface DepositConfirmationList { - // Deposit confirmations to be audited. - deposit-confirmations: DepositConfirmation[]; - } - - .. ts:def:: DepositConfirmation - - interface DepositConfirmation { - - // Database row id of entry - row_id: Integer; - - // Time when the deposit confirmation confirmation was generated. - timestamp: Timestamp; - - // How much time does the merchant have to issue a refund - // request? Zero if refunds are not allowed. - refund_deadline: Timestamp; - - // By what time does the exchange have to wire the funds? - wire_deadline: Timestamp; - - // Amount to be deposited, excluding fee. Calculated from the - // amount with fee and the fee from the deposit request. - amount_without_fee: Amount; - } - - .. note:: - - This API is still experimental (and is not yet implemented at the - time of this writing). - -.. _deposit-confirmation: - --------------------------------- -Submitting deposit confirmations --------------------------------- - Merchants should probabilistically submit some of the deposit confirmations they receive from the exchange to auditors to ensure that the exchange does not lie about recording deposit confirmations @@ -418,17 +246,61 @@ paid out first. time of this writing). A key open question is whether the auditor should sign the response information. -.. delete-deposit-confirmation: +This API is used by the auditor to obtain a list of all deposit confirmations that the auditor +did not receive by the exchange, only by the merchant. ------------------------ -Delete audited deposit confirmation ------------------------ +.. http:get:: /deposit-confirmation + + Get a list of all deposit confirmations that were not received by the auditor from the exchange to be manually audited. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a :ts:type:`DepositConfirmationList` object. + :http:statuscode:`204 No Content`: + No missing deposit confirmations found. + + **Details:** + + .. ts:def:: DepositConfirmationList + + interface DepositConfirmationList { + // Deposit confirmations to be audited. + deposit-confirmations: DepositConfirmation[]; + } + + .. ts:def:: DepositConfirmation + + interface DepositConfirmation { + + // Database row id of entry + row_id: Integer; + + // Time when the deposit confirmation confirmation was generated. + timestamp: Timestamp; + + // How much time does the merchant have to issue a refund + // request? Zero if refunds are not allowed. + refund_deadline: Timestamp; + + // By what time does the exchange have to wire the funds? + wire_deadline: Timestamp; + + // Amount to be deposited, excluding fee. Calculated from the + // amount with fee and the fee from the deposit request. + amount_without_fee: Amount; + } + + .. note:: + + This API is still experimental (and is not yet implemented at the + time of this writing). This API is used by the auditor to delete an audited deposit confirmation. -.. http:delete:: /deposit-confirmation/$rowid +.. http:delete:: /deposit-confirmation/$SERIAL_ID - Delete deposit confirmation entry with given row id. + Delete deposit confirmation entry with given serial_id. **Response:** @@ -439,10 +311,7 @@ This API is used by the auditor to delete an audited deposit confirmation. Unauthorized request. :http:statuscode:`404 Not found`: - The deposit confirmation was already unknown. - - :http:statuscode:`409 Conflict`: - The deposit confirmation cannot be deleted anymore. + The deposit confirmation was unknown. .. note:: @@ -452,45 +321,41 @@ This API is used by the auditor to delete an audited deposit confirmation. .. balances-list: ----------------------- -Obtaining list of auditor balances to check +Obtaining list of auditor balances ----------------------- -This API is used by the auditor to obtain a list of all balances that need to be audited by -this auditor. +This API is used to obtain a list of all the balances that are stored by the auditor. .. http:get:: /balances - Get a list of all auditor balances. + Get a list of all balances stored by the auditor. **Response:** :http:statuscode:`200 OK`: - The auditor responds with a :ts:type:`BalanceList` object. This request should - virtually always be successful. + The auditor responds with a :ts:type:`BalanceList` object. + + :http:statuscode:`409 Conflict`: + Balance missing or other error occured. **Details:** - .. ts:def:: BalanceList + .. ts:def:: Balances interface BalanceList { - // Balances of the auditor. - balance: Balance[]; - } - - .. ts:def:: Balance + // Total amount reported + auditor_total_reported_balance: taler_amount; - interface Balance { - // By what time does the exchange have to wire the funds? - balance_key: string; + // Amount potentially missing + auditor_missing_balance: taler_amount; - // amount with fee and the fee from the deposit request. - balance_value: taler_amount; + //... } .. note:: This API is still experimental (and is not yet implemented at the - time of this writing). + time of this writing). The API will be further developed as needed. .. denominations-pending-list: |