diff options
Diffstat (limited to 'api-mint.rst')
| -rw-r--r-- | api-mint.rst | 85 |
1 files changed, 50 insertions, 35 deletions
diff --git a/api-mint.rst b/api-mint.rst index 9d158a5f..ea7a6b17 100644 --- a/api-mint.rst +++ b/api-mint.rst @@ -156,49 +156,56 @@ In order group multipe coins, the customer generates a refreshing session key. .. _refresh: .. http:post:: /refresh/melt - "Melt" coins, marking it for refreshing. Invalidates the coins. + "Melt" coins. Invalidates the coins and prepares for minting of fresh coins. The request body must contain a JSON object with the following fields: - :<json array melt_coins: List of coins to refresh. - :<json array new_denoms: List of new denominations to order. + :<json array new_denoms: List of `n` new denominations to order. :<json string session_pub: Session public key + :<json string session_sig: Signature over the whole commitment + :<json array coin_evs: For each of the `n` new coin, `kappa` coin blanks. + :<json array transfer_pubs: List of `m` transfer public keys + :<json array new_encs: For each of the `n` new coins, a list of encryptions (one for each cnc instance) + :<json array secret_encs: For each of the `kappa` cut-and-choose instances, the linking encryption for each of the `m` old coins + :<json array melt_coins: List of `m` coins to melt. The `melt_coins` field is a list of JSON objects with the following fields: - :json string coin_pub: Coin public key - :json string coin_sig: Signature by the coin over the session public key - :json string denom_pub: Denomination public key - :json string denom_sig: Signature over the coin public key by the denomination - key - :json obj retract_perm (optional): If the coin was claimed as a refund, this - field should contain the retract permission obtained from the merchant, - otherwise it should not be present. For details about the object type, see - :ref:`Merchant API:retract<retract>`. - + :<json string coin_pub: Coin public key + :<json string coin_sig: Signature by the coin over the session public key + :<json string denom_pub: Denomination public key + :<json string denom_sig: Signature over the coin public key by the denomination + key + :<json string value: Amount of the value of the coin that should be melted as part of this refresh operation **Success Response** - :status 200 OK: The request was succesful. In that case, the responst body is a json - object with `kappa` blind session keys for each new coin. + :status 200 OK: The request was succesful. The response body contains a JSON object with the following fields: + * `noreveal_index`: Which of the `kappa` indices does the client not have to reveal. + * `mint_sig`: Signature of the mint affirming the successful melt and confirming the `noreveal_index` + **Error Responses** :status 400 Bad Request: A request parameter is missing or malformed. - :status 401 Gone: The coin `coin` has already been refreshed. - :status 403 Forbidden: Either `csig` or `ssig` is invalid. + + :status 401 Gone: A coin `coin` has insufficient funds. Request body contains a JSON object with + the following fields: + + :<fixme: Details showing that `coin` has insufficient funds to satisfy the request. + + :status 403 Forbidden: Either a `coin_sig` or the `session_sig` is invalid. + + :status 404 Not Found: The mint does not know one of the denomination keys `denom_pub` given in the request. + + + .. http:post:: /refresh/reveal .. http:post:: /refresh/commit Commit values for the cut-and-choose in the refreshing protocol. The request body must be a JSON object with the following fields: - :<json string session_pub: Session to commit values for - :<json string session_sig: Signature over the whole commitment - :<json array coin_evs: For each new coin, `kappa` coin blanks. - :<json array transfer_pubs: List of transfer public keys - :<json array new_encs: For each new coin, a list of encryptions (one for each cnc instance) - :<json array secret_encs: For each cut-and-choose instance, the linking encryption for each old coin **Success Response** @@ -230,21 +237,18 @@ In order group multipe coins, the customer generates a refreshing session key. :>json array bcsig_list: List of the mint's blind signatures on the ordered new coins. - :status 202 Accepted: The revealed value was accepted, but the mint requires - more reveals. - - **Error Responses** - - If the reveal is incomplete, the JSON object contains: - - :>json array reveal_missing: List of blinding keys with missing reveals from - the customer. :status 400 Bad Request: Request parameters incomplete or malformed. :status 403 Forbidden: The signature `ssig` is invalid. :status 404 Not Found: The blinding key is not known to the mint. :status 409 Conflict: The revealed value was inconsistent with the commitment. + + * `original_info`: signed information from /refresh/melt that conflicts with the current /refresh/reveal request. + :status 410 Gone: A conflict occured, the money is gone. + * `conflict_info`: proof of previous attempt by the client to cheat + + .. http:get:: /refresh/link Link an old key to the refreshed coin. @@ -356,12 +360,25 @@ deposit permission for the coin from the customer. In these failures, the response contains an error string describing the reason why the request has failed. +.. _restract: +.. http:POST:: /retract + + Undo deposit of the given coin, restoring its value. The request + should contain a JSON object with the following fields: + + :json obj retract_perm: If the coin was claimed as a refund, this + field should contain the retract permission obtained from the merchant, + otherwise it should not be present. For details about the object type, see + :ref:`Merchant API:retract<retract>`. + :json string retract_value: Value returned due to the retraction. + + .. _deposit: .. http:POST:: /deposit Deposit the given coin and ask the mint to transfer the given amount to the merchants bank account. The request should contain a JSON object with the - following fields + following fields: :<json string C: coin's public key :<json string K: denomination key with which the coin is signed @@ -637,5 +654,3 @@ The `encrypted` block denotes an encrypted message. struct PublicKey tpks[n]; struct RefreshEnc encs[n]; }; - - |