POST /batch-issue/$CHARITY_ID

Send in a IssueReceiptsRequest and ask the Donau to sign all it’s contained BUDIs.

Request: IssueReceiptsRequest

Response:

200 OK:

The request was successful, and the response is a BlindedDonationReceiptSignaturesResponse. Also returned for idempotent re-requests of an already-processed batch.

400 Bad Request:

The request was malformed. This can occur when the $CHARITY_ID cannot be parsed, the budikeypairs array is empty or contains malformed entries, or the total donation amount exceeds the charity’s per-year limit. Returned with error code TALER_EC_GENERIC_PARAMETER_MALFORMED, TALER_EC_GENERIC_JSON_INVALID, or TALER_EC_DONAU_EXCEEDING_DONATION_LIMIT.

403 Forbidden:

The charity signature is invalid. Returned with error code TALER_EC_DONAU_CHARITY_SIGNATURE_INVALID.

404 Not Found:

The charity is unknown to the Donau, or at least one of the referenced donation unit keys could not be found. Returned with error code TALER_EC_DONAU_CHARITY_NOT_FOUND or TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN.

409 Conflict:

The year specified does not match the validity year for the given denomination unit key. Returned with an error code of TALER_EC_DONAU_GENERIC_DONATION_UNIT_WRONG_YEAR.

410 Gone:

The year specified is in the past, and the Donau does not permit issuing donation receipts in the past. The client should pick a donation unit from the current year. Returned with an error code of TALER_EC_DONAU_GENERIC_DONATION_UNIT_EXPIRED.

425 Too Early:

The year specified is in the future, and the Donau does not permit issuing donation receipts in the future. The client may retry the request in the specified year, at that point it may succeed. Returned with an error code of TALER_EC_DONAU_GENERIC_DONATION_UNIT_TOO_EARLY.

500 Internal Server Error:

The Donau encountered an internal error, such as a database failure or a signing helper problem. Returned with error code TALER_EC_GENERIC_DB_FETCH_FAILED or TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE

503 Service unavailable:

The donau is lacking the keys to create the donation statement. Returned with error code TALER_EC_DONAU_GENERIC_KEYS_MISSING.

Details:

interface IssueReceiptsRequest {

  // Signature by the charity approving that the
  // Donau should sign the donation receipts below.
  charity_sig: EddsaSignature;

  // Year for which the donation receipts are expected.
  // Also determines which keys are used to sign the
  // blinded donation receipts.
  year: Integer;

  // Array of blinded donation receipts to sign.
  // Must NOT be empty (if no donation receipts
  // are desired, just leave the entire donau
  // argument blank).
  budikeypairs: BlindedDonationReceiptKeyPair[];
}

interface BlindedDonationReceiptKeyPair {
  // Hash of the public key that should be used to sign
  // the donation receipt.
  h_donation_unit_pub: HashCode;

  // Blinded value to give to the Donau to sign over.
  blinded_udi: BlindedUniqueDonationIdentifier;
}

type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ;

interface RSABUDI {
  cipher: "RSA";
  rsa_blinded_identifier: string;          // Crockford Base32 encoded
}

// For donation unit signatures based on Blind Clause-Schnorr, the BUDI
// consists of the public nonce and two Curve25519 scalars which are two
// blinded challenges in the Blinded Clause-Schnorr signature scheme.
// See https://taler.net/papers/cs-thesis.pdf for details.
interface CSBUDI {
  cipher: "CS";
  cs_nonce: string;      // Crockford Base32 encoded
  cs_blinded_c0: string; // Crockford Base32 encoded
  cs_blinded_c1: string; // Crockford Base32 encoded
}

// Secret for blinding/unblinding.
// An RSA blinding secret, which is basically
// a 256-bit nonce, converted to Crockford Base32.
type BUDIBlindingKeyP = string;

interface BlindedDonationReceiptSignaturesResponse {
  // Total amount over which all the blind signatures are signing.
  issued_amount: Amount;

  // Array of the blind signatures.
  blind_signatures: BlindedDonationReceiptSignature[];
}

type BlindedDonationReceiptSignature =
  | RSABlindedDonationReceiptSignature
  | CSBlindedDonationReceiptSignature;

interface RSABlindedDonationReceiptSignature {
  cipher: "RSA";

  // (blinded) RSA signature
  blinded_rsa_signature: BlindedRsaSignature;
}

interface CSBlindedDonationReceiptSignature {
  cipher: "CS";

  // Signer chosen bit value, 0 or 1, used
  // in Clause Blind Schnorr to make the
  // ROS problem harder.
  b: Integer;

  // Blinded scalar calculated from c_b.
  s: Cs25519Scalar;
}

interface IssueError{
  max_per_year: Amount;
  current_year: Amount;
}

interface DonationUnitUnknownError{
  unknown_hash_pub_donation_unit: HashCode[];
  donau_pub: EddsaPublicKey;
  donau_sig: EddsaSignature;
}

interface DonationUnitExpiredMessage{
  h_donation_unit_pub: HashCode;
  donau_pub: EddsaPublicKey;
  donau_sig: EddsaSignature;
}