POST /reserves/$RESERVE_PUB/open

Request keeping a reserve open for invoicing.

Request:

The request body must be a ReserveOpenRequest object.

Response:

200 OK:

The exchange responds with a ReserveOpenResponse object.

400 Bad Request:

The request timestamp has excessive clock skew. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW.

402 Payment Required:

The exchange responds with a ReserveOpenFailure object when the payment offered is insufficient for the requested operation.

403 Forbidden:

The TALER_SIGNATURE_WALLET_RESERVE_OPEN signature is invalid. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_RESERVES_OPEN_BAD_SIGNATURE.

404 Not found:

The reserve key does not belong to a reserve known to the exchange. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN.

409 Conflict:

The balance of the reserve or of a coin was insufficient. Which case it is can be decided by looking at the error code (TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS or TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY or TALER_EC_EXCHANGE_RESERVES_OPEN_INSUFFICIENT_FUNDS). The specific fields of the response depend on the error code and include the signatures (and what was signed over) proving the conflict. The response is WithdrawError object or a DepositDoubleSpendError depending on the error type.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

500 Internal Server Error:

The exchange encountered an internal error. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING, TALER_EC_EXCHANGE_GENERIC_BAD_CONFIGURATION, TALER_EC_GENERIC_DB_FETCH_FAILED, TALER_EC_GENERIC_DB_STORE_FAILED, or TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT.

Details:

interface ReserveOpenRequest {
  // Signature of purpose
  // TALER_SIGNATURE_WALLET_RESERVE_OPEN over
  // a TALER_ReserveOpenPS.
  reserve_sig: EddsaSignature;

  // Array of payments made towards the cost of the
  // operation.
  payments: OpenPaymentDetail[];

  // Amount to be paid from the reserve for this
  // operation.
  reserve_payment: Amount;

  // Time when the client made the request.
  // Timestamp must be reasonably close to the time of
  // the exchange, otherwise the exchange may reject
  // the request (with a status code of 400).
  request_timestamp: Timestamp;

  // Desired new expiration time for the reserve.
  // If the reserve would expire before this time,
  // the exchange will charge account fees (and
  // possibly KYC fees) until the expiration time
  // exceeds this timestamp. Note that the exchange
  // will refuse requests (with a status code of 400)
  // if the time is so far in the future that the
  // fees are not yet known (see /keys).
  reserve_expiration: Timestamp;

  // Desired open purse limit. Can be used to pay the
  // annual account fee more than once to get a larger
  // purse limit.
  purse_limit: Integer;

}

interface ReserveOpenResponse {
  // Transaction cost for extending the expiration time.
  // Excludes KYC fees.
  open_cost: Amount;

  // Current expiration time for the reserve.
  reserve_expiration: Timestamp;
}

interface ReserveOpenFailure {
  // Transaction cost that should have been paid
  // to extending the reserve as requested.
  // Excludes KYC fees.
  open_cost: Amount;

  // Remaining expiration time for the reserve.
  reserve_expiration: Timestamp;
}

interface OpenPaymentDetail {

  // Contribution of this coin to the overall amount.
  // Can be a fraciton of the coin's total value.
  amount: Amount;

  // Hash of denomination RSA key with which the coin is signed.
  denom_pub_hash: HashCode;

  // Exchange's unblinded RSA signature of the coin.
  ub_sig: DenominationSignature;

  // Age commitment for the coin, if the denomination is age-restricted.
  age_commitment?: AgeCommitment;

  // Signature over TALER_ReserveOpenDepositSignaturePS
  // of purpose TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT
  // made by the customer with the
  // coin's private key.
  coin_sig: EddsaSignature;

  // Public key of the coin being used to pay for
  // opening the reserve.
  coin_pub: EddsaPublicKey;

}