Shuttle 節點服務 · Weaver系統API文檔

**節點服務 Shuttle** 是訪問區塊鏈的中間服務，主要提供交易構造、簽名、數據上鏈、交易信息訂閱、發行 Token 等服務。 Shuttle 系統提供部署于業務系統內部環境的 Shuttle Proxy Docker 鏡像，通過內部訪問 Shuttle Proxy 實現相關功能，具體接口如下： [TOC] ## 說明 ### 演示環境接口地址：https://shuttledemo.stringon.com/…… apiKey 和 secKey：使用 [Matrix](https://matrixdemo.stringon.com) 系統注冊用戶的 API_Key 和 API_Secret ### 資產標識系統使用 coin 和 tokenKey 來標識一種資產，其中 coin 標識區塊鏈名稱或鏈的原生幣，tokenKey 標識一條鏈上的 Token： - coin：大寫的幣種簡稱，原生幣等于鏈簡稱，當前支持的類型為： | 取值 | 說明 | |----|----| |ASTRO_TOKEN|基于 ASTRO 發行的 Token| - chain：鏈的標識簡稱，當前支持的類型為： | 取值 | 說明 | |----|----| |chain|ASTRO| ### 參數中的簽名字段所有用戶接口都使需要帶有對其他請求參數內容的簽名，如其他參數內容如下： ``` data: { cb_url: 'http://localhost/api/cb' api_key: '12345678', } str="api_key=12345678&cb_url=http://localhost/api/cb" + sec_key signature=md5(str) ``` 其中，sec_key 是用戶密鑰，對所有參數進行字母排序以&連接，后對 str 執行 md5 得到 signature <span style="color: red">****注意！！如果在當前頁面調試接口，所有接口的api_key 和 signature 不需要填寫;使用https://shuttledemo.stringon.com/，所有接口的api_key 和 signature為必填字段**** </span> ### 請求應答 Body 數據格式 ~~~ ?{ ? ? code: 狀態碼 | 0: 成功 40**: 錯誤碼 ? ? msg: 描述 ? ? data: 數據ai ?} ~~~ ## 通用接口 ### 設置回調 URL ~~~[api:shuttleV2] put:/api/v2/set_callback_url *cb_url#回調url api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "data": { "apiKey": "matrix", "cbUrl": "http://web", "msg": "Welcome" } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | apiKey | string | 用戶的api_key | | cbUrl| string | 回調的url| | msg| string | Welcome | ### 添加訂閱地址 ~~~[api:shuttleV2] post:/api/v2/subscribe *chain# 鏈 *addresses#訂閱地址列表，逗號分割 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "data": { "addresses": [ "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81C" ], "addressesTotalCount": 1 } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | addresses | array | 用戶提交的訂閱地址列表| | addressesTotalCount | | 用戶全部的訂閱地址數 | ### 獲取交易記錄 ~~~[api:shuttleV2] get:/api/v2/history *coin# 幣種 token_key# Token標識鍵（多個以“,” 分割） token_origin# Token標識鍵 (跟token_key 可二選一，有該參數，token_key無效) *address#地址 inout# 取值：【in，out】；in:address 是轉入方，out 是轉出方 txid# txid tx_type#事務類型（多個以“,” 分割） sort# 排序方式，取值【time，height】time:時間排序，height:塊高排序，默認塊高 page_index# 頁碼 | 默認值：1 page_size# 條數 | 默認值：100 timeStart# 起始時間 timeEnd#結束時間 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "msg": "success", "data": { "items": [ { "chain": "ASTRO", "coin": "ASTRO_TOKEN", "tokenKey": "a100", "tokenOrigin": "a100", "_id": "5cd3fc8507eb8c089d1dfd1b", "from": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q", "to": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "txid": "0C697F48392907A0159CF6D2C8928DC8", "__v": 0, "blockHeight": 8, "blockTime": 1559731210835, "meta": "this is a exchange 10 ", "tokenChild": "a100_ex_cfa1caec-5810-4532-8d98-4b8ec7098924", "txType": "astro.token.exchange", "updatedAt": 1557396613343, "valid": true, "value": "10", "createdAt": 1557461369189 }, ], "count": 1, "total": 1 } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 對象內部參數 | 參數類型 | 描述 | | --- | --- | --- |--- | | count | | int | 此次查詢的條數 | | total | | int | 總條數 | | items| | int | 總條數 | | |from| string | 轉出方| | |to| string | 轉入方 | | |tokenOrigin| string| token的源token | | |tokenKey | string| tokenId| | |tokenChild| string | token裂變的子token | | |txType | string| 該事務的類型（見 txType說明）| ### 獲取交易的詳情 ~~~[api:shuttleV2] get:/api/v2/get_create_transfer_status request_id#創建未簽名或者提交簽名返回的requestId create_id#創建未簽名用戶自己傳入的id ；跟requestId 兩者必須有一個 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "data": { "_id": "5cd4ef123653212bcc7c896b", "chain": "ASTRO", "coin": "ASTRO_TOKEN", "_account": "5cac6aa922f8273b6a76171f", "requestBody": { "from": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q", "to": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "value": "1", "token_key": "a100", "metadata": "exchange", "apiKey": "set your apiKey", "signature": "5e39fd3f471fc98ce2595f55f10a7653", "chain": "ASTRO", "tokenKey": "a100", "coin": "ASTRO_TOKEN" }, "__v": 0, "txData": { "raw": "I::batch:ChMKB0FCQ0hBSU4SCEFzdHJvX3YxEgYIpPrT5gUaFBR+/f/cQGvmqgnbZ4FrYRnm1KSq:CnoKEEFTVFJPLlRPS0VOLkJVUk4SZgoEYTEwMBIIZXhjaGFuZ2UaFEFTVFJPLlRPS0VOLkVYQ0hBTkdFIglAQXN0cm9fdjEqFgoU+YATUr5PxX7Lg5uyG7BXZ9o0w51qGwoWChT5gBNSvk/FfsuDm7IbsFdn2jTDnRIBAQqaAQoQQVNUUk8uVE9LRU4uSU5JVBKFAQosYTEwMF9leF8zM2ZiZGI3Mi04ZmMxLTQ4MGMtYmYwMC0yMmMzM2MzZDNiMjkSCGV4Y2hhbmdlKhYKFPmAE1K+T8V+y4ObshuwV2faNMOdUjMKAQESFPmAE1K+T8V+y4ObshuwV2faNMOdGhQSbaukOOqE58Q8L1ajIA7WXjcbOyABKAEKgwEKEkFTVFJPLlRPS0VOLkFTU0lHThJtCixhMTAwX2V4XzMzZmJkYjcyLThmYzEtNDgwYy1iZjAwLTIyYzMzYzNkM2IyORIIZXhjaGFuZ2UqFgoU+YATUr5PxX7Lg5uyG7BXZ9o0w51CGwoBARIWChQSbaukOOqE58Q8L1ajIA7WXjcbOw==", "hash": "23C014865044949429443E7C0A3D41E8FA066D9128393485083B95B2180343A0", "promise": { "txID": "pending", "txNonce": "FH79/9xAa+aqCdtngWthGebUpKo=", "outputs": [ { "FundNonce": "nEhJqrtBxOgQGL6VMHjse90GbUNKwmVEZkmeel9fpos=", "Nonce": "FH79/9xAa+aqCdtngWthGebUpKo=" }, { "FundNonce": "zN1V_wAQ6DjHH-2en0SvQagRpsnZTmhFa1KpFDMz7fE=", "Nonce": "FH79/9xAa+aqCdtngWthGebUpKo=" } ] } }, "txRaw": "EC:01,ED83704C95D829046F1AC27806211132102C34E9AC7FFA1B71110658E5B9D1BDEDC416F5CEFC1DB0625CD0C75DE8192D2B592D7E3B00BCFB4A0E860D880FD1FC,C1A93B42989F5279127E650AE1C82E2745E49A999FB83FB27448E234B52B1B15F6AD76C0E7FBFC9F9F3CE775E0DA17305D26BD976A9102BB3F7AFD2084F9AE96:", "kafkaMsg": { "topic": "ASTRO_TRANSACTION", "messages": "{\"txRaw\":\"EC:01,ED83704C95D829046F1AC27806211132102C34E9AC7FFA1B71110658E5B9D1BDEDC416F5CEFC1DB0625CD0C75DE8192D2B592D7E3B00BCFB4A0E860D880FD1FC,C1A93B42989F5279127E650AE1C82E2745E49A999FB83FB27448E234B52B1B15F6AD76C0E7FBFC9F9F3CE775E0DA17305D26BD976A9102BB3F7AFD2084F9AE96:\",\"requestId\":\"5cd4ef123653212bcc7c896b\"}", "key": "SUBMIT_TRANSFER", "attributes": 1, "timestamp": 1557459734029, "partition": 0 }, "kafkaMsgResult": { "ASTRO_TRANSACTION": { "0": 29 } }, "txid": "0C697F48392907A0159D35606036AF1C", "chainBody": { "createdAt": 1559534844165, "value": "2", "updatedAt": 1559534844157, "txType": "astro.token.transfer", "requestId": "5cf49ced08262700190dba16", "meta": null, "blockTime": 1559534843593, "blockHeight": 476, "__v": 0, "txid": "0C697F48392907A0159D35606036AF1C", "to": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q", "from": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "_id": "5cf49ced8c0fc5ae92f76207", "tokenOrigin": "aaaa0", "tokenKey": "aaaa0", "coin": "ASTRO_TOKEN", "chain": "ASTRO" }, "updatedAt": 1557459734245, "createdAt": 1557458706334, "logs": [ "update txData at: 1557458708185", "sendTransaction at: 1557459734026", "sendKafkaMsg at: 1557459734114", "TX_HASH at: 1557459734245" ], "code": 16, "status": "TXID" } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestBody | object |用戶構建該事務請求參數 | | txData | object | 用戶構造未簽名事務返回的txData | | txid| string| 該事務返回的txid | | chainBody | object | 鏈上返回的事務的數據 | | code| int| 該事務現在所處的狀態 | | status| string| 該事務現在所處的狀態的文字描述 | **code值的含義** | 數值 | 含義 | | --- | --- | | -2| 用戶取消了該事務 | | -1| 該事務構建失敗 | | 0| 構建事務請求 | | 2| 構建事務成功返回 | | 4| 對于該事務提交簽名請求 | | 8| 簽名的事務發送到shuttle消息隊列中 | | 16| 該事務返回txid | | 32| 該事務已經上鏈 | | 64| 該事務已經被確認 | ## Astro Token 專有接口 ### 構造提貨事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_exchange_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 轉賬發送者 *to#收款地址 *value#轉賬金額 metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "msg": "成功", "data": { "txData": { "raw": "I::batch:ChMKB0FCQ0hBSU4SCEFzdHJvX3YxEgYIpPrT5gUaFBR+/f/cQGvmqgnbZ4FrYRnm1KSq:CnoKEEFTVFJPLlRPS0VOLkJVUk4SZgoEYTEwMBIIZXhjaGFuZ2UaFEFTVFJPLlRPS0VOLkVYQ0hBTkdFIglAQXN0cm9fdjEqFgoU+YATUr5PxX7Lg5uyG7BXZ9o0w51qGwoWChT5gBNSvk/FfsuDm7IbsFdn2jTDnRIBAQqaAQoQQVNUUk8uVE9LRU4uSU5JVBKFAQosYTEwMF9leF8zM2ZiZGI3Mi04ZmMxLTQ4MGMtYmYwMC0yMmMzM2MzZDNiMjkSCGV4Y2hhbmdlKhYKFPmAE1K+T8V+y4ObshuwV2faNMOdUjMKAQESFPmAE1K+T8V+y4ObshuwV2faNMOdGhQSbaukOOqE58Q8L1ajIA7WXjcbOyABKAEKgwEKEkFTVFJPLlRPS0VOLkFTU0lHThJtCixhMTAwX2V4XzMzZmJkYjcyLThmYzEtNDgwYy1iZjAwLTIyYzMzYzNkM2IyORIIZXhjaGFuZ2UqFgoU+YATUr5PxX7Lg5uyG7BXZ9o0w51CGwoBARIWChQSbaukOOqE58Q8L1ajIA7WXjcbOw==", "hash": "23C014865044949429443E7C0A3D41E8FA066D9128393485083B95B2180343A0", "promise": { "txID": "pending", "txNonce": "FH79/9xAa+aqCdtngWthGebUpKo=", "outputs": [ { "FundNonce": "nEhJqrtBxOgQGL6VMHjse90GbUNKwmVEZkmeel9fpos=", "Nonce": "FH79/9xAa+aqCdtngWthGebUpKo=" }, { "FundNonce": "zN1V_wAQ6DjHH-2en0SvQagRpsnZTmhFa1KpFDMz7fE=", "Nonce": "FH79/9xAa+aqCdtngWthGebUpKo=" } ] } }, "requestId": "5cd4ef123653212bcc7c896b", } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 內部對象名 |參數類型 | 描述 | | --- | --- | --- |--- | | txData | | object |構造的未簽名事務| | | hash | string|用戶需要對此hash值進行簽名| | | 其余 | string|展示用| | requestId| | string |構造未簽名事務返回的id，提交簽名事務或查詢詳細信息需要此id| ### 構造發貨事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_deliver_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 發送者 *to#接受者地址 *value#發貨數量 *split# 是否分割：true|false（true會產生新token） metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { txData: {}, // 事務數據 requestId:, // 提交id } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 構造換貨事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_change_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 發送者 *to#接受者地址 *value#換貨數量 metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { txData: {}, // 事務數據 requestId:, // 提交id } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 構造申請退貨事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_refunding_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 發送者 *to#接受者地址 *value#換貨數量 metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { txData: {}, // 事務數據 requestId:, // 提交id } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 構造處理退貨事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_refund_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 發送者 *to#接受者地址 *value#換貨數量 metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { txData: {}, // 事務數據 requestId:, // 提交id } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 構造轉賬事務 ~~~[api:shuttleV2] post:/api/v2/astro/create_transfer_tx_data create_id#用戶自己傳入的id ，不要重復 *token_key# TokenId *from# 發送者 *to#接受者地址 *value#發貨數量 weak# true/fasle 默認fasle 轉賬余額檢查弱還是強【強用余額的useable、弱用useable+inlocked】 metadata#該事務的需要添加的替他屬性 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { txData: {}, // 事務數據 requestId:, // 提交id } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 構造多地址授權 ~~~[api:shuttleV2] post:/api/v2/astro/create_multi_auth *addresses# 地址集，以 ‘,’分割 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { code: 0, msg: "success", data: { "txid": "d60fbb07e45efd7171b127a1adaed9c7c3ccacdb0586c1502cd428d5418e3252", "mixAddress": "Aftj1zqTIPY72_-Z2XTpxz_c3hPPTs3xpg", "requestId": "5d3a765ab84a02001898da67" } } <<< error { "code": 4000, "msg": "error: ${errorId}" } ~~~ **返回值** 同構造提貨事務 ### 提交已簽名事務 ~~~[api:shuttleV2] post:/api/v2/astro/submit_tx *signed_tx_raw#簽名后事務數據 *request_id#創建未簽名事務返回的requestId *sync# true/false 是否同步請求，默認false api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success sync :false { "code": 0, "data": { "requestId": "5cd4ef123653212bcc7c896b" "sync": fasle, }, "msg": "create task success, the status of task will be notify" } sync:true { "code": 0, "data": { "requestId": "5d652f852449c29d4499d90f", "txid": "3ea2d3f7bfa10b8fcf6cb5b3f6b32bc3db6feb2e09f75e9392e31e46c73af84d", "sync": true, "balance": { "from": [ { "address": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "tokeyKey": "aaaa0", "total": "840", "useable": "838", "inLocked": "0", "outLocked": "2" } ], "to": [ { "address": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q", "tokeyKey": "aaaa0", "total": "52", "useable": "50", "inLocked": "2", "outLocked": "0" } ] } } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | requestId |string | 用戶傳入的request_id | | txid|string | 上鏈后得txid | | balance|object| 參見 get_balance 接口描述，balance的total為 -1 表示余額請求失敗，可用get_balance接口重新查詢 | ### 獲取余額 ~~~[api:shuttleV2] get:/api/v2/astro/get_balance *address#地址 *token_key#tokenId api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "msg": "成功", "data": { "_id": "5ce7bc3c2a9efee3abd6052e", "chain": "ASTRO", "coin": "ASTRO_TOKEN", "tokenKey": "a100", "address": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "total": "1199", "useable": "1196", "inConfirming": "0", "outConfirming": "0", "outLocked": "3", "inConfirmingLocks": [], "outLocks": [ { "value": "1", "tfcId": "5ce7bc3cf1c29b6288415045" }, { "value": "2", "tfcId": "5ce7bc41f1c29b6288415046" } ], "outConfirmingLocks": [] } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | chain | string|ASTRO| | coin | string| string|ASTRO_TOKEN| | tokenKey | string|參數 token_key| | address | string|參數 address | | total | string|總余額| | useable | string|可用余額（總余額減 outLocked）| | inConfirming| object |轉入該地址待確認的| | outConfirming| object |該地址轉出待確認的| | outLocked| string |outLocks所有value的和| | outLocks| object |構造此次未簽名事務后未提交簽名事務的鎖定，包含每一個構建的id，跟數值| | inConfirmingLocks| object |轉入該地址待確認的| | outConfirmingLocks| object |該地址轉出待確認的| ### 獲取地址下的token ~~~[api:shuttleV2] get:/api/astro/get_address_token_detail *address#地址 api_key# 用戶的apiKey signature#secKey簽名后的數據 <<< success { "code": 0, "msg": "成功", "data": { "txCount": 16, "token": [ { "tokenKey": "aaaa0", "status": "-" }, { "tokenKey": "aaaa0_ex_ed7fc8ff-017d-4119-94c8-b49e1e58d4cb", "status": "astro.token.exchange" }, { "tokenKey": "aaaa0_ex_f4830e0e-e5db-4435-8f7f-9cde669c06e3", "status": "-" }, { "tokenKey": "cccc", "status": "-" }, ], "_id": "5cdd366b68c0efe45d69477e", "address": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A", "createdAt": 1558001259252, "updatedAt": 1558489637928, "__v": 0 } } <<< error { "code": 40000, "msg": "error: ${errorId}" } ~~~ **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | txCount| string|該地址的交易數量| | tokenKey| string|用戶請求的token_key| | balance| string|該地址下的token的余額| | status | string|狀態：‘-’，流轉中| ## 通知 ### 通知消息請求結構 ``` { method: 'POST' url: ${cbUrl}, // 用戶設置的回調url data: { taskId: key: msg: signture: } } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | taskId | string | 消息id，用戶可根據此id過濾重發消息，默認消息再沒有正常發送情況下會再重發兩次 | | key | string | 消息類型 | | msg| object | json序列化后的數據消息，用戶需要使用類似 JSON.parse() 的方法反序列化成對象 | | signture| string | 使用用戶sec_key對消息簽名，用戶需驗證消息簽名正確，驗簽時msg為json字符串 | ### 用戶收到通知后需要回復以下格式數據： ``` { code: 0 } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | * | | | | * | | | ### 轉賬相關通知 #### 主動轉賬提交上鏈 ``` key: "TRANSFER_ACTION", msg { status: "SUBMIT_TRANSACTION_TO_CHAIN", txid: 事務ID， tfcId：平臺存入數據庫的id requestId: 轉賬ID, // 提交簽名時需要提交此ID } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | txid | string | 事務 txid | | tfcId| string | 平臺存入該事務到數據庫的id | | requestId| string | 創建未簽名事務返回的requestId | #### 轉賬提交上鏈錯誤 ``` key: "TRANSFER_ACTION", msg: { status: "SUBMIT_TRANSACTION_ERROR" error: 錯誤消息, requestId: 轉賬ID, } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | error| string | 錯誤消息 | | requestId| string | 創建未簽名事務返回的requestId | #### 轉賬被打包上鏈 ``` key: "TRANSFER_ACTION", msg: { status: 'TRANSFER_FROM_CHAIN', inout: 'OUT' | 'IN', // 轉出或轉入 yourAddr: 用戶訂閱的地址, record: { // 轉賬記錄 id，平臺存入數據庫的id （tfcId） chain, coin, tokenOrigin ， tokenKey, from, to, value, txid, blockNum， txType tokenChild， meta }, balance: { // 地址余額 coin, tokenKey, address, total, inConfirming, outConfirming, outLocked }, } ``` **返回值** | 參數名 | 對象內部參數 | 參數類型 | 描述 | | --- | --- | --- | --- | | status || string | 狀態 | | inout| string | 轉入或者轉出 | | yourAddr| | string | 用戶訂閱的地址 | | record| | object| 轉賬記錄 | | | id| string | 平臺存入數據庫的id （tfcId）| | | chain| string | 鏈| | | coin| string | 幣種| | | from| string | token發行者 | | | to| string | token擁有者 | | | value| string | 數量 | | | tokenKey | string | tokenId | | | tokenOrigin | string | token源| | | tokenChild| string | 該事務產生的子token| | | meta| string | 該事務附加的屬性| | | txType| string |參見txType說明 | | | txid| string | 事務的txid | | | blockNum| string | 塊高 | | balance | | object| 參見余額接口說明 | #### 轉賬事務確認 ``` key: "TRANSFER_ACTION", msg: { status: 'CONFIRM', inout: 'IN' | 'OUT', // 轉入或者轉出 txid: 事務ID, confirmedNum：確認數， blockNum } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | inout| string | 轉入或者轉出 | | txid | string | 事務 txid | | confirmedNum| string | 確認數| | blockNum| string | 塊高 | #### 轉賬完成 ``` key: "TRANSFER_ACTION", msg: { status: 'TRANSFER_FINISH'， inout: 'IN' | 'OUT', // 轉入或者轉出 tfcId confirmedNum: 確認數， balance: { // 地址余額 coin, tokenKey, address, total, inConfirming, outConfirming, outLocked }, } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | inout| string | 轉入或者轉出 | | tfcId| string | 平臺存入該事務到數據庫的id（與提交上鏈通知返回的一致） | | confirmedNum| string | 確認數| | balance| object| 參見余額接口余額返回| ### 發布 Token 相關通知 #### 提交上鏈 ``` key: "TOKEN_ACTION", msg: { status: SUBMIT_TOKEN_TO_CHAIN txid requestId: 提交簽名事務返回的id, } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | txid | string | 事務 txid | | requestId| string | 創建未簽名事務返回的requestId | #### 提交簽名事務錯誤 ``` key: "TOKEN_ACTION", msg: { status: SUBMIT_TRANSACTION_TO_CHAIN_ERROR error: requestId: 轉賬id, } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | error| string | 錯誤消息 | | requestId| string | 創建未簽名事務返回的requestId | #### 提交簽名事務鏈上返回錯誤 ``` key: "TOKEN_ACTION", msg: { status: SUBMIT_TRANSACTION_ON_CHAIN_ERROR error: requestId: 轉賬id, } ``` **返回值** | 參數名 | 參數類型 | 描述 | | --- | --- | --- | | status | string | 狀態 | | error| string | 錯誤消息 | | requestId| string | 創建未簽名事務返回的requestId | #### 上鏈事務確認 ``` key: "TOKEN_ACTION", msg:{ status: 'TOKEN_FINISH', requestId: 提交簽名事務返回的id, record: { id chain, coin, tokenKey, tokenOrigin, meta, name, symbol, txType creator, owner, value txid, blockNum, }, balance: { // 地址余額 coin, tokenKey, address, total, inConfirming, outConfirming, outLocked }, } ``` **返回值** | 參數名 | 對象內部參數 | 參數類型 | 描述 | | --- | --- | --- | --- | | status || string | 狀態 | | requestId| | string | 創建未簽名事務返回的requestId | | record| | object| 創建未簽名事務返回的requestId | | | chain| string | 鏈| | | coin| string | 幣種| | | tokenKey | string | tokenId | | | tokenOrigin | string | token源| | | meta| string | 該事務附加的屬性| | | name| string | token名稱 | | | symbol| string | token簡寫 | | | creator| string | token發行者 | | | owner| string | token擁有者 | | | value| string | 數量 | | | txType| string |參見txType說明 | | | txid| string | 事務的txid | | | blockNum| string | 塊高 | | balance | | object| 參見余額接口說明 | ## txType說明 - txType ：astro 專有 - 'astro.token.offer' // 增發 - 'astro.token.create' // 發行 - 'astro.token.exchange' //提貨 - 'astro.token.deliver' //發貨 - 'astro.token.change' // 換貨 - 'astro.token.refunding' // 申請退貨 - 'astro.token.refund' // 處理退貨 ## 錯誤碼 | 錯誤碼 | 描述 | | --- |--- | |460003|設置回調url錯誤| |460006|設置回調url異常| | 460010 | 創建發布Token 事務異常 | | 460011 | 創建Token 增發事務異常 | | 460012 | 創建Token Transfer 事務異常 | | 460013 | 創建提貨事務異常 | | 460014 | 創建發貨事務異常 | | 460015 | 創建換貨事務異常 | | 460016 | 創建處理退貨事務異常 | | 460017 | 創建申請退貨事務異常 | | 460018 | 提交簽名事務類型錯誤 | | 460019 | 提交簽名事務RequestId錯誤 | | 460020 | 提交簽名事務異常 | | 460021 | 獲取余額異常 | | 460022 | 獲取交易詳情異常 | | 460023 | 獲取Token狀態異常 | | 460067 | 獲取轉賬詳情失敗 | | 460068 | 獲取轉賬詳情異常 | | 460069 | 獲取歷史詳情異常 | | 460070 | 訂閱失敗 | | 460071 | 訂閱異常 | ## token 合約簡單說明 ### 個別字段說明 | 字段 | 描述 | | --- |--- | |tokenKey|某一個具體的token| |tokenOrigin|一個token的源token，子token包含【 \_ex_ 】 | | tokenChild | 一個事務中tokenKey裂變的子token，注意處理退貨事務的tokenChild不是新token | ### astro token 合約接口說明 astro token 合約目前提供：轉賬、申請提貨、發貨、申請退貨、處理退貨等接口下面以用戶：c，商家 b ，token：t 進行舉例，以便于理解各個接口 1. 假如商家 b 發行 token t 1000個 2. 用戶c 向商家 b購買 100個 token t，調用轉賬接口；（from：b、to：c、 value：100 ）;等待鏈上確認結束，此時商家 b 擁有token t :900個，用戶b擁有 token t 100個 3. 用戶c 向商家 b 申請提貨 token t 20 個，調用申請提貨接口（from：c、to：b、value：20）;等待鏈上確認結束，此次交易記錄應該為： ``` "from" : "c", "to" : "b", "txid" : "B80704BB7B4D7C0315A17E03F23FA2FC", "blockHeight" : 3, "chain" : "ASTRO", "coin" : "ASTRO_TOKEN", "meta" : "this is a exchange 20 ", "tokenChild" : "t_ex_t1", "tokenKey" : "t", "tokenOrigin" : "t", "txType" : "astro.token.exchange", "value" : "20" ``` 此時：用戶c 擁有 token t 80個，商家 b 擁有token t\_ex\_t1 20 個； **注** 該交易記錄 token t 裂變為 t_ex_t1 4. 商家 b 向用戶 c 發貨 20 個，調用發貨接口（from：b，to：c tokenKey:t\_ex\_t1）;等待上鏈結束，此時交易記錄應為： ``` "from" : "b", "to" : "c", "txid" : "365A858149C6E2D115A17E03F85F1BA4", "blockHeight" : 4, "chain" : "ASTRO", "coin" : "ASTRO_TOKEN", "meta" : null, "tokenChild" : "t_ex_t1", "tokenKey" : "t_ex_t2", "tokenOrigin" : "t", "txType" : "astro.token.deliver", "value" : "20" ``` 此時：商家擁有token t_ex_t1 0個，用戶擁有token t_ex_t2 20 個 **注** 發貨接口有個split 參數，true 表示token t_ex_t1 會裂變為新token t_ex_t2，false 表示不會裂變新token；此處以 split true 為條件。 [ 如果split 為false ，則用戶 b 將擁有token t_ex_t1 20個（此時不會有t_ex_t2 產生）] 5. 用戶 b 向商家 c 申請換貨 10 個，調用換貨接口（from : b ,to：c，tokenKey : t\_ex\_t2）;等待上鏈結束，此時交易記錄應為： ``` "from" : "b", "to" : "c", "txid" : "57E9D1860D1D68D815A17E03FE2342F4", "blockHeight" : 5, "chain" : "ASTRO", "coin" : "ASTRO_TOKEN", "meta" : "change", "tokenChild" : "t_ex_t3", "tokenKey" : "t_ex_t2", "tokenOrigin" : "t", "txType" : "astro.token.change", "value" : "10" ``` 此時用戶 b 擁有 t\_ex\_t2 10個，商家 c 擁有 t\_ex\_t3 10個 **注** 用戶換貨后，商家應該重新發貨，此時發貨的tokenKey 應該為 t_ex_t3 。 6. 用戶 b 向商家 c 申請退貨 10 個，調用申請退貨接口（from : b ,to：c，tokenKey : t_ex_t2）;等待上鏈結束，此時交易記錄應為： ``` "from" : "b", "to" : "c", "txid" : "8866CB397916001E15A17E04020FA59C", "blockHeight" : 6, "chain" : "ASTRO", "coin" : "ASTRO_TOKEN", "meta" : "退貨ing", "tokenChild" : "t_ex_t4", "tokenKey" : "t_ex_t2", "tokenOrigin" : "t", "txType" : "astro.token.refunding", "value" : "10" ``` 此時用戶 b 擁有 t_ex_t2 0個，商家 c 擁有 t_ex_t4 10個 7. 商家 c 處理退貨，調用處理退貨接口（from : c ,to：b，tokenKey : t_ex_t4）;等待上鏈結束，此時交易記錄應為： ``` "from" : "c", "to" : "b", "txid" : "9408D2AC22C4D29415A17E0408110E90", "blockHeight" : 7, "chain" : "ASTRO", "coin" : "ASTRO_TOKEN", "meta" : "退貨", "tokenChild" : "t", "tokenKey" : "t_ex_t4", "tokenOrigin" : "t", "txType" : "astro.token.refund", "value" : "10" ``` 此時商家 c 所擁有的token t_ex_t4 為0，同時擁有的token t 減少10個，用戶擁有的token t 增加10 個 **注** 這種情況下的tokenChild t 不是新的token