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.

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;
}