Field Reference#

Field Types#

This lists all the field types used in the protocol.

  • String: A JSON string.

  • Integer: A JSON integer.

  • BigInt: A JSON string containing a large number represented as the hex representation of it.

  • DateTime: A JSON string containing the ISO representation of a date.

  • List: A JSON list that can contain all the possible field types mentioned here.

  • URL: A JSON string containing the URL of a resource.

  • WeightedURLList: A list of 2 element tuples [Int, URL]. Useful for round-robin, but also reflects a preference. The lower the weight value, the higher the priority.

  • Schema / Object: A JSON object that conforms to the given schema.

All fields are mandatory, but can be empty in case of strings.

Fields#

additional_info#

A field where the issuer can store additional information about the currency. Free text for humans.

Type: String
Used in: CDDC

blind_signature#

The signature on the blinded hash of a payload.

Type: BigInt
Used in: ResponseMint Message

blind_signatures#

A list of BlindSignatures.

Type: List of BlindSignatures
Used in: ResponseMint Message

blinded_payload_hash#

The blinded hash of a payload.

Type: BigInt
Used in: Blind

blinds#

A List of Blinds.

Type: List of Blinds
Used in: RequestMint Message, RequestRenew Message

cdd#

Contains the Currency Description Document (CDD).

Type: CDD
Used in: CDDC

cdd_expiry_date#

The date the CDD expires.

The CDD should not be used or validated after this date.

Type: String
Used in: CDDC

cdd_location#

Location to download the CDD from.

Useful for clients to “bootstrap” a yet unknown currency.

Type: URL
Used in: CDDC, Payload

cdd_serial#

The version of the CDD.

Should be increased by 1 on a new version.

Type: Int
Used in: CDDC, MKC, RequestCDDC Message, ResponseCDDSerial Message

cdd_signing_date#

When was the CDD signed?

Type: DateTime
Used in: CDDC

cddc#

A full Currency Description Document Certificate.

Type: CDDC
Used in: ResponseCDDC Message

coins#

A list of coins.

Type: List of Coins
Used in: CoinStack Message, RequestRedeem Message, RequestRenew Message

coins_expiry_date#

Coins expire after this date.

Do not use coins after this date.

Type: DateTime
Used in: MKC

currency_divisor#

Used to express the value in units of ‘currency name’.

Example: a divisor of 100 can be used express cent values for EUR or USD.

Type: Int
Used in: CDDC

currency_name#

The name of the currency, e.g. Dollar.

Use the name of the ‘full’ unit, and not its fraction, e.g. ‘dollar’ instead of ‘cent’, and use the currency_divisor to express possible fractions.

Type: String
Used in: CDDC

denomination#

The value of the coin(s).

Type: Int
Used in: MKC, Payload

denominations#

The list of possible denominations.

Should be chosen wisely, so that it allows all possible values within the currency. Should be listed in increasing value.

Type: List of Int
Used in: CDDC, RequestMKCs Message

id#

Identifier, a somewhat redundant hash of the PublicKey

This is just a visual helper, and MUST not be relied on. Calculate the hash of the key in the wallet (client software).

Type: BigInt
Used in: CDD, CDDC, MintKey, MKC

info_service#

A list of locations where more information about the currency can be found.

This refers to human-readable information.

Type: WeightedURLList Used in: CDDC

issuer_cipher_suite#

Identifier of the cipher suite that is used.

The format is: SIGN-HASH-PADDING-BLINDING, e.g. RSA-SHA256-PSS-CHAUM82.

See cipher suites.

Type: String
Used in: CDDC

issuer_id#

The identifier (hash) of the issuer public master key in the CDDC

Type: BigInt
Used in: MKC, Payload

issuer_public_master_key#

The hash of the issuer’s public key

The only valid identifier of a currency is the master key.

Type: PublicKey
Used in: CDDC

keys#

A list of Mint Key Certificates

Type: List of MKCs
Used in: ResponseMKCs Message

message_reference#

Client internal message reference.

Set by the client, echoed by the issuer.

Type: Integer
Used in: RequestCDDSerial Message, RequestCDDC Message, RequestMint Message, RequestMKCs Message, RequestRedeem Message, RequestRenew Message, RequestResume Message, ResponseCDDSerial Message, ResponseCDDC Message, ResponseDelay Message, ResponseMint Message, ResponseMKCs Message, ResponseRedeem Message

mint_key#

The mint key that was signed in the certificate.

Type: MintKey
Used in: MKC

mint_key_id#

Identifier of the mint key used.

Type: BigInt
Used in: Blind, Payload

mint_key_ids#

What mint keys should be returned?

If left emtpy, no filter is applied.

Type: List of BigInt
Used in: RequestMKCs Message

mint_service#

A list of locations where Blinds can be minted into Coins

Type: WeightedURLList
Used in: CDDC

modulus#

The modulus of the public key

Type: BigInt
Used in: PublicKey

payload#

The payload of the coin.

Type: Payload
Used in: Coin

protocol_version#

The protocol version that was used.

Type: Url
Used in: CDDC, Payload

public_exponent#

The exponent of the public key.

Type: BigInt
Used in: PublicKey

public_mint_key#

The public key of the mint key.

Type: PublicKey
Used in: MintKey

redeem_service#

A list of locations where Coins can be redeemed.

Type: WeightedURLList
Used in: CDDC

reference#

An identifier that connects Blind, BlindSignature and blinding secrets.

Set by the client, echoed by the server.

Type: String
Used in: ResponseMint Message, Blind

renew_service#

A list of locations where Coins can be renewed.

Type: WeightedURLList
Used in: CDDC

serial#

The serial of the Coin.

This random value is generated by clients. It is used to identify coins and prevent double spending. Once the coin is spent, the serial will be stored by the issuer. It is supposed to be unique for each coin because of its sufficient long length. A high entropy (crypto grade quality) is important.

Type: BigInt
Used in: Payload

sign_coins_not_after#

Use MintKey only before this date.

Type: DateTime
Used in: MKC

sign_coins_not_before#

Use MintKey only after this date.

Type: String
Used in: MKC

signature#

A signature within a certificate.

Type: String
Used in: CDDC, Coin, MKC

status_code#

The issuer can return a status code, like in HTTP:

2XX SUCCESS
3XX DELAY / TEMPORARY ERROR
4XX PERMANENT ERROR

Type: Integer
Used in: ResponseCDDSerial Message, ResponseCDDC Message, ResponseDelay Message, ResponseMint Message, ResponseMKCs Message, ResponseRedeem Message

status_description#

Description that the issuer passes along with the status_code.

Type: String
Used in: ResponseCDDSerial Message, ResponseCDDC Message, ResponseDelay Message, ResponseMint Message, ResponseMKCs Message, ResponseRedeem Message

subject#

A message that can be passed along with the coin stack.

Can be left empty. Used informally to indicate a reason for payment etc.

Type: String
Used in: CoinStack Message

transaction_reference#

A random identifier that allows the client to resume a delayed mint/renew process.

This should be a good random number.

Type: BigInt
Used in: RequestMint Message, RequestRenew Message, RequestResume Message

type#

String identifying the type of message.

This is the id that is used for parsing the message. One of:

  • blinded payload hash

  • blind signature

  • cdd

  • cdd certificate

  • coin

  • coinstack

  • mint key certificate

  • mint key

  • payload

  • rsa public key

  • request cddc

  • request cdd serial

  • request mint key certificates

  • request mint

  • request redeem

  • request renew

  • request resume

  • response cddc

  • response cdd serial

  • response delay

  • response mint key certificates

  • response mint

  • response redeem

Type: String
Used in: ResponseMint Message, Blind, CDDC, CDDC, Coin, CoinStack Message, MKC, MKC, Payload, RequestCDDSerial Message, RequestCDDC Message, RequestMint Message, RequestMKCs Message, RequestRedeem Message, RequestRenew Message, RequestResume Message, ResponseCDDSerial Message, ResponseCDDC Message, ResponseDelay Message, ResponseMint Message, ResponseMKCs Message, ResponseRedeem Message, PublicKey