Schemata#

In here we present the actual schemata for the all the messages that we send and receive in the OpenCoin protocol. Each schema contains a description, a list of its fields and an example. The field names are linked to the fields page, where you can more detailed information about the fields.

Note

The examples are produced by the run_protocol.py script.

Elements of messages#

CDD#

The Currency Description Document holds all information about a currency that is following the OpenCoin protocol.

It contains the master key, the denominations, the services, the name of the currency and more.

Always part of a CDDC

Fields#

additional_info: A field where the issuer can store additional information about the currency. Free text for humans. (String)
cdd_expiry_date: The date the CDD expires. (String)
cdd_location: Location to download the CDD from. (URL)
cdd_serial: The version of the CDD. (Int)
cdd_signing_date: When was the CDD signed? (DateTime)
currency_divisor: Used to express the value in units of ‘currency name’. (Int)
currency_name: The name of the currency, e.g. Dollar. (String)
denominations: The list of possible denominations. (List of Int)
id: Identifier, a somewhat redundant hash of the PublicKey (BigInt)
info_service: A list of locations where more information about the currency can be found. (WeightedURLList)
redeem_service: A list of locations where Coins can be redeemed. (WeightedURLList)
issuer_cipher_suite: Identifier of the cipher suite that is used. (String)
issuer_public_master_key: The hash of the issuer’s public key (PublicKey)
protocol_version: The protocol version that was used. (Url)
renew_service: A list of locations where Coins can be renewed. (WeightedURLList)
type: String identifying the type of message. (String)
mint_service: A list of locations where Blinds can be minted into Coins (WeightedURLList)

Example#

{
  "additional_info": "",
  "cdd_expiry_date": "2023-07-22T15:45:53.164685",
  "cdd_location": "https://opencent.org",
  "cdd_serial": 1,
  "cdd_signing_date": "2022-07-22T15:45:53.164685",
  "currency_divisor": 100,
  "currency_name": "OpenCent",
  "denominations": [1, 2, 5],
  "id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
  "info_service": [
        [10, "https://opencent.org"]
      ],
  "issuer_cipher_suite": "RSA-SHA256-PSS-CHAUM82",
  "issuer_public_master_key": {
    "modulus": "daaa63ddda38c189b8c49020c8276adbe0a695685a...",
    "public_exponent": 65537,
    "type": "rsa public key"
  },
  "mint_service": [
        [10, "https://opencent.org"],
    [20, "https://opencent.com/validate"]
      ],
  "protocol_version": "https://opencoin.org/1.0",
  "redeem_service": [
        [10, "https://opencent.org"]
      ],
  "renew_service": [
        [10, "https://opencent.org"]
      ],
  "type": "cdd"
}

Complete example: cdd.json

Secret key#

To make this documentation completely reproducible, here is the data for the secret issuer key:

{
  "d": "19ed9857e71751c39dd818eafa30ca57f6246a94ec...",
  "n": "daaa63ddda38c189b8c49020c8276adbe0a695685a..."
}

Complete example: issuer_secret.json

Warning

Don’t ever publish your secret keys!

CDDC#

The certificate for the CDD, signed with the secret master key. This is the “trust anchor”.

Fields#

cdd: Contains the Currency Description Document (CDD). (CDD)
signature: A signature within a certificate. (String)
type: String identifying the type of message. (String)

Example#

{
  "cdd": {
    "additional_info": "",
    "cdd_expiry_date": "2023-07-22T15:45:53.164685",
    "cdd_location": "https://opencent.org",
    "cdd_serial": 1,
    "cdd_signing_date": "2022-07-22T15:45:53.164685",
    "currency_divisor": 100,
    "currency_name": "OpenCent",
    "denominations": [1, 2, 5],
    "id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
    "info_service": [
        [10, "https://opencent.org"]
      ],
    "issuer_cipher_suite": "RSA-SHA256-PSS-CHAUM82",
    "issuer_public_master_key": {
      "modulus": "daaa63ddda38c189b8c49020c8276adbe0a695685a...",
      "public_exponent": 65537,
      "type": "rsa public key"
    },
    "mint_service": [
        [10, "https://opencent.org"],
      [20, "https://opencent.com/validate"]
      ],
    "protocol_version": "https://opencoin.org/1.0",
    "redeem_service": [
        [10, "https://opencent.org"]
      ],
    "renew_service": [
        [10, "https://opencent.org"]
      ],
    "type": "cdd"
  },
  "signature": "3fc265677973b6308dd665b66750cd27911e8a7b5c...",
  "type": "cdd certificate"
}

Complete example: cddc.json

PublicKey#

Schema to hold public keys. We have decided for our own format because we want to keep things simple. Using a predefined format would probably lead to use bigger libraries when implementing the protocol.

Always part of a CDD or MKC.

Fields#

modulus: The modulus of the public key (BigInt)
public_exponent: The exponent of the public key. (BigInt)
type: String identifying the type of message. (String)

Example#

{
  "modulus": "daaa63ddda38c189b8c49020c8276adbe0a695685a...",
  "public_exponent": 65537,
  "type": "rsa public key"
}

Complete example: issuer_public_master_key.json

MintKey#

This describes a key that is used to sign/mint coins for a single denomination. As the key doesn’t see the content it is signing (it is blinded, after all), we need to define the meaning of its signature: “this signature is worth n units of value”.

The key will be used for a period of time, after which it is going to be swapped for a new one. The coins will be valid a bit longer then the signing time of the key.

Warning

Never use the mint key for encryption, only ever for signing!

Always part of an MKC

Fields#

cdd_serial: The version of the CDD. (Int)
coins_expiry_date: Coins expire after this date. (DateTime)
denomination: The value of the coin(s). (Int)
id: Identifier, a somewhat redundant hash of the PublicKey (BigInt)
issuer_id: The identifier (hash) of the issuer public master key in the CDDC (BigInt)
public_mint_key: The public key of the mint key. (PublicKey)
sign_coins_not_after: Use MintKey only before this date. (DateTime)
sign_coins_not_before: Use MintKey only after this date. (String)
type: String identifying the type of message. (String)

Example#

{
  "cdd_serial": 1,
  "coins_expiry_date": "2023-10-30T15:45:53.164685",
  "denomination": 1,
  "id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
  "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
  "public_mint_key": {
    "modulus": "ce3af9b91d6a6da0fe8def8870743428c0c4c60f5a...",
    "public_exponent": 65537,
    "type": "rsa public key"
  },
  "sign_coins_not_after": "2023-07-22T15:45:53.164685",
  "sign_coins_not_before": "2022-07-22T15:45:53.164685",
  "type": "mint key"
}

Complete example: mintkey_1.json

Secret key#

To make this documentation completely reproducible, here is the data for the secret mint key for the value 1:

{
  "d": "31d379e649bf1f0198befe327ec8f4992c09deb872...",
  "n": "ce3af9b91d6a6da0fe8def8870743428c0c4c60f5a..."
}

Complete example: mintkey_1_secret.json

Warning

Don’t ever publish your secret keys!

MKC#

A Mint Key Certificate for the MKC. Signed with the secret master key in the CDD.

Fields#

mint_key: The mint key that was signed in the certificate. (MintKey)
signature: A signature within a certificate. (String)
type: String identifying the type of message. (String)

Example#

{
  "mint_key": {
    "cdd_serial": 1,
    "coins_expiry_date": "2023-10-30T15:45:53.164685",
    "denomination": 1,
    "id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
    "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
    "public_mint_key": {
      "modulus": "ce3af9b91d6a6da0fe8def8870743428c0c4c60f5a...",
      "public_exponent": 65537,
      "type": "rsa public key"
    },
    "sign_coins_not_after": "2023-07-22T15:45:53.164685",
    "sign_coins_not_before": "2022-07-22T15:45:53.164685",
    "type": "mint key"
  },
  "signature": "84aceee2562297d127560bff4d66654e881e89eae2...",
  "type": "mint key certificate"
}

Complete example: mkc_1.json

Payload#

These are the “innards” of Coin. The mint key id is only a helper so that the corresponding key for the signature of the coin can be found faster. The same is true for the denomination - an implementation should take the coins value from the MintKey, and not from the contents of the Payload, because the values in the Payload are user defined.

Fields#

cdd_location: Location to download the CDD from. (URL)
denomination: The value of the coin(s). (Int)
issuer_id: The identifier (hash) of the issuer public master key in the CDDC (BigInt)
mint_key_id: Identifier of the mint key used. (BigInt)
protocol_version: The protocol version that was used. (Url)
serial: The serial of the Coin. (BigInt)
type: String identifying the type of message. (String)

Example#

{
  "cdd_location": "https://opencent.org",
  "denomination": 1,
  "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
  "mint_key_id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
  "protocol_version": "https://opencoin.org/1.0",
  "serial": "cd613e30d8f16adf91b7584a2265b1f5",
  "type": "payload"
}

Complete example: payload_a0.json

BlindSignature#

The signature for a blind. The blind is specified with the reference.

Fields#

blind_signature: The signature on the blinded hash of a payload. (BigInt)
reference: An identifier that connects Blind, BlindSignature and blinding secrets. (String)
type: String identifying the type of message. (String)

Example#

{
  "blind_signature": "57744b5430075756d246ceff94f47e9ffeb80af3d8...",
  "reference": "a0",
  "type": "blind signature"
}

Complete example: blind_signature_a0.json

Coin#

The certificate for a payload. The signature is the unblinded BlindSignature.

Fields#

payload: The payload of the coin. (Payload)
signature: A signature within a certificate. (String)
type: String identifying the type of message. (String)

Example#

{
  "payload": {
    "cdd_location": "https://opencent.org",
    "denomination": 1,
    "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
    "mint_key_id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
    "protocol_version": "https://opencoin.org/1.0",
    "serial": "cd613e30d8f16adf91b7584a2265b1f5",
    "type": "payload"
  },
  "signature": "2ec0af339566b19fb9867b491ce58025dcefcab649...",
  "type": "coin"
}

Complete example: coin_a0.json

Messages#

RequestCDDSerial Message#

This message asks for the cdd_serial of the current CDDC.

Fields#

message_reference: Client internal message reference. (Integer)
type: String identifying the type of message. (String)

Example#

{
  "message_reference": 100000,
  "type": "request cdd serial"
}

Complete example: request_cddc_serial.json

ResponseCDDSerial Message#

Returns the current cdd_serial.

Fields#

cdd_serial: The version of the CDD. (Int)
message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "cdd_serial": 1,
  "message_reference": 100000,
  "status_code": 200,
  "status_description": "ok",
  "type": "response cdd serial"
}

Complete example: response_cddc_serial.json

RequestCDDC Message#

This requests the CDDC specified by the cdd_serial. If cdd_serial is set to 0, the most current CDDC is returned.

Fields#

cdd_serial: The version of the CDD. (Int)
message_reference: Client internal message reference. (Integer)
type: String identifying the type of message. (String)

Example#

{
  "cdd_serial": 1,
  "message_reference": 100001,
  "type": "request cddc"
}

Complete example: request_cddc.json

ResponseCDDC Message#

This response carries the CDDC.

Fields#

cddc: A full Currency Description Document Certificate. (CDDC)
message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "cddc": {
    "cdd": {
      "additional_info": "",
      "cdd_expiry_date": "2023-07-22T15:45:53.164685",
      "cdd_location": "https://opencent.org",
      "cdd_serial": 1,
      "cdd_signing_date": "2022-07-22T15:45:53.164685",
      "currency_divisor": 100,
      "currency_name": "OpenCent",
      "denominations": [1, 2, 5],
      "id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
      "info_service": [
        [10, "https://opencent.org"]
      ],
      "issuer_cipher_suite": "RSA-SHA256-PSS-CHAUM82",
      "issuer_public_master_key": {
        "modulus": "daaa63ddda38c189b8c49020c8276adbe0a695685a...",
        "public_exponent": 65537,
        "type": "rsa public key"
      },
      "mint_service": [
        [10, "https://opencent.org"],
        [20, "https://opencent.com/validate"]
      ],
      "protocol_version": "https://opencoin.org/1.0",
      "redeem_service": [
        [10, "https://opencent.org"]
      ],
      "renew_service": [
        [10, "https://opencent.org"]
      ],
      "type": "cdd"
    },
    "signature": "3fc265677973b6308dd665b66750cd27911e8a7b5c...",
    "type": "cdd certificate"
  },
  "message_reference": 100001,
  "status_code": 200,
  "status_description": "ok",
  "type": "response cddc"
}

Complete example: response_cddc.json

RequestMKCs Message#

This requests one or more MKCs. The fields denominations and mint_key_ids specify which MKCs should be delivered. Denominations refer to the most current key(s) for the given denominations. If both fields are empty, all most current MKCs are delivered - we assume that is the normal use case.

Fields#

denominations: The list of possible denominations. (List of Int)
message_reference: Client internal message reference. (Integer)
mint_key_ids: What mint keys should be returned? (List of BigInt)
type: String identifying the type of message. (String)

Example#

{
  "denominations": [1, 2, 5],
  "message_reference": 100002,
  "mint_key_ids": [],
  "type": "request mint key certificates"
}

Complete example: request_mkc.json

ResponseMKCs Message#

This delivers the [MKCs] as specified in the RequestMKCs.

Fields#

keys: A list of Mint Key Certificates (List of MKCs)
message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "keys": [
    {
      "mint_key": {
        "cdd_serial": 1,
        "coins_expiry_date": "2023-10-30T15:45:53.164685",
        "denomination": 1,
        "id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "public_mint_key": {
          "modulus": "ce3af9b91d6a6da0fe8def8870743428c0c4c60f5a...",
          "public_exponent": 65537,
          "type": "rsa public key"
        },
        "sign_coins_not_after": "2023-07-22T15:45:53.164685",
        "sign_coins_not_before": "2022-07-22T15:45:53.164685",
        "type": "mint key"
      },
      "signature": "84aceee2562297d127560bff4d66654e881e89eae2...",
      "type": "mint key certificate"
    },
    {
      "mint_key": {
        "cdd_serial": 1,
        "coins_expiry_date": "2023-10-30T15:45:53.164685",
        "denomination": 2,
        "id": "f2864e5cd937dbaa4825e73a81062de162143682",
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "public_mint_key": {
          "modulus": "ca03c4fa5a94144c5649d1f5d7cb9780e45911323c...",
          "public_exponent": 65537,
          "type": "rsa public key"
        },
        "sign_coins_not_after": "2023-07-22T15:45:53.164685",
        "sign_coins_not_before": "2022-07-22T15:45:53.164685",
        "type": "mint key"
      },
      "signature": "2db1d5a728a841f415f414a07767b7d43ab3d62235...",
      "type": "mint key certificate"
    },
    {
      "mint_key": {
        "cdd_serial": 1,
        "coins_expiry_date": "2023-10-30T15:45:53.164685",
        "denomination": 5,
        "id": "897a16bf12bd9ba474ef7be0e3a53553a7b4ece8",
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "public_mint_key": {
          "modulus": "d35f9a322c851eb071f557f8b5723d10c7889ad7ba...",
          "public_exponent": 65537,
          "type": "rsa public key"
        },
        "sign_coins_not_after": "2023-07-22T15:45:53.164685",
        "sign_coins_not_before": "2022-07-22T15:45:53.164685",
        "type": "mint key"
      },
      "signature": "9a76c1f3223817de54632b9f2eb5c94a0426d26738...",
      "type": "mint key certificate"
    }
  ],
  "message_reference": 100002,
  "status_code": 200,
  "status_description": "ok",
  "type": "response mint key certificates"
}

Complete example: response_mkc.json

RequestMint Message#

Request blinds to be signed. The Blinds hold the information which mint keys are to be used for minting.

The client asking for this action should be authenticated, and the issuer should check if the client meets the requirements of the request, a.k.a. has enough funds to pay for the minting process.

Fields#

blinds: A List of Blinds. (List of Blinds)
message_reference: Client internal message reference. (Integer)
transaction_reference: A random identifier that allows the client to resume a delayed mint/renew process. (BigInt)
type: String identifying the type of message. (String)

Example#

{
  "blinds": [
    {
      "blinded_payload_hash": "924edb672c3345492f38341ff86b57181da4c673ef...",
      "mint_key_id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
      "reference": "a0",
      "type": "blinded payload hash"
    },
    {
      "blinded_payload_hash": "95db92e1c46ebea5edec5e508a831263de6fb78b4c...",
      "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
      "reference": "a1",
      "type": "blinded payload hash"
    },
    {
      "blinded_payload_hash": "10afac98ac43eb40e996c621d5db4d2238348e3f74...",
      "mint_key_id": "897a16bf12bd9ba474ef7be0e3a53553a7b4ece8",
      "reference": "a2",
      "type": "blinded payload hash"
    }
  ],
  "message_reference": 100003,
  "transaction_reference": "b2221a58008a05a6c4647159c324c985",
  "type": "request mint"
}

Complete example: request_mint.json

ResponseMint Message#

This delivers the BlindSignatures. The client will derive the signature for the Coins by unblinding the BlindSignatures.

Fields#

blind_signatures: A list of BlindSignatures. (List of BlindSignatures)
message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "blind_signatures": [
    {
      "blind_signature": "57744b5430075756d246ceff94f47e9ffeb80af3d8...",
      "reference": "a0",
      "type": "blind signature"
    },
    {
      "blind_signature": "568bcaa9357d0fce7649c9217f275d277bb89721f4...",
      "reference": "a1",
      "type": "blind signature"
    },
    {
      "blind_signature": "a8206a048987d9372232b7a084325ca26b4b151dda...",
      "reference": "a2",
      "type": "blind signature"
    }
  ],
  "message_reference": 100003,
  "status_code": 200,
  "status_description": "ok",
  "type": "response mint"
}

Complete example: response_mint_a.json

CoinStack Message#

This holds a set of coins. It is not a message in the strict sense, but more a transport container. Transferring the CoinStack in a manner that is untraceable by the issuer is key to protecting the privacy. How this is achieved is outside the protocol, and left as an exercise to the implementer :-)

Fields#

coins: A list of coins. (List of Coins)
subject: A message that can be passed along with the coin stack. (String)
type: String identifying the type of message. (String)

Example#

{
  "coins": [
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 1,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "cd613e30d8f16adf91b7584a2265b1f5",
        "type": "payload"
      },
      "signature": "2ec0af339566b19fb9867b491ce58025dcefcab649...",
      "type": "coin"
    },
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 2,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "78e510617311d8a3c2ce6f447ed4d57b",
        "type": "payload"
      },
      "signature": "6aefa7472518ed0a1ec64971220ce3a3a921a70bb0...",
      "type": "coin"
    },
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 5,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "897a16bf12bd9ba474ef7be0e3a53553a7b4ece8",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "e4b06ce60741c7a87ce42c8218072e8c",
        "type": "payload"
      },
      "signature": "72da93670f666c529f26fcf15092a63c0fa48c8387...",
      "type": "coin"
    }
  ],
  "subject": "a little gift",
  "type": "coinstack"
}

Complete example: coinstack.json

RequestRenew Message#

Coins that are received need to be swapped for new ones, in order to protect the receiver against double spending. Otherwise, the sender could keep a copy of the coins and try to use the coins again. Before doing so we need to ask: what coin sizes should be chosen for the coins to be minted?

What if we have not the right coin selection (“change”) for an amount to pay? Imagine that the price is 5 opencent, but we just have coins in the sizes: 2, 2, 2.

One solution would be to require the recipient to give change back to the client. This would complicate the protocol, and would just shift the problem to the recipient. Another approach is to allow partial spending coins, but this again makes the protocol more complicated. ¹ ¹GNU Taler experiments with this approach: in essence coins don’t have serials but keys, which can sign a partial amount to be spent. This requires more smartness to avoid double spending, introducing new problems to be solved.

The easy way out is to aim for a selection of coins that allows us to pay any amount below or equal to the sum of all coins. E.g. if we own the sum of 6 opencent it would be advisable to have coins in the selection of 2,2,1,1 in order to pay all possible amounts. This also prevents amount tracing, where an awkward price (13.37) asks for an awkward coin exchange at the issuer beforehand.

So, we need to look at the combined sum of coins received and coins already in possession, and need to find the right coin selection to be able to make all possible future coin transfers. We then need to know which coins to keep, and what blinds to make and paying for the minting using all the just received coins and using some existing coins.

Also see Tokenizing for a sample implementation of a solution.

Fields#

blinds: A List of Blinds. (List of Blinds)
coins: A list of coins. (List of Coins)
message_reference: Client internal message reference. (Integer)
transaction_reference: A random identifier that allows the client to resume a delayed mint/renew process. (BigInt)
type: String identifying the type of message. (String)

Example#

{
  "blinds": [
    {
      "blinded_payload_hash": "7ed0cda1c1b36f544514b12848b8436974b7b9f6c7...",
      "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
      "reference": "b0",
      "type": "blinded payload hash"
    },
    {
      "blinded_payload_hash": "8924dbcf75ab40e3bd3b4d38315722c981fe10946d...",
      "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
      "reference": "b1",
      "type": "blinded payload hash"
    },
    {
      "blinded_payload_hash": "278fc8e4bd861b7206c065004296af57e14963d928...",
      "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
      "reference": "b2",
      "type": "blinded payload hash"
    },
    {
      "blinded_payload_hash": "2995fd1b9e61926d757a516357f9814e20869fe722...",
      "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
      "reference": "b3",
      "type": "blinded payload hash"
    }
  ],
  "coins": [
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 1,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "1ceb977bb531c65f133ab8b0d60862b17369d96",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "cd613e30d8f16adf91b7584a2265b1f5",
        "type": "payload"
      },
      "signature": "2ec0af339566b19fb9867b491ce58025dcefcab649...",
      "type": "coin"
    },
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 2,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "78e510617311d8a3c2ce6f447ed4d57b",
        "type": "payload"
      },
      "signature": "6aefa7472518ed0a1ec64971220ce3a3a921a70bb0...",
      "type": "coin"
    },
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 5,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "897a16bf12bd9ba474ef7be0e3a53553a7b4ece8",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "e4b06ce60741c7a87ce42c8218072e8c",
        "type": "payload"
      },
      "signature": "72da93670f666c529f26fcf15092a63c0fa48c8387...",
      "type": "coin"
    }
  ],
  "message_reference": 100004,
  "transaction_reference": "ad45f23d3b1a11df587fd2803bab6c39",
  "type": "request renew"
}

Complete example: request_renew.json

ResponseDelay Message#

This message is used by the issuer to signal a delay in minting or renewing coins. It is recommended to set up the issuer to be fast and reliable enough to never use this message.

Fields#

message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "message_reference": 100004,
  "status_code": 300,
  "status_description": "ok",
  "type": "response delay"
}

Complete example: response_delay.json

RequestResume Message#

This message request that an action that was delayed before with a ResponseDelay is to be resumed. Either a ResponseMint is returned, or another ResponseDelay if the client is unlucky.

Fields#

message_reference: Client internal message reference. (Integer)
transaction_reference: A random identifier that allows the client to resume a delayed mint/renew process. (BigInt)
type: String identifying the type of message. (String)

Example#

{
  "message_reference": 100005,
  "transaction_reference": "ad45f23d3b1a11df587fd2803bab6c39",
  "type": "request resume"
}

Complete example: request_resume.json

RequestRedeem Message#

This message aks for coins to be redeemed, e.g. converted for real-world money.

The client needs to be authenticated for this request (outside this protocol), so that the issuer knows who to credit the value of the coins to.

Fields#

coins: A list of coins. (List of Coins)
message_reference: Client internal message reference. (Integer)
type: String identifying the type of message. (String)

Example#

{
  "coins": [
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 2,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "cd447e35b8b6d8fe442e3d437204e52d",
        "type": "payload"
      },
      "signature": "11b6bfa18134c300f4440df1db17a08fa71a071b71...",
      "type": "coin"
    },
    {
      "payload": {
        "cdd_location": "https://opencent.org",
        "denomination": 2,
        "issuer_id": "23ed956e629ba35f0002eaf833ea436aea7db5c2",
        "mint_key_id": "f2864e5cd937dbaa4825e73a81062de162143682",
        "protocol_version": "https://opencoin.org/1.0",
        "serial": "5b6e6e307d4bedc51431193e6c3f339",
        "type": "payload"
      },
      "signature": "a6dd7b7f1f12c4e411289e8ea0355f24a8597bbc38...",
      "type": "coin"
    }
  ],
  "message_reference": 100006,
  "type": "request redeem"
}

Complete example: request_redeem.json

ResponseRedeem Message#

This just answers to a RequestRedeem, and doesn’t hold other meaningful information.

Fields#

message_reference: Client internal message reference. (Integer)
status_code: The issuer can return a status code, like in HTTP: (Integer)
status_description: Description that the issuer passes along with the status_code. (String)
type: String identifying the type of message. (String)

Example#

{
  "message_reference": 100006,
  "status_code": 200,
  "status_description": "ok",
  "type": "response redeem"
}

Complete example: response_redeem.json

OpenCoinv0.4

Schemata

Contents

Schemata#

Elements of messages#

CDD#

Fields#

Example#

Secret key#

CDDC#

Fields#

Example#

PublicKey#

Fields#

Example#

MintKey#

Fields#

Example#

Secret key#

MKC#

Fields#

Example#

Payload#

Fields#

Example#

Blind#

Fields#

Example#

BlindSignature#

Fields#

Example#

Coin#

Fields#

Example#

Messages#

RequestCDDSerial Message#

Fields#

Example#

ResponseCDDSerial Message#

Fields#

Example#

RequestCDDC Message#

Fields#

Example#

ResponseCDDC Message#

Fields#

Example#

RequestMKCs Message#

Fields#

Example#

ResponseMKCs Message#

Fields#

Example#

RequestMint Message#

Fields#

Example#

ResponseMint Message#

Fields#

Example#

CoinStack Message#

Fields#

Example#

RequestRenew Message#

Fields#

Example#

ResponseDelay Message#

Fields#

Example#

RequestResume Message#

Fields#

Example#

RequestRedeem Message#

Fields#

Example#

ResponseRedeem Message#

Fields#

Example#

OpenCoin

v0.4