**鑰匙庫 Keeper** 是 Token 應用系統的私鑰管理服務，類似于手機加密貨幣錢包，提供生成、保存私鑰和簽名的服務，Keeper 以 Docker 鏡像部署于業務系統的內部環境，并通過接口進行內網訪問，通過加密等防護措施確保私鑰安全。具體接口如下： [TOC] ## 演示環境 接口地址：https://47.104.196.35/bwallet/…… 目前測試環境中使用的種子為： ~~~ "mnemonic": "donate hedgehog exit connect fly cargo velvet basic portion injury vehicle juice", "seed": "f0a09a464d5c6d7af067841efc5d475f53f58fcb39b87716506a713b9fdb865e4391fd9457de77be98e45f487c3a02f23408859c63124e40a8078ae758e6e6e5" ~~~ 雖然可以使用 generateseed 接口無限制的生成種子，但是一旦某種子被啟用，在后繼的生成私鑰的操作中，該種子不可變更。除非清空數據庫才可以重新啟用新的種子，派生新的私鑰。 ## 接口 ### 1. 生成種子 <span id="api00"></span> 接口名稱：/api/v2/generate_seed 請求方法：GET 響應類型：JSON 狀態：有效 接口描述：向私鑰管理服務請求生成密鑰種子，一旦使用了某密鑰種子，請妥善保存該種子，可以將其記錄與紙質文件或U盤中，由重要的人保管！ ~~~[api:keeper] get:/api/v2/generate_seed <<< success { "code": 0, "data": { "mnemonic": "supply disagree case say pipe unit use raw test faith mistake hole", "seed": "05e8585bb7d5f6a3a7059c17c6213a980a34619edfe46b858553556e2c79041e8a30f8e1abd23ed27b7b60f0c34b1575cab254c67b8e9d9fcbf9439c1516e59a" } } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | mnemonic | string | 種子助記詞 | | seed | string | 種子 | ### 2. 批量生成地址 <span id="api01"></span> 接口名稱：/api/v2/generate_keys 請求方法：POST 響應類型：JSON 狀態：有效 接口描述：向私鑰管理服務請求生成新的私鑰，私鑰加密保存在內網，返回對應的公鑰和地址，這里生成的地址都是未分配使用的。私鑰的加密是定期更新的，確保即使加密被破解，也僅僅會影響一段時間的安全性。 ~~~[api:keeper] post:/api/v2/generate_keys *string:seed#生成私鑰所需要的種子 *number:amount#新生成地址數量 string:network_id#1:測試網絡(缺省),4:正式網絡 <<< success { "code": 0, "data": [ { "pubKey": "f25fad5ae82804d3e990af6a1b5379dabae5fafd5f26a5295f6cbfc2b33e8989b896192bf14be8c0b2bab184242bc569bccfae224b511a65fd1c51c4f85a96d8", "address": "AUUk3GpbpZum_B5YKLGgQT3FhaXNbN0QGA", "index": 0 }, { "pubKey": "483c5cb5d57bbe2b8223548269dd65d7f9c8d2ceb7b8afa8fa7da7a27960475db45be102e5aa396600d12f1864b2bc6e1c7d5601a37acf28f4c0444de02fe61b", "address": "AfdIP-Gy32OQztxT1iimiWBBHGcbxecG0A", "index": 1 }, { "pubKey": "29b20d5a0e9523a78525698b3d2506e3091630f0a32f0ee86cc95cff7d4aec4258f207e25d3e0286a5c38234a73154f26be8056e5e757e8582dc47da8199e857", "address": "AYRhYtOjRmQ_VXFDZPihkQcZB4Za2fjByg", "index": 2 }, { "pubKey": "2fa3b60b50a587af844c6daefb084c37796b41c85600bdf2f07d7511a00227aeffd0f756e4a734dfbbbd58f31451c1e5d2f20b135341b66662ccf47bacb880ce", "address": "Admlc1WtfTi2ygjoS-_zNHiWSrTUcE3EoA", "index": 3 }, { "pubKey": "3a0d1e5f9aec94c91acb9432f2fa993bea017b38ca95da6d3a975b99f1aead4e300adc8622d9ea3fe262653915b944d3190e8790d722568286e08908351f4733", "address": "AVXND9zP2cX2RABbMiTj0ON5jmKBTHYvCw", "index": 4 } ], "msg": "success" } <<< error { "code": 5000, "msg": "系統異常" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | pubKey | string | 地址公鑰 | | address | string | 地址 | | index | integer | 地址索引 | ### 3. 獲取 1 個未使用的地址 接口名稱：/api/v2/get_unused_key 請求方法：POST 響應類型：JSON 狀態：有效 接口描述：申請一個未使用的地址公鑰對 ~~~[api:keeper] post:/api/v2/get_unused_key <<< success { "code": 0, "data": { "pubKey": "f7fd57df8a840a26af0cd5671af737d78bfd183a286ea926015a06933a31646b1b6e81976882a245d34a907d0e898580fda242c27cdc16123d8adedb83b400d8", "address": "AdkELJpYcCk4U5QCAit1t54OtasEBH8wtw", "index": 14 } } <<< error { "code": 5000, "msg": "系統異常" } ~~~ ** 返回第一個未使用的地址公鑰對, "pubKey"為公鑰, "address"為對應地址, "index"為索引, 該地址返回后, keeper內部將標示其為已使用. 如果沒有可用的地址, "data"為 {} ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | pubKey | string | 地址公鑰 | | address | string | 地址 | | index | integer | 地址索引 | ### 4. 獲取未使用的地址數量 接口名稱： /api/v2/get_unused_key_count 請求方法：GET 響應類型：JSON 狀態：有效 接口描述：返回keeper內部未使用的地址公鑰對數量 ~~~[api:keeper] get:/api/v2/get_unused_key_count <<< success { "code": 0, "data": { "count": 11 } } <<< error { "code": 5000, "msg": "系統異常" } ~~~ ** 返回未使用的地址公鑰對數量** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | count | int | 未使用地址數量 | ### 5. 事務簽名（指定公鑰） 接口名稱：/api/v2/sign_by_key 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：指定由公鑰對應的私鑰對未簽名事務 hash 進行簽名，返回簽名 ~~~[api:keeper] post:/api/v2/sign_by_key string:hash#待簽名事務hash（32字節，編碼后為64字符） string:pub_key#服務端使用參數所指定公鑰對應的私鑰進行簽名 <<< success { code: 0, data: { "signed_hash" : "f62a74dd5c55e2dc4af650654348b6884bf6b08a2fbb59f424c1ddcfa3974fb49c281fb2aafa7394f0bc20e84866a1094bd9d9ea7ab11a7d91b610855e312764,de67efffc14cc1b2f0bc3bec5f993471f1fa9c411b90249b60511ed960041abb445d49711168315d01ef20a842675f9c89f9a14839d1f093fa934ac9f008f85a" } } <<< error { code: 4100, msg: '簽名服務已關閉' } ~~~ ** 返回數據里"signed_hash"即為簽名成功后的數據, 如果公鑰不合法,或者簽名服務已關閉,則將返回錯誤信息 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | signed_hash | string | 簽名數據 | ### 6. 事務簽名（指定地址） 接口名稱：/api/v2/sign_by_addr 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：指定由參數所指定地址對應的私鑰對未簽名事務 hash 進行簽名，返回簽名 ~~~[api:keeper] post:/api/v2/sign_by_addr string:hash#待簽名事務 hash（32 字節，編碼后為 64 字符） string:address#服務端使用該地址對應的私鑰進行簽名 <<< success { code: 0, data: { "signed_hash" : "f62a74dd5c55e2dc4af650654348b6884bf6b08a2fbb59f424c1ddcfa3974fb49c281fb2aafa7394f0bc20e84866a1094bd9d9ea7ab11a7d91b610855e312764,de67efffc14cc1b2f0bc3bec5f993471f1fa9c411b90249b60511ed960041abb445d49711168315d01ef20a842675f9c89f9a14839d1f093fa934ac9f008f85a" } } <<< error { code: 4200, msg: '系統異常' } ~~~ ** 接口返回數據里"signed_hash"即為簽名成功后的數據, 如果地址不合法,或者簽名服務已關閉,則將返回錯誤信息 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | signed_hash | string | 簽名數據 | ### 7. 設置系統參數 接口名稱：/api/v2/set_params 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：設置系統的運行時參數，用于限制是否可以簽名，黑白地址名單等，這里設置的黑白名單將清除服務端原有的黑白名單設置。 ~~~[api:keeper] post:/api/v2/set_params number:sign_count#簽名數,目前 <= 0 關閉簽名服務 > 0 開啟簽名服務 string:blacklist#白名單數組(數組字符串需要經過編碼處理:[],等數組里的特俗字符) string:whitelist#黑名單數組(數組字符串需要經過編碼處理:[],等數組里的特俗字符) <<< success { code: 0, msg: 'success' } <<< error { code: 4500, msg: '系統異常' } ~~~ 參數示例： ``` { sign_count: 1, blacklist: [{"pub_key": "89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7", "address": "AZvnLUhQSmyE0t-sWTacMdu4ldnsE66mrA"}], whitelist: [{"pub_key": "23e484676e5c783afa8fd4a8fa8783f965d7954649419ed6659e6f6a1796646e97235464d96a137c016f9f2442f8443057fad5208765a0faff8140b1e4f385ac", "address": "ASYJcGipUeKzHxxnILy7T9v8nFZlRAK_gw"}] } ``` ### 8. 黑名單操作 接口名稱：/api/v2/operate_black_list 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：對黑名單進行操作 ~~~[api:keeper] post:/api/v2/operate_black_list string:action#動作（add、remove、get） string:keypairs#公鑰地址對數組（數組字符串，特殊字符需要經過編碼處理 ） <<< success { code: 0, msg: 'success' } <<< error { code: 4600, msg: '系統異常' } ~~~ 參數示例: - 新增黑名單 ``` { action: 'add', keypairs: [{"pub_key": "89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7", "address": "AZvnLUhQSmyE0t-sWTacMdu4ldnsE66mrA"}] } ``` - 移除黑名單 ``` { action: 'remove', keypairs: [{"pub_key": "89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7", "address": "AZvnLUhQSmyE0t-sWTacMdu4ldnsE66mrA"}] } ``` - 獲取黑名單 ``` { action: 'get' } ``` ### 9. 白名單操作 接口名稱：/api/v2/operate_white_list 請求方法：POST 響應類型：JSON 請求數據類型：application/json 狀態：有效 接口描述：對白名單進行操作 ~~~[api:keeper] post:/api/v2/operate_white_list string:action#動作（add、remove、get） string:keypairs#公鑰地址對數組（數組字符串，特殊字符需要經過編碼處理 ） <<< success { code: 0, msg: 'success' } <<< error { code: 4700, msg: '系統異常' } ~~~ 參數示例: - 新增白名單 ``` { action: 'add', keypairs: [{"pub_key": "89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7", "address": "AZvnLUhQSmyE0t-sWTacMdu4ldnsE66mrA"}] } ``` - 移除白名單 ``` { action: 'remove', keypairs: [{"pub_key":"89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7", "address": "AZvnLUhQSmyE0t-sWTacMdu4ldnsE66mrA"}] } ``` - 獲取白名單 ``` { action: 'get' } ``` ### 10. 獲取地址使用狀態 接口名稱：/api/v2/export_keys 請求方法：GET 響應類型：JSON 狀態：有效 接口描述：導出私鑰管理服務系統中的的私鑰被使用的數量以及總數等信息。由外部調用，用于定期備份密鑰狀態 ~~~[api:keeper] get:/api/v2/export_keys <<< success { "code": 0, "data": [ { "used": 10, "total": 32, "pubkey": "89c114d91fad38a04a4b0ecc682e7b87bf5e386869c183cac5052c0d8852b1aae139595e811ce95ab93b6a05d3687206f839f13dce0bc27d6334ac918bcfb5f7" } ] } <<< error { "code": 5000, "msg": "系統異常" } ~~~ ** 接口返回數據里"used"為已使用的私鑰的數量，"total"為總的私鑰數量，"pubkey"為total對應的公鑰的值，如果簽名服務已關閉,則將返回錯誤信息 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | used | integer | 已使用的私鑰的數量 | | total | integer | 總的私鑰數量 | | pubkey | string | total對應公鑰 | ### 11. 恢復密鑰 接口名稱：/api/v2/import_keys 請求方法：POST 響應類型：JSON 請求數據類型：application/json 狀態：有效 接口描述：通過輸入種子和外部備份的密鑰狀態信息，可以恢復導出密鑰狀態時的密鑰狀態情況。當服務異常、升級等情況下可以用來恢復數據 **請求參數** ~~~ { "seed":"38627b052f6ac556cc09e0812f272b37f2f4036b1af919b79f9c93ed6ba17d0938280b72aa3749da30e9cae7a7b79c72f57204a7730283dfc3ba000e33bc3510", "used":1, "total":1, "pubkey":"d82677732d9fdb46265e0f80c2086770e792e5e2a497271e47b623a24bb6bc907ce2dcddc0d0510dd452ef384a30ef733e805a04273be34d449bd55d1874a101" } ~~~ ~~~[api:keeper] post:/api/v2/import_keys string:seed#種子字符串 int:used#使用過的密鑰數 int:total#總共的密鑰數 string:pubkey#total對應的公鑰 <<< success { "code": 0, "data": [ { "pubKey": "f25fad5ae82804d3e990af6a1b5379dabae5fafd5f26a5295f6cbfc2b33e8989b896192bf14be8c0b2bab184242bc569bccfae224b511a65fd1c51c4f85a96d8", "address": "AUUk3GpbpZum_B5YKLGgQT3FhaXNbN0QGA", "index": 0 }, { "pubKey": "483c5cb5d57bbe2b8223548269dd65d7f9c8d2ceb7b8afa8fa7da7a27960475db45be102e5aa396600d12f1864b2bc6e1c7d5601a37acf28f4c0444de02fe61b", "address": "AfdIP-Gy32OQztxT1iimiWBBHGcbxecG0A", "index": 1 }, { "pubKey": "29b20d5a0e9523a78525698b3d2506e3091630f0a32f0ee86cc95cff7d4aec4258f207e25d3e0286a5c38234a73154f26be8056e5e757e8582dc47da8199e857", "address": "AYRhYtOjRmQ_VXFDZPihkQcZB4Za2fjByg", "index": 2 }, { "pubKey": "2fa3b60b50a587af844c6daefb084c37796b41c85600bdf2f07d7511a00227aeffd0f756e4a734dfbbbd58f31451c1e5d2f20b135341b66662ccf47bacb880ce", "address": "Admlc1WtfTi2ygjoS-_zNHiWSrTUcE3EoA", "index": 3 }, { "pubKey": "3a0d1e5f9aec94c91acb9432f2fa993bea017b38ca95da6d3a975b99f1aead4e300adc8622d9ea3fe262653915b944d3190e8790d722568286e08908351f4733", "address": "AVXND9zP2cX2RABbMiTj0ON5jmKBTHYvCw", "index": 4 } ], msg: 'success' } <<< error { code: 5000, msg: '系統異常' } ~~~ ** 接口返回數據里"code"為0表示正常，data為公鑰地址對數組，"pubkey"為公鑰，"address"為公鑰對應的地址，"index"為賬戶索引 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | data | array | 公鑰地址對數組 | | pubkey | string | 公鑰 | | address | string | 地址 | | index | integer | 地址索引 | ### 12. 根據對方公鑰加密 接口名稱：/api/v2/ecies_encrypt_by_address 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：指定由參數所指定地址對應的私鑰對明文加密加密數據，返回加密數據(base64編碼), 此接口可用于提貨信息的加密, 自己和擁有公鑰雙方都可以對加密串解密. **請求參數** ~~~ { "address":"AZSqDujzrpq--uXcD5dJgpDFWzYqmbV4rQ", "to_pubkey": "cabb8a3a73ea4a03d025a6ac2ebbbb19a545e4fb10e791ec9b5c942d77aa20760f64e4604cdfbec665435a382a8c9bfd560c6f0fca8a2708cda302f658368b36", "plain_text":"'{reply:"ok", orderNo: "238812132423"}'", } ~~~ ~~~[api:keeper] post:/api/v2/ecies_encrypt_by_address string:plain_text#待加密數據(utf8編碼) string:to_pubkey#對方的公鑰(hex編碼) string:address#服務端使用該地址對應的私鑰進行加密 <<< success { "code": 0, "data": { "encrypted_base64_str": "UJNCe6+ewXCTNuQC9KOAnQR5GtrgTppdZYkpd8nTcgdZDdsqwnnmcPkl17aap+G/nmFRRK+5xQ8kNh5v2OAnvpymwaRP/TrzvN/8xo+a0HmKBLr9Z2aNfUd989RSidMJ2hQT6nivV8iMXzCyGDbnLcy0iVwAJ0aEPMQvCKynadZWC6YCq8MsncJeM0GSN+o3zkM5BvYQtbA33ZuHMFlCXvzCyRPZCrMin/qCOhz2HdxFYwWslh+eafIQMhyu6YAr4gzC+O+SgE7aDQAZUpI4107b7Tt3gclFw12ztDDeiD1bgA==" } } <<< error { code: 5000, msg: '系統異常' } ~~~ ** 接口返回數據里"encrypted_base64_str"即為加密成功后的數據 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | encrypted_base64_str | string | 加密數據 | ### 13. 根據已加密信息加密 接口名稱：/api/v2/ecies_encrypt_by_address_reply 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：根據已經加密信息包含的上下文信息進行加，返回加密數據(base64編碼), 此接口可用于商品發貨后, 提貨token的打回. **請求參數** ~~~ { "address":"AZSqDujzrpq--uXcD5dJgpDFWzYqmbV4rQ", "old_data":"UJNCe6+ewXCTNuQC9KOAnQR5GtrgTppdZYkpd8nTcgdZDdsqwnnmcPkl17aap+G/nmFRRK+5xQ8kNh5v2OAnvpymwaRP/TrzvN/8xo+a0HmKBLr9Z2aNfUd989RSidMJ2hQT6nivV8iMXzCyGDbnLcy0iVwAJ0aEPMQvCKynadZWC6YCq8MsncJeM0GSN+o3zkM2dZw1NWruOFrCSqcVE5gpsRgp6axPLVt1jaeYRQqLKcXIQK/8VWleldytDV2MkknKxwtUqqD1PW4a6aYW0+yq/F2RXHIcgsjtqO58Wa3ptjJ5sQu90cK+tfNhL8DeVc77lSeD7DXYvnkNg0OrdbdtNb0vmdqTskMWaGWR3k0h2Q==", "plain_text":"'{reply:"ok", orderNo: "238812132423"}'", } ~~~ ~~~[api:keeper] post:/api/v2/ecies_encrypt_by_address_reply string:plain_text#待加密數據(utf8編碼) string:old_data#原加密數據(base64編碼) string:address#服務端使用該地址對應的私鑰進行加密 <<< success { "code": 0, "data": { "encrypted_base64_str": "UJNCe6+ewXCTNuQC9KOAnQR5GtrgTppdZYkpd8nTcgdZDdsqwnnmcPkl17aap+G/nmFRRK+5xQ8kNh5v2OAnvpymwaRP/TrzvN/8xo+a0HmKBLr9Z2aNfUd989RSidMJ2hQT6nivV8iMXzCyGDbnLcy0iVwAJ0aEPMQvCKynadZWC6YCq8MsncJeM0GSN+o3zkM5BvYQtbA33ZuHMFlCXvzCyRPZCrMin/qCOhz2HdxFYwWslh+eafIQMhyu6YAr4gzC+O+SgE7aDQAZUpI4107b7Tt3gclFw12ztDDeiD1bgA==" } } <<< error { code: 5000, msg: '系統異常' } ~~~ ** 接口返回數據里"encrypted_base64_str"即為加密成功后的數據 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | encrypted_base64_str | string | 加密數據 | ### 14. 解密 接口名稱：/api/v2/ecies_decrypt_by_address 請求方法：POST 響應類型：JSON 請求數據類型: application/json 狀態：有效 接口描述：指定由參數所指定地址對應的私鑰對加密數據進行解密，返回解密密數據(utf8編碼) **請求參數** ~~~ { "address":"AZSqDujzrpq--uXcD5dJgpDFWzYqmbV4rQ", "encrypted_str":"UJNCe6+ewXCTNuQC9KOAnQR5GtrgTppdZYkpd8nTcgdZDdsqwnnmcPkl17aap+G/nmFRRK+5xQ8kNh5v2OAnvpymwaRP/TrzvN/8xo+a0HmKBLr9Z2aNfUd989RSidMJ2hQT6nivV8iMXzCyGDbnLcy0iVwAJ0aEPMQvCKynadZWC6YCq8MsncJeM0GSN+o3zkM2dZw1NWruOFrCSqcVE5gpsRgp6axPLVt1jaeYRQqLKcXIQK/8VWleldytDV2MkknKxwtUqqD1PW4a6aYW0+yq/F2RXHIcgsjtqO58Wa3ptjJ5sQu90cK+tfNhL8DeVc77lSeD7DXYvnkNg0OrdbdtNb0vmdqTskMWaGWR3k0h2Q==", } ~~~ ~~~[api:keeper] post:/api/v2/ecies_decrypt_by_address string:encrypted_str#原加密數據(base64編碼) string:address#服務端使用該地址對應的私鑰進行解密 <<< success { "code": 0, "data": { "decrypted_utf8_str": "{foo:\"aaaaaaaaaaaaaaa\",baz:10000, address: \"北京朝陽區望京西路15號樓7單元203\"}" } } <<< error { code: 5000, msg: '系統異常' } ~~~ ** 接口返回數據里"decrypted_utf8_str"即為解密成功后的數據 ** **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | decrypted_utf8_str | string | 解密數據 | ## shuttle接口封裝 **封裝提貨、轉賬、發貨、退貨創建交易事務, keeper簽名, 上鏈的接口調用** ### 1. 轉賬 <span id="api00"></span> 接口名稱：/api/v2/tx/transfer_by_address 請求方法：POST 響應類型：JSON 狀態：有效 接口描述: 構建轉賬事務并上鏈 **請求參數** ~~~ { token_key:VCT1000 from:AcLO3hwkncntl9tTsO1-xUzEeP8SP-hYQw to: AXhfvSAiXjSZaOqBC221BmeLGHbLLtwL5g value:"1" metadata:keeper transfer a token to_pub_key:14c5fe881149bb3c79fe7012670a1106ed7e5d3745dcbea7e6687e25e38408ea0f451096bf99fe13006e7c56ad218e6e7fc20c20d2cc93ed6efeaf2d6090ff4c } ~~~ ~~~[api:keeper] post:/api/v2/tx/transfer_by_address *string:token_key#商品token *string:from#token轉賬發起人 *string:to#token轉賬接收人 *string:value#token轉賬數量 string:metadata#交易meta信息 string:to_pub_key#加密meta所有的公鑰, 該公鑰需要和目標地址對應,否則轉賬接收者不能解密meta數據. 該參數為空,則meta信息不加密 <<< success { "code": 0, "data": { "requestId": "5ce535a78329f30018da6bc6" }, "msg": "create task success, the status of task will be notify" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId | string | 上鏈事務管理id | ### 2. 提貨 <span id="api00"></span> 接口名稱：/api/v2/tx/exchange_by_address 請求方法：POST 響應類型：JSON 狀態：有效 接口描述: 構建提貨事務并上鏈 **請求參數** ~~~ { token_key:VCT1000 from:AcLO3hwkncntl9tTsO1-xUzEeP8SP-hYQw value:"1" metadata:{"out\_pickup\_no":"","consignee":"張三","cellphone":"13912345678","address":\["北京市","四環到五環之間","朝陽區","望京地區","望京SOHO T1 C座1915室"\],"zipcode":"100001"} } ~~~ ~~~[api:keeper] post:/api/v2/tx/exchange_by_address *string:token_key#商品token *string:from#token提貨發起人 *string:value#token提貨數量 *string:metadata#提貨地址信息 <<< success { "code": 0, "data": { "requestId": "5ce535a78329f30018da6bc6" }, "msg": "create task success, the status of task will be notify" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId | string | 上鏈事務管理id | ### 3. 發貨 <span id="api00"></span> 接口名稱：/api/v2/tx/deliver_by_address 請求方法：POST 響應類型：JSON 狀態：有效 接口描述: 構建發貨事務并上鏈 **請求參數** ~~~ { token_key:VCT1000 from:AcLO3hwkncntl9tTsO1-xUzEeP8SP-hYQw to: AXhfvSAiXjSZaOqBC221BmeLGHbLLtwL5g value:"1" metadata:keeper deliver a token to_pub_key:14c5fe881149bb3c79fe7012670a1106ed7e5d3745dcbea7e6687e25e38408ea0f451096bf99fe13006e7c56ad218e6e7fc20c20d2cc93ed6efeaf2d6090ff4c, split: 'false' } ~~~ ~~~[api:keeper] post:/api/v2/tx/deliver_by_address *string:token_key#商品token *string:from#token發貨發起人 *string:to#token發貨接收人 *string:value#token發貨數量 *string:split#是否生成新的token, 取值'true' 或者 'false' string:metadata#交易meta信息 string:to_pub_key#加密meta所有的公鑰, 該公鑰需要和目標地址對應,否則發貨接收者不能解密meta數據. 該參數為空,則meta信息不加密 <<< success { "code": 0, "data": { "requestId": "5ce535a78329f30018da6bc6" }, "msg": "create task success, the status of task will be notify" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId | string | 上鏈事務管理id | ### 4. 申請退貨 <span id="api00"></span> 接口名稱：/api/v2/tx/refunding_by_address 請求方法：POST 響應類型：JSON 狀態：有效 接口描述: 構建客戶申請退貨事務并上鏈 **請求參數** ~~~ { token_key:VCT1000 from:AcLO3hwkncntl9tTsO1-xUzEeP8SP-hYQw to: AXhfvSAiXjSZaOqBC221BmeLGHbLLtwL5g value:"1" metadata:keeper deliver a token to_pub_key:14c5fe881149bb3c79fe7012670a1106ed7e5d3745dcbea7e6687e25e38408ea0f451096bf99fe13006e7c56ad218e6e7fc20c20d2cc93ed6efeaf2d6090ff4c } ~~~ ~~~[api:keeper] post:/api/v2/tx/refunding_by_address *string:token_key#商品token *string:from#token申請退貨發起人 *string:value#token申請退貨數量 string:metadata#交易meta信息 <<< success { "code": 0, "data": { "requestId": "5ce535a78329f30018da6bc6" }, "msg": "create task success, the status of task will be notify" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId | string | 上鏈事務管理id | ### 5. 退貨 <span id="api00"></span> 接口名稱：/api/v2/tx/refund_by_address 請求方法：POST 響應類型：JSON 狀態：有效 接口描述: 構建退貨事務并上鏈 **請求參數** ~~~ { token_key:VCT1000 from:AcLO3hwkncntl9tTsO1-xUzEeP8SP-hYQw to: AXhfvSAiXjSZaOqBC221BmeLGHbLLtwL5g value:1 metadata:keeper deliver a token to_pub_key:14c5fe881149bb3c79fe7012670a1106ed7e5d3745dcbea7e6687e25e38408ea0f451096bf99fe13006e7c56ad218e6e7fc20c20d2cc93ed6efeaf2d6090ff4c } ~~~ ~~~[api:keeper] post:/api/v2/tx/refund_by_address *string:token_key#商品token *string:from#token退貨發起人 *string:to#token退貨接收人 *string:value#token退貨數量 string:metadata#交易meta信息 string:to_pub_key#加密meta所有的公鑰, 該公鑰需要和目標地址對應,否則退貨接收者不能解密meta數據. 該參數為空,則meta信息不加密 <<< success { "code": 0, "data": { "requestId": "5ce535a78329f30018da6bc6" }, "msg": "create task success, the status of task will be notify" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId | string | 上鏈事務管理id | ## 接口錯誤碼匯總 ``` 4000: 接口請求參數錯誤 4100: keeper簽名服務已關閉 4200: keeper簽名地址不合法 4300: keeper簽名公鑰不合法 4400: keeper更新黑名單失敗 4500: keeper更新白名單失敗 4600: keeper使用錯誤種子生成批量生成地址 5000: 接口調用異常 ``` ## 接口使用示例 **獲取密鑰種子 seed** 該部署完成后，該接口只需要調用一次，一旦用該 seed 生成了地址后，除非恢復，后續將不能再修改，請妥善保存seed。 *使用我們提供的測試環境則不需要再調用了* ``` # curl http://127.0.0.1:8003/api/v2/generate_seed # { "code": 0, "data": { "mnemonic": "supply disagree case say pipe unit use raw test faith mistake hole", "seed": "05e8585bb7d5f6a3a7059c17c6213a980a34619edfe46b858553556e2c79041e8a30f8e1abd23ed27b7b60f0c34b1575cab254c67b8e9d9fcbf9439c1516e59a" } } ``` **批量生成密鑰對** ``` # curl -H "Content-Type: application/json" -X POST --data '{"seed":"6f21c9239acc5d127d9159d06bbfc656f6eba20bd3fb658105fba456f9eef4d4907e452bdc79b9f3fd0781a8375707f76270380788151866691604015e891151", "amount" : 1}' http://127.0.0.1:8003/api/v2/generate_keys ``` **返回公鑰地址對, 這里生成的公鑰對都是未分配的** ``` # {"code":0,"data":\[{"pubKey":"06032117d1367819cf010cdba9efd2f57c7f223c6e1fc5489e0e8cc8d547b25756ae03ca816fa9b8269f61f07915fa49b45c3f4577d8f71323f078212d4d4e61","address":"AYZe38fxK7bUivWOrBbGKb0EAraGP1I17A","index":38}\],"msg":"success"} ``` **申請一個未使用的地址** ``` # curl http://127.0.0.1:8003//api/v2/get_unused_key ``` **返回一個地址，系統內部標示其為已使用** ``` # {"code":0,"data":{"pubKey":"799f5e6ed68f90d7131ae7e82fde680cde039e705be88e34ee91b6c22974e1cb6d30ffc4d0c91657e0f530e86582935678c0f8111970a9818019b88c8343833e","address":"AWKgbWiyhRIh09PZ6-OBv46nJDEE6tTyOA","index":0}} ``` **使用公鑰簽名** ``` #curl -H "Content-Type: application/json" -X POST --data '{"hash":"D36BF29D562CF53F92727A8608C054D26F122611D9DF06EC923C6F7868813CC3", "pub_key" : "06032117d1367819cf010cdba9efd2f57c7f223c6e1fc5489e0e8cc8d547b25756ae03ca816fa9b8269f61f07915fa49b45c3f4577d8f71323f078212d4d4e61"}' http://127.0.0.1:8003//api/v2/sign_by_key ``` **簽名后返回數據** ``` # {"code":0,"data":{"signed\_hash":"EC:01,06032117d1367819cf010cdba9efd2f57c7f223c6e1fc5489e0e8cc8d547b25756ae03ca816fa9b8269f61f07915fa49b45c3f4577d8f71323f078212d4d4e61,6dae86c6fe20af788167a53da6a0475542e65ed7362269e8d7ba7a96d235a13b2eeee041ca7d6d641714b99d67af036090b6871a4a165bcad1ca165ee461d0df:"}} ``` ## Docker 容器 Keeper 服務需要部署在應用系統的服務器環境，我們提供 Keeper Docker 容器鏡像。用戶可在自己的服務器環境中啟動一個 Keeper 容器，用戶直接請求容器，Keeper 容器將提供如上的接口功能。 **如何啟動一個 Keeper docker 容器(地址/私鑰保存在docker容器對應外部存儲中)** ``` docker run --name keeper -p 8003:8003 -d -v /opt/data:/var/lib/mysql -e PORT=8003 -e EGG_SERVER_ENV=test -e SHUTTLE_APIKEY=5a72327aafbb45fe9917938e1a9f1c4b -e SHUTTLE_SECKEY=3e2d7169f946458b92febf3140327014 -e SHUTTLE_BASE=https://shuttle.stringon.com -e MATRIX_BASE=https://matrix.stringon.com -e MYSQL_ROOT_PASSWORD=mypassword stringon/keeper:1.0.26 /apps/apj/setup.sh ``` **如何啟動一個 Keeper docker 容器(地址/私鑰不保存在docker容器)** ``` docker run --name keeper -p 8003:8003 -d -e PORT=8003 -e EGG_SERVER_ENV=test -e SHUTTLE_APIKEY=5a72327aafbb45fe9917938e1a9f1c4b -e SHUTTLE_SECKEY=3e2d7169f946458b92febf3140327014 -e SHUTTLE_BASE=https://shuttle.stringon.com -e MATRIX_BASE=https://matrix.stringon.com -e MYSQL_ROOT_PASSWORD=mypassword stringon/keeper:2.0.7 /apps/apj/setup.sh ``` - env：環境，test-測試環境，prod-生產環境 - /opt/data：數據保存目錄（該目錄自行指定） - SHUTTLE_BASE: shuttle訪問url - SHUTTLE_APIKEY, SHUTTLE_SECKEY對應在matrix上申請 - MATRIX_BASE: matrix訪問url