post-reveal-withdraw.rst (4499B)
1 .. http:post:: /reveal-withdraw 2 3 Reveal previously committed values to the exchange, except for the values 4 corresponding to the ``noreveal_index`` returned by the :http:post:`/withdraw </withdraw>` step. 5 6 The request body is a `RevealWithdrawRequest`. 7 8 This endpoint was introduced in this form in protocol **v32**. 9 Since protocol **v42** the request body must also carry the 10 ``reserve_pub`` of the original :http:post:`/withdraw </withdraw>` 11 request: a withdraw operation is identified by the pair 12 (``reserve_pub``, ``planchets_h``), as in 13 :http:post:`/recoup-withdraw </recoup-withdraw>`. A given 14 ``planchets_h`` may legitimately exist under more than one reserve. 15 16 :http:statuscode:`200 OK`: 17 The coin's' secret material matched the commitment and the original request was well-formed. 18 The response body is a `RevealResponse`. 19 :http:statuscode:`400 Bad Request`: 20 The request from the client is malformed. Error codes used are: 21 22 - ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` 23 - ``TALER_EC_EXCHANGE_WITHDRAW_REVEAL_INVALID_HASH`` 24 25 :http:statuscode:`404 Not found`: 26 The given reserve has no withdraw operation under the provided 27 ``planchets_h``. 28 Error code: ``TALER_EC_EXCHANGE_WITHDRAW_COMMITMENT_UNKNOWN`` 29 :http:statuscode:`413 Request entity too large`: 30 The uploaded body is to long, it exceeds the size limit. 31 Returned with an error code of 32 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 33 :http:statuscode:`500 Internal Server Error`: 34 Returned if the server had an internal issue processing the request. 35 Error codes include: 36 37 - ``TALER_EC_GENERIC_DB_FETCH_FAILED`` 38 - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` 39 40 :http:statuscode:`503 Service unavailable`: 41 The server could not process the request because it is currently 42 unavailable. Error codes include: 43 - ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` 44 45 **Details:** 46 47 Request body for a ``reveal-withdraw`` request 48 contains a JSON object with the following fields: 49 50 .. ts:def:: RevealWithdrawRequest 51 52 interface RevealWithdrawRequest { 53 54 // Public key of the reserve that the original call to 55 // ``/withdraw`` was made from. Together with ``planchets_h`` 56 // this identifies the withdraw operation. 57 // Since protocol **v42**. 58 reserve_pub: EddsaPublicKey; 59 60 // This is the running hash of all blinded planchets 61 // from the previous call to ``/withdraw``. 62 planchets_h: string; 63 64 // Array of ``(kappa - 1)`` disclosed batch secrets, 65 // from which for each of the n coins in a batch 66 // their coin master secret is derived, 67 // from which in turn their private key, 68 // blinding, nonce (for Clause-Schnorr) and 69 // age-restriction is calculated. 70 disclosed_batch_seeds: AgeRestrictedPlanchetSeed[]; 71 72 } 73 74 .. ts:def:: AgeRestrictedPlanchetSeed 75 76 // The master seed material from which for n coins in a batch, 77 // each the coins' private key ``coin_priv``, blinding ``beta`` 78 // and nonce ``nonce`` (for Clause-Schnorr) itself are 79 // derived as usually in wallet-core. Given a coin's master key material, 80 // the age commitment for the coin MUST be derived from this private key as 81 // follows: 82 // 83 // Let m ∈ {1,...,M} be the maximum age group as defined in the reserve 84 // that the wallet can commit to. 85 // 86 // For age group $AG ∈ {1,...m}, set 87 // seed = HDKF(coin_secret, "age-commitment", $AG) 88 // p[$AG] = Edx25519_generate_private(seed) 89 // and calculate the corresponding Edx25519PublicKey as 90 // q[$AG] = Edx25519_public_from_private(p[$AG]) 91 // 92 // For age groups $AG ∈ {m+1,...,M}, set 93 // f[$AG] = HDKF(coin_secret, "age-factor", $AG) 94 // and calculate the corresponding Edx25519PublicKey as 95 // q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG]) 96 // 97 type AgeRestrictedPlanchetSeed = string; 98 99 .. ts:def:: PublishedAgeRestrictionBaseKey 100 101 // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen 102 // `Edx25519PublicKey` for which the private key is not known to the clients. It is 103 // used during the age-withdraw protocol so that clients can prove that they 104 // derived all public keys to age groups higher than their allowed maximum 105 // from this particular value. 106 const PublishedAgeRestrictionBaseKey = 107 new Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG");