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.

403 Forbidden:

The charity signature is invalid. This response comes with a standard ErrorDetail response.

404 Not found:

At least one of the donation unit keys is not known to the Donau. Comes with a DonationUnitUnknownError. This suggests a bug in the donor as it should have used current donation unit keys from /keys.

409 Conflict:

The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis. The response is a IssueError object.

410 Gone:

The requested donation unit key is not yet or no longer valid. It either before the validity year, past the year or was revoked. The response is a DonationUnitExpiredMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.

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