DxChain Testnet v0.3.6 Documentation¶
DxChain Network is the world first decentralized big data and machine learning network powered by computing centric blockchain, aiming to build a stable and heterogeneous solution for distributed data storage and computation.
Currently, DxChain Project team is working on the Testnet version of the data chain, which is able to provide persistent and reliable decentralized storage service based on storage contracts. On January 2019, we released DxChain Testnet v0.3.6 fully running on nodes all over the world. Testnet network has been released along with API and SDK.
The main features of the DxChain data chain includes:
- Fully supports transaction types for storage contracts. All nodes on chain could work as storage client or provider to get involved in data storage service.
- High reliability of data storage system by introducing erasure code algorithm, keeping high data security with comparatively low redundency.
- Effective and efficient challange-proof algorithm for validating data storage, building trustable storage.
- Information security with encryption-sharding mechanism for data encryption, protecting user’s privacy.
Basic Concepts¶
Wallets and Addresses¶
To ensure the anonymity and confidentiality of wallets, each wallet is encrypted by a primary key (also known as password) and can generate a number of public addresses used for transactions.
A primary key is a combination of 29 passphrases. E.g.
bailed lukewarm ostrich mowing volcano nostril ravine aggravate cage energy public gags
novelty restrict potato wickets fonts jeers vein waveform vessel adrenalin bamboo adrenalin
tuition voted plotting abrasive after
To spend tokens belonging to each address, the primary key is required. Here is an example of public addresses generated by one primary key.
69wB5DkkkAkUY9xBCSHKVus4yv4LcHJEXwoGRH1kyBurpH3eLjaX
WzSeExR3Yxnacwqp5Zv1QDtWTJuLpssPjQxbLnSathRuMZnbk48X
6YhEi2Pj8fat1uUKjRmJHWVCmCiodjpc5bK1xi4Xqg8dfENGguck
ReKyWEmpxnwRYqiX4hcQLQrPr2fH6yue5uVuQv4GKMvUhusnYV3i
M43GuLCRCfBrW7EeNVrETAatpzFjHaJ8BQdCBYLiqMDNWioCqS5M
LdRwkDikUhgQtZiWXjztEnFNDZv3xSvqqy4NmS5sMRgqsMarkcfm
To enhance the anonymity of wallet, it is always recommended to create a new address when making transactions.
Storage Contract¶
In the storage market, nodes can play two roles:
- client: Using the storage service to upload/download files with dxcoin.
- provider: Giving disk space and bandwidth to provide storage service to earn dxcoin.
Storage contract ensures the persistence and irreversibility of the agreement between storage provider and client. Meanwhile, contract also provides a payment method for storage entities.
Storage contract follows the routine below:
- A provider broadcasts himself as a provider, which will post a specific transaction to the blockchain announcing that he is accepting contracts.
- Once clients got the message from step 1, they will communicate with the provider to get the settings of storage service, e.g. contract price, storage price, upload price, download price, etc.
- After that, the client can manage to form storage contracts. The client’s node will automatically select a certain number of top rated candidates from all available providers, and try to form storage contract with each of them. Each contract keeps storage records which include the merkle root of data, data size, the expiration block height, and etc. Moreover, it also holds funds from client and collaterals from providers.
- Once the client has successfully formed contract with each provider, he can upload/download files to/from blockchain. Each upload/download operation will consume corresponding contract funds based on provider’s settings. The spendings will be stored into the storage contract.
- The client’s node will automatically submit the revised storage contract, also known as storage contract revision, to the blockchain. To ensure the nonrepudiation of the storage contract, and to avoid storing excessive data on chain, only the result of the last valid revision in the contract will be submitted.
- Before the contract ends, the client’s node will automatically form a new contract with settings from last revised contract, which extends the storage duration.
- After the contract ended, the provider’s node will submit the storage proof to the blockchain. Thus, the provider can have the collaterals back along with his profits from this contract, and the client can take back his unspent funds. At this point, the contract comes to an end.
Here are some attributes for a storage contract:
| Field | Description |
|---|---|
| storage merkleroot | Merkle root of the stored data in this contract, used for storage validation |
| storagesize | The total size of the stored data |
| start height | The block height where the contract begins |
| end height | The block height where the contract expires |
| verified proof outputs | The storage contract outputs if the provider submits a valid storage proof |
| failed proof outputs | The storage contract output if the provider fails to submit a valid storage proof |
| revision number | Number of times the contract is revised because of download and upload |
Transactions¶
Storage contract information introduced previously are stored into blockchain as transactions. Therefore, other than token transfering, additional three types of transactions are supported:
| Transaction Type | Description |
|---|---|
| storagecontracts | formed contracts in the transaction |
| storagecontractrevisions | submitted contract revisions in the transaction |
| storageproofs | accepted storage proof |
Blocks¶
A block is a data structure that keeps the transaction data, which can be thought of as the individual page of a ledger. In DxChain block, it contains info about block id, block height, id of the parent block, and a list of transactions which can be of three types mentioned above.
Block Content Explanation¶
Block¶
| Field | Datatype | Description |
|---|---|---|
| id | hash | ID of the block, aka. hash of the block header |
| height | int | Current block height |
| parent id | hash | ID of the previous block |
| difficulty | int | Difficulty of the current block |
| nonce | list of int | Answer to the mining puzzle |
| timestamp | int | Unix timestamp of the time block is mined |
| minerpayouts | list of outputs | Mining reward for the miner(s) |
| transactions | list of transactions | Confirmed transactions in this block |
This is an example block with empty transaction:
{
"id": "00000003ae8cecb7287e3cdf1970bc2ef8ac4183e8ca9e2601d35a0de4ec45db",
"height": 29,
"parentid": "000000069bda8dfb2449d6bdfa90872255f5ad2aa5b3f493030b0a8bb1fab928",
"difficulty": "242159757",
"nonce": [172, 38, 0, 0, 0, 0, 0, 0],
"timestamp": 1545275442,
"minerpayouts": [
{
"id": "dd0599b23bc2b2f5e6732a1da613f402252db4e6d0e6208ee7066e8ab2a81902",
"unlockhash": "dfqa76JzYbzhB3HiDTzahGmQyfFkj9RMjb3dWxkhaGMgnbTxNbzu",
"value": "29700000000000000000000000000"
}
],
"transactions": [
{
"arbitrarydata": [
"Tm9uR2R4AAAAAAAAAAAAAF/WqZnb2YXgknLACh8mTy0="
],
"dxcoininputs": [],
"dxcoinoutputs": [],
"id": "b72cc004f0962e5c260f8363e828960dd4eb2d1e1ff659f39e566d2b41df6379",
"minerfees": [],
"storagecontractrevisions": [],
"storagecontracts": [],
"storageproofs": [],
"transactionsignatures": []
}
]
}
Transaction in blocks¶
Transaction has the following fields:
| Field | Datatype | Description |
|---|---|---|
| id | hash | ID of the transaction |
| dxcoininputs | list | Tokens transfer from |
| dxcoinoutputs | list | Tokens transfer to |
| storagecontracts | list | Contracts formed |
| storagecontractrevisions | list | Contract revisions |
| storageproofs | list | Storage proofs of contracts |
| minerfee | int | Fee paying to miner |
| arbitrarydata | str | Based58 encoded message |
| transactionsignatures | list | Signatures required to validate the transaction |
{
"id": "83b9629008137f1f3a0746e09587d01510fc28ab9ce4a309cc790240188bfe3e",
"dxcoininputs": [
{
"parentid": "08f2ad746a3d5ee8bd9221d2bf58f1bbf0c93b51ce145a80973d0287d3b56bdb",
"unlockconditions": {
"timelock": 0,
"publickeys": [
"ed25519:6a9769aacf4b793071075e3616d4f01eac8c365cea79bb0807b883fe232bb652"
],
"signaturesrequired": 1
},
"unlockhash": "Bq37k24STeMuMLc3Hho35yJnRp4282uMPSeAwfvZfkbMnkh8Ne3d"
}
],
"dxcoinoutputs": [
{
"id": "d0f37720885a7c6a2571bf784fe2b4bb021bff6e42b90e17cd3be28895507a61",
"value": "39900000000000000000000",
"unlockhash": "9wQhsTtj5rovP894FRrJQoQ9U2w5D4zJ6Y22BHYSqFWU7LcT7Qjx"
},
{
"id": "0a09b4bdb8988f0b1219cc0f6bee6bb2b61293505b90ae0d9ad8499edd97ad2b",
"value": "29693960100000000000000000000",
"unlockhash": "7eGZmE9CXognhcDvRFx3MtwWMTXBHdhzZmwuxCRA2nvowBCurZpx"
}
],
"storagecontracts": [],
"storagecontractrevisions": [],
"storageproofs": [],
"minerfees": [],
"arbitrarydata": [],
"transactionsignatures": [
{
"parentid": "08f2ad746a3d5ee8bd9221d2bf58f1bbf0c93b51ce145a80973d0287d3b56bdb",
"publickeyindex": 0,
"timelock": 0,
"coveredfields": {
"wholetransaction": true,
"dxcoininputs": [],
"dxcoinoutputs": [],
"filecontracts": [],
"filecontractrevisions": [],
"storageproofs": [],
"dxtokenallocation": [],
"dxtokendistribution": [],
"minerfees": [],
"arbitrarydata": [],
"transactionsignatures": []
},
"signature": "WVFBomKeM42CsDZqjIxmm/AxSyPU4sl/y1y2K4dgh/wO2cmlqzuAnK+HPhv21z6ZzavTYZJh5KJtDX8A+4whAA=="
}
]
}
The following describes transactions fields related to storage contract operations.
storage contracts¶
| Field | Datatype | Description |
|---|---|---|
| id | hash | ID of the file contract, a.k.a. the hash of the contract header |
| storagesize | int | Size of stored data in bytes |
| storagemerkleroot | hash | Merkle root for stored data hosted in the contract |
| windowstart | int | Block height where provider can start submitting storage proof |
| windowend | int | Block height before which provider should have submitted storage proof |
| payout | int | Tokens held within the contract in unit Hump, including client's contract fund and provider's collaterals |
| verifiedproofoutputs | list of outputs | The storage contract output if the proivider submits a valid storage proof before the window end |
| failedproofoutputs | list of outputs | The storage contract output if the provider fails to submit a valid storage proof before the window end |
| revision number | int | When a new contract is formed, the revision number is default to 0 |
{
"id": "94c017800039ae0e4df9e684355d000d581ee8ed2d3e81c59a5de08e1e92907b",
"storagesize": 262144,
"storagemerkleroot": "e038daa649211eda8f685af01b6c4a27dc4b0d4d1b99b66213ba494627180e46",
"windowstart": 564
"windowend": 600,
"payout": "14215679969659256825234039",
"unlockhash": "AgBuf5rBkYtZxseCFZZRBqHDUCPuCyoQq8S7tu1UhCQkcEvBDE1F",
"verifiedproofoutputs": [
{
"id": "e8306bfc5ea9bb860abc4780d62388927cb9a6df8389b59c3b656a0e38c3bd70",
"unlockhash": "dmYYzitCZKAwSWydS4TsPhqswnQfHC6f3vNPCU4m7EHX5d4NNJ8w",
"value": "4638559984829629449932429"
},
{
"id": "1e7385b7ef07c81180b2c15f9c92029baf37b863e1326d5f2a4a8b6c5a202415",
"unlockhash": "Qg7BefJxm5FTYBrRq9Z6XVdYme2Gt9t8w8yFErLJ1zToe5tg66Ko",
"value": "9577119984829627375301610"
}
],
"failedproofoutputs": [
{
"id": "91b1cef0ebcdf37248c320eb3229e00242c8aa593fd4a22c108a909594cbb4aa",
"unlockhash": "dmYYzitCZKAwSWydS4TsPhqswnQfHC6f3vNPCU4m7EHX5d4NNJ8w",
"value": "4638559984829629449932429"
},
{
"id": "0b36324e40dd34c57b2a4403d53ff3722877f2db91cc84e93ef9e75984064573",
"unlockhash": "Qg7BefJxm5FTYBrRq9Z6XVdYme2Gt9t8w8yFErLJ1zToe5tg66Ko",
"value": "9577119939318516280210410"
},
{
"id": "5c2e828ce03876c95fdf785c61cffd309da285695610b79973dcdbbbb42bb7b7",
"unlockhash": "dmYYzitCZKAwSWydS4TsPhqswnQfHC6f3vNPCU4m7EHX5d4NNJ8w",
"value": "45511111095091200"
}
],
"revisionnumber": 0,
}
storage contract revision¶
| Field | Datatype | Description |
|---|---|---|
| parentid | hash | ID of the file contract |
| unlockconditions | unlockHash | The unlock condition for unlocking the tokens in storage contract |
| newrevisionnumber | int | Number of revisions |
| newstoragesize | int | New storage size in bytes after revision |
| newstoragemerkleroot | hash | New merkle root for hosted data |
| newwindowstart | int | New block height where provider can start submitting storage proof |
| newwindowend | int | New block height before which provider should have submitted storage proof |
| newvalidproofoutputs | list of outputs | Modified storage contract output if the proivider submits a valid storage proof before the window end |
| newfailedproofoutputs | list of outputs | Modified storage contract output if the provider fails to submit a valid storage proof before the window end |
| newunlockhash | unlockhash | The new unlock condition for unlocking the tokens in storage contract |
{
"parentid": "79ff9aedbcdbe96ff18af1c7cf463353f7cfacd4b6b6eb3793c907e53f3c4f64",
"unlockconditions": {
"timelock": 0,
"publickeys": [
"ed25519:56396c920acc9b34c3128db56f0cb25c0f30f7a324ce32ad13a30a4994e6257e",
"ed25519:064d264fead5793bf073b64bce53f663aad78eb06a16c8911a337c052885beaa"
],
"signaturesrequired": 2
},
"newrevisionnumber": 1,
"newstoragesize": 0,
"newstoragemerkleroot": "0000000000000000000000000000000000000000000000000000000000000000",
"newwindowstart": 364,
"newwindowend": 400,
"newvalidproofoutputs": [
{
"value": "4638559999999999814962829",
"unlockhash": "Jddh3WTQTeL2UXfuN96vUSJus8Lymm5D6GjuWpB3fct3HkhqPUQn"
},
{
"value": "9577119999999997740332010",
"unlockhash": "Qg7BefJxm5FTYBrRq9Z6XVdYme2Gt9t8w8yFErLJ1zToe5tg66Ko"
}
],
"newmissedproofoutputs": [
{
"value": "4638559999999999814962829",
"unlockhash": "Jddh3WTQTeL2UXfuN96vUSJus8Lymm5D6GjuWpB3fct3HkhqPUQn"
},
{
"value": "9577119999999997740332010",
"unlockhash": "Qg7BefJxm5FTYBrRq9Z6XVdYme2Gt9t8w8yFErLJ1zToe5tg66Ko"
},
{
"value": "0",
"unlockhash": "Jddh3WTQTeL2UXfuN96vUSJus8Lymm5D6GjuWpB3fct3HkhqPUQn"
}
],
"newunlockhash": "AgBuf5rBkYtZxseCFZZRBqHDUCPuCyoQq8S7tu1UhCQkcEvBDE1F"
}
Storage Proof¶
Once received storage proof, the storage contract is proved to be executed successfully. Thus the token held in the storage contract is dispersed according to the validproofoutputs. If the storage proof is not received and validated within the proof window, the contract token is dispersed according to failedproofoutputs.
| Field | Datatype | Description |
|---|---|---|
| parentid | hash | ID of the storage contract |
| segment | data | actual data of a certain segment |
| hashset | list of hash | The content of the storage proof |
{
"parentid": "c8ae81e233157a3e600e2003985200a5f38d39a9c13a7fdcec54861d67304029",
"segment": [136,34,94,69,38,97,172,1,197,166,39,189,160,143,167,219,48,126,28,223,97,208,197,189,18,129,133,49,254,131,180,57,79,139,131,58,198,58,239,8,32,90,169,127,103,168,21,122,208,89,207,57,54,80,4,42,153,173,46,116,81,11,185,19],
"hashset": [
"d31a57ceefc39433718420ac775141e46af41b93afe1b854001a6a6a1b32563e",
"007b43dd586318329f86fba5faa30dbdeebd5f0817a2f67ae6de58e1a228274e",
"9d7e49f6e86a7b035dcc9cf01858059af971776d5342bd5a8fc2eb4896775c22",
"c4a6f6713c69beeed073864ad93f7cff5684c9596af53755a7a23d2eda7a6803",
"0dd3f172ca3e711d13dca842bc8de14ca93c8bdfcd2df3f1dbd50b98e0452dcc",
"590bb2fc75a2c0cee879964a6a253b07a91a078daa90eee30c98c7b66b014b80",
"ad205b4d3c062f33a6e03a72612ffbff46b94f1a2e9150f36aa959d4a7b69d5c",
"08036426e458b78c27d35f0945961b521d7131875507c9161c5e6b26706519fd",
"205dc0ef5da53562aaf1b189d49866b794e27a2323eafb22adaa83973856a61f",
"d8810b69333976dfadf7276514a38d2f3afb8b0a64b7adff520ec7a07b6b0db3",
"9c0e99a005199ac4604aa6c5de3087d6dcef9054597b27861481182d7fc2e9f3",
"2e14174969b60046c12d14b92a37237fe00c5ae6357c9c098be7fa71586a3f32"
],
}
API document¶
Overview¶
Along with the release of DxChain Testnet v0.3.6, Go-DxChain API is released as well. Three testing servers are hosted in different regions to handle API requests. To get the best performance, please select the server below based on IP location .
| Node location | IP address | Port number |
|---|---|---|
| US (N. California) | 13.52.66.101 | 1688 |
| EU (London) | 35.178.216.243 | 1688 |
| CN (Hebei) | 39.98.171.89 | 1688 |
Deamon programs are running on servers, making them fully synced with DxChain network. Currently, users are able to query on chain data and upload/download files with API.
http://<IP address>:<port number>/<path>
For example, to get the current network status of the server hosted in Europe, use HTTP GET method with the following url:
$ curl --header "User-Agent: Dx-Agent" --user "":"dxchaingogogo" http://35.178.216.243:1688/network
{"netaddress":"35.178.216.243:1689","peers":[{"inbound":false,"local":false,"netaddress":"52.52.118.251:1689","version":"0.3.6"},{"inbound":true,"local":false,"netaddress":"50.18.182.50:1689","version":"0.3.6"},{"inbound":false,"local":false,"netaddress":"18.191.35.18:1689","version":"0.3.6"},{"inbound":false,"local":false,"netaddress":"54.169.160.94:1689","version":"0.3.6"},{"inbound":false,"local":false,"netaddress":"13.52.66.101:1689","version":"0.3.6"},{"inbound":false,"local":false,"netaddress":"18.235.25.189:1689","version":"0.3.6"}]}
Note: The default size unit used is byte.
Note: The default currency unit used is hump, which is the smallest unit of dxcoin. One DXC is 10^24 humps
Detailed API usage will be discussed below.
/network [GET]¶
Return information about current network status, including what the external address is, and which peers the current machine is connected to.
Sample output:
{
"netaddress": "13.57.1.24:1689",
"peers": [
{
"inbound": false,
"local": false,
"netaddress": "13.52.96.207:1689",
"version": "0.3.6"
},
{
"inbound": false,
"local": false,
"netaddress": "52.8.2.87:1689",
"version": "0.3.6"
}
]
}
/consensus [GET]¶
Return information on current consensus state, including the current height, current block ID, etc.
Sample output:
{
"synced": true,
"height": 4225,
"currentblock": "00000002aa3b9c4a12b3c9a426714cf1abff57e95d773bae46d09f4ef61d76b1",
"target": [
0,
0,
0,
57,
146,
0,
101,
219,
193,
148,
55,
127,
207,
44,
241,
177,
157,
148,
224,
48,
190,
151,
104,
62,
54,
1,
255,
145,
174,
41,
28,
208
],
"difficulty": "74603848"
}
/consensus/blocks?height=blockheight [GET]¶
Return detailed block content with the specified block height.
| API Parameter | Description |
|---|---|
| blockheight | a number represents the height of the block |
Sample output:
{
"id": "00000032b0e34b9d8d09283a8eb862cb06950ffb7be96846dad703674ab41d80",
"height": 5,
"parentid": "0000007340bbf82d80aada1a974f98a45e50b3e22e798c7d8a9b0b5a93670d4e",
"difficulty": "22934380",
"nonce": [
149,
32,
0,
0,
0,
0,
0,
0
],
"timestamp": 1544828160,
"minerpayouts": [
{
"id": "d3cb4ea14793ae05753f3fecf21fed548db35caa3cd1522cab8bff75ea188277",
"value": "29700000000000000000000000000",
"unlockhash": "WMsjbgFtmTF4xCTXJZSjEGNXvofbfvKrfHHdroLt5f1KfUsm3HxB"
}
],
"transactions": [
{
"id": "890980cdf546f3858fdf737c4fbf9e58b7b4e0df3c33656925e10a0ccae605e8",
"dxcoininputs": [],
"dxcoinoutputs": [],
"storagecontracts": [],
"storagecontractrevisions": [],
"storageproofs": [],
"minerfees": [],
"arbitrarydata": [
"Tm9uR2R4AAAAAAAAAAAAAHAFAybtijh3PrpUhY9h7NA="
],
"transactionsignatures": []
}
]
}
/consensus/blocks?id=blockid [GET]¶
Return detailed block content with specified block ID. The return message is the same as the previous one.
| API Parameter | Description |
|---|---|
| blockid | 64-bit hash value represents the id of the block |
/wallet [GET]¶
Return current wallet status, including the balance, wallet status, etc.
Sample output:
{
"encrypted": true,
"height": 4239,
"rescanning": false,
"unlocked": true,
"confirmeddxcoinbalance": "82320612295115146315863328738930",
"unconfirmedoutgoingdxcoins": "0",
"unconfirmedincomingdxcoins": "0",
"dxcoinclaimbalance": "0",
"dxfundbalance": "0",
"dustthreshold": "30000000000000000000"
}
/wallet/address [GET]¶
Generate a new wallet address with the primary key and returned.
Sample output:
{
"address": "X6Hsi1KR2RYv15AA5zE1LcdMTgqvN7GZJgA3Fhzomt7pTVp54x22"
}
/wallet/addresses [GET]¶
Return a list of addresses belonging to the wallet.
Sample output:
{
"Addresses": [
{
"id": "dgxNaR9eeJQAvm38FMAUJcrRLk1d2T9mSdXzSyfsUdy18zTddTfg",
"balance": "0",
"unconfirmedinput": "0",
"unconfirmedoutput": "0"
},
{
"id": "MMKUNwWPPqa1sFCymK8wajS75usCk7yMmeRNiW5eXjN81oToZuPT",
"balance": "0",
"unconfirmedinput": "0",
"unconfirmedoutput": "0"
}
]
}
/miner [GET]¶
Return the current miner status.
Sample output:
{
"blocksmined": 2773,
"cpuhashrate": 421533,
"cpumining": true,
"staleblocksmined": 4
}
/provider [GET]¶
Return detailed provider settings information
Sample output:
{
"externalsettings": {
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 432,
"maxrevisebatchsize": 17825792,
"netaddress": "13.57.1.24:1690",
"remainingstorage": 989855744,
"sectorsize": 262144,
"totalstorage": 989855744,
"unlockhash": "PXLMoGZ8wgo8727DDCXNpE2zmJZxAE9U6TyKDG83stuG6js7SkPL",
"windowsize": 36,
"collateral": "2314814814",
"maxcollateral": "5000000000000000000000000000",
"contractprice": "300000000000000000000000",
"downloadbandwidthprice": "25",
"storageprice": "50",
"uploadbandwidthprice": "1",
"revisionnumber": 2025,
"version": "0.3.6"
},
"financialmetrics": {
"contractcount": 0,
"contractcompensation": "0",
"potentialcontractcompensation": "0",
"lockedstoragecollateral": "0",
"lostrevenue": "0",
"loststoragecollateral": "0",
"potentialstoragerevenue": "0",
"riskedstoragecollateral": "0",
"storagerevenue": "0",
"transactionfeeexpenses": "0",
"downloadbandwidthrevenue": "0",
"potentialdownloadbandwidthrevenue": "0",
"potentialuploadbandwidthrevenue": "0",
"uploadbandwidthrevenue": "0"
},
"internalsettings": {
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 432,
"maxrevisebatchsize": 17825792,
"netaddress": "",
"windowsize": 36,
"collateral": "2314814814",
"collateralbudget": "100000000000000000000000000000",
"maxcollateral": "5000000000000000000000000000",
"mincontractprice": "30",
"mindownloadbandwidthprice": "25",
"minstorageprice": "50",
"minuploadbandwidthprice": "1"
},
"networkmetrics": {
"downloadcalls": 0,
"errorcalls": 0,
"formcontractcalls": 0,
"renewcalls": 0,
"revisecalls": 0,
"settingscalls": 2014,
"unrecognizedcalls": 829
},
"connectabilitystatus": "connectable",
"workingstatus": "working"
}
/client [GET]¶
Return information for client settings.
Sample output:
{
"settings": {
"allowance": {
"funds": "50000000000000000000000000",
"providers": 3,
"period": 1440,
"renewwindow": 720
},
"maxuploadspeed": 0,
"maxdownloadspeed": 0,
"streamcachesize": 2
},
"financialmetrics": {
"contractfees": "722880000000000000000000",
"downloadspending": "743178240000000031428",
"storagespending": "55410687980495437824",
"totalallocated": "4999999999999999814962828",
"uploadspending": "18874368000000000000",
"unspent": "49276302536704019504530748",
"contractspending": "4999999999999999814962828",
"withheldfunds": "4277104271360005351444108",
"releaseblock": 4816,
"previousspending": "2168820582324131504854134"
},
"currentperiod": 4050
}
/client/contracts [GET]¶
Return list of contracts that the client has formed with providers.
Sample output:
{
"activecontracts": [
{
"StorageSpending": "0",
"downloadspending": "0",
"endheight": 1583,
"fees": "361440000000000000000000",
"goodforrenew": true,
"goodforupload": true,
"hostpublickey": "ed25519:19d02c9a579ed6d6c5a385245b0f51ff3b6c7b2e96d340684b0c6bf9a7075b71",
"id": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"lasttransaction": {
"arbitrarydata": [],
"storagecontractrevisions": [
{
"newfilemerkleroot": "0000000000000000000000000000000000000000000000000000000000000000",
"newfilesize": 0,
"newmissedproofoutputs": [
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "10749671111111111111111111"
},
{
"unlockhash": "Ss9aeNSfbcm8VhK5RJF58mq64s27WNenT9xET2cn7B79k17ZszU5",
"value": "21799342222222219961039850"
},
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "0"
}
],
"newrevisionnumber": 1,
"newunlockhash": "7oZmYeCzo1QRvFH9Sy6Mi3xPEBLpmXY4QiqZZHkB9pJqJMd8uX8f",
"newvalidproofoutputs": [
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "10749671111111111111111111"
},
{
"unlockhash": "Ss9aeNSfbcm8VhK5RJF58mq64s27WNenT9xET2cn7B79k17ZszU5",
"value": "21799342222222219961039850"
}
],
"newwindowend": 1619,
"newwindowstart": 1583,
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"unlockconditions": {
"publickeys": [
"ed25519:61805be8af102e5ed1eeb45f3da647238c35b843b82cbf330ec31d592734fcf8",
"ed25519:19d02c9a579ed6d6c5a385245b0f51ff3b6c7b2e96d340684b0c6bf9a7075b71"
],
"signaturesrequired": 2,
"timelock": 0
}
}
],
"storagecontracts": [],
"gdxcoininputs": [],
"gdxcoinoutputs": [],
"gdxfundinputs": [],
"gdxfundoutputs": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [
{
"coveredfields": {
"arbitrarydata": [],
"dxcoininputs": [],
"dxcoinoutputs": [],
"dxtokenallocation": [],
"dxtokendistribution": [],
"filecontractrevisions": [
0
],
"filecontracts": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": false
},
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"publickeyindex": 0,
"signature": "m7W5x3nN0QeFaKFgQeeOeaEr210lUvi3KfcUDp+VndJ4rCWnXmdzaqWPnQNiK0tmYFh4yDEAkGMiNu1rp+yHCQ==",
"timelock": 0
},
{
"coveredfields": {
"arbitrarydata": [],
"dxcoininputs": [],
"dxcoinoutputs": [],
"dxtokenallocation": [],
"dxtokendistribution": [],
"filecontractrevisions": [
0
],
"filecontracts": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": false
},
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"publickeyindex": 1,
"signature": "7KyruFXn0Xv48Ac75AI5Y+SMpEhQ6ZyNDNNnntBCv/H3keyNWs4R7zFYEqRYWuWwrIfF6LvqtRtX7oH5UMr4AA==",
"timelock": 0
}
]
},
"netaddress": "13.52.66.101:1690",
"renterfunds": "10749671111111111111111111",
"size": 0,
"startheight": 143,
"storagespending": "0",
"totalcost": "11111111111111111111111111",
"uploadspending": "0"
}
],
"contracts": [
{
"StorageSpending": "0",
"downloadspending": "0",
"endheight": 1583,
"fees": "361440000000000000000000",
"goodforrenew": true,
"goodforupload": true,
"hostpublickey": "ed25519:19d02c9a579ed6d6c5a385245b0f51ff3b6c7b2e96d340684b0c6bf9a7075b71",
"id": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"lasttransaction": {
"arbitrarydata": [],
"filecontractrevisions": [
{
"newfilemerkleroot": "0000000000000000000000000000000000000000000000000000000000000000",
"newfilesize": 0,
"newmissedproofoutputs": [
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "10749671111111111111111111"
},
{
"unlockhash": "Ss9aeNSfbcm8VhK5RJF58mq64s27WNenT9xET2cn7B79k17ZszU5",
"value": "21799342222222219961039850"
},
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "0"
}
],
"newrevisionnumber": 1,
"newunlockhash": "7oZmYeCzo1QRvFH9Sy6Mi3xPEBLpmXY4QiqZZHkB9pJqJMd8uX8f",
"newvalidproofoutputs": [
{
"unlockhash": "LYtMm6gk3gSTTGd5Q9SKshHmiQ9z56ojfkY9n4cpbFCPDsedYgaQ",
"value": "10749671111111111111111111"
},
{
"unlockhash": "Ss9aeNSfbcm8VhK5RJF58mq64s27WNenT9xET2cn7B79k17ZszU5",
"value": "21799342222222219961039850"
}
],
"newwindowend": 1619,
"newwindowstart": 1583,
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"unlockconditions": {
"publickeys": [
"ed25519:61805be8af102e5ed1eeb45f3da647238c35b843b82cbf330ec31d592734fcf8",
"ed25519:19d02c9a579ed6d6c5a385245b0f51ff3b6c7b2e96d340684b0c6bf9a7075b71"
],
"signaturesrequired": 2,
"timelock": 0
}
}
],
"filecontracts": [],
"gdxcoininputs": [],
"gdxcoinoutputs": [],
"gdxfundinputs": [],
"gdxfundoutputs": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [
{
"coveredfields": {
"arbitrarydata": [],
"dxcoininputs": [],
"dxcoinoutputs": [],
"dxtokenallocation": [],
"dxtokendistribution": [],
"filecontractrevisions": [
0
],
"filecontracts": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": false
},
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"publickeyindex": 0,
"signature": "m7W5x3nN0QeFaKFgQeeOeaEr210lUvi3KfcUDp+VndJ4rCWnXmdzaqWPnQNiK0tmYFh4yDEAkGMiNu1rp+yHCQ==",
"timelock": 0
},
{
"coveredfields": {
"arbitrarydata": [],
"dxcoininputs": [],
"dxcoinoutputs": [],
"dxtokenallocation": [],
"dxtokendistribution": [],
"filecontractrevisions": [
0
],
"filecontracts": [],
"minerfees": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": false
},
"parentid": "0e656096572210ae1c906084827d1c1042ca01eeb5558283bade7dd46d85eea5",
"publickeyindex": 1,
"signature": "7KyruFXn0Xv48Ac75AI5Y+SMpEhQ6ZyNDNNnntBCv/H3keyNWs4R7zFYEqRYWuWwrIfF6LvqtRtX7oH5UMr4AA==",
"timelock": 0
}
]
},
"netaddress": "13.52.66.101:1690",
"renterfunds": "10749671111111111111111111",
"size": 0,
"startheight": 143,
"storagespending": "0",
"totalcost": "11111111111111111111111111",
"uploadspending": "0"
}
],
"expiredcontracts": [],
"inactivecontracts": []
}
/client/providers/active [GET]¶
Return list of active storage providers and corresponding settings
Sample output:
{
"providers": [
{
"LastHistoricUpdate": 4466,
"acceptingcontracts": true,
"collateral": "2314814814",
"contractprice": "300000000000000000000000",
"downloadbandwidthprice": "25000000000000",
"firstseen": 354,
"historicdowntime": 0,
"historicfailedinteractions": 0.43131736091896283,
"historicsuccessfulinteractions": 87.18474978322104,
"historicuptime": 0,
"maxcollateral": "5000000000000000000000000000",
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "52.8.2.87:1690",
"publickey": "ed25519:43413f53af6a4faba11bcf27d3d25b82be259a2a1671d22a97ac38359a7081b9",
"publickeystring": "ed25519:43413f53af6a4faba11bcf27d3d25b82be259a2a1671d22a97ac38359a7081b9",
"recentfailedinteractions": 0,
"recentsuccessfulinteractions": 24,
"remainingstorage": 975699968,
"revisionnumber": 2348,
"scanhistory": [
{
"success": true,
"timestamp": "2018-12-15T02:58:07.585416871Z"
},
{
"success": true,
"timestamp": "2018-12-15T03:05:30.256567793Z"
},
{
"success": true,
"timestamp": "2018-12-17T23:53:07.362785471Z"
},
{
"success": true,
"timestamp": "2018-12-17T23:57:19.925556696Z"
}
],
"sectorsize": 262144,
"storageprice": "1157407407",
"totalstorage": 989855744,
"unlockhash": "bmSxefo3yA52Ws5um9NFSdeRHdnVyt4iRdeu5GgUFwSUF6AsuBa3",
"uploadbandwidthprice": "1000000000000",
"version": "0.3.6",
"windowsize": 36
},
{
"LastHistoricUpdate": 4466,
"acceptingcontracts": true,
"collateral": "2314814814",
"contractprice": "300000000000000000000000",
"downloadbandwidthprice": "25000000000000",
"firstseen": 354,
"historicdowntime": 0,
"historicfailedinteractions": 2.125778421672031,
"historicsuccessfulinteractions": 89.46039349530885,
"historicuptime": 0,
"maxcollateral": "5000000000000000000000000000",
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "13.52.96.207:1690",
"publickey": "ed25519:bbb67c4613c3e3bb146c630b20e10f9c2f8638d14be4fe174aaef069abe1ece3",
"publickeystring": "ed25519:bbb67c4613c3e3bb146c630b20e10f9c2f8638d14be4fe174aaef069abe1ece3",
"recentfailedinteractions": 0,
"recentsuccessfulinteractions": 24,
"remainingstorage": 975699968,
"revisionnumber": 2358,
"scanhistory": [
{
"success": true,
"timestamp": "2018-12-14T18:43:16.357434544Z"
},
{
"success": true,
"timestamp": "2018-12-15T02:33:16.357435427Z"
},
{
"success": true,
"timestamp": "2018-12-15T07:18:21.16006678Z"
},
{
"success": true,
"timestamp": "2018-12-15T07:25:00.239986709Z"
},
{
"success": true,
"timestamp": "2018-12-15T07:29:04.571050096Z"
}
],
"sectorsize": 262144,
"storageprice": "1157407407",
"totalstorage": 989855744,
"unlockhash": "K7huKPCSPtnrgEMdWEFAne3TWiZ1Bho1gpUna9Ggr96jaKK5T9Ut",
"uploadbandwidthprice": "1000000000000",
"version": "0.3.6",
"windowsize": 36
},
]
}
/client/files [GET]¶
Return list of all files’ status that are known to the client.
Sample output:
{
"files": [
{
"dxpath": "testing/txt",
"localpath": "/home/ubuntu/test2.txt",
"filesize": 2097152,
"available": true,
"renewing": true,
"redundancy": 2,
"uploadedbytes": 4718592,
"uploadprogress": 100,
"expiration": 6210,
"filecontracts": [
"31438d979d6eba856b0bf54abe7e028be49fb78bc47bcea1e93eb9ba2a3dc04d",
"e3037621a2283e186f2177da4dd123a99ecd07c19ef1d7f758af943f02577666"
]
},
{
"dxpath": "home/mzhang/test2.txt",
"localpath": "/home/ubuntu/api_test/text2.txt",
"filesize": 2097152,
"available": true,
"renewing": true,
"redundancy": 2,
"uploadedbytes": 4718592,
"uploadprogress": 100,
"expiration": 6210,
"filecontracts": [
"e3037621a2283e186f2177da4dd123a99ecd07c19ef1d7f758af943f02577666",
"31438d979d6eba856b0bf54abe7e028be49fb78bc47bcea1e93eb9ba2a3dc04d"
]
},
{
"dxpath": "testing.txt",
"localpath": "/home/ubuntu/test2.txt",
"filesize": 2097152,
"available": true,
"renewing": true,
"redundancy": 2,
"uploadedbytes": 4718592,
"uploadprogress": 100,
"expiration": 6210,
"filecontracts": [
"31438d979d6eba856b0bf54abe7e028be49fb78bc47bcea1e93eb9ba2a3dc04d",
"e3037621a2283e186f2177da4dd123a99ecd07c19ef1d7f758af943f02577666"
]
}
]
}
/client/downloads?active=active [GET]¶
Return list of downloads
| API Flag | Description |
|---|---|
| active | Boolean. If true, return current downloading files. Otherwise, returns all downloaded and downloading files |
Sample output:
{
"downloads": [
{
"destination": "/home/ubuntu/api_test/filename.txt",
"destinationtype": "file",
"filesize": 2097152,
"length": 2097152,
"offset": 0,
"dxpath": "mzhang",
"completed": true,
"endtime": "2018-12-17T21:12:15.968824153Z",
"error": "",
"received": 2097152,
"starttime": "2018-12-17T21:12:06.764122744Z",
"starttimeunix": 1545081126764122744,
"totaldatatransferred": 4718088
},
{
"destination": "/home/ubuntu/api_test/text2.txt",
"destinationtype": "file",
"filesize": 2097152,
"length": 2097152,
"offset": 0,
"dxpath": "text2.txt",
"completed": true,
"endtime": "2018-12-15T03:45:21.505550618Z",
"error": "",
"received": 2097152,
"starttime": "2018-12-15T03:45:12.603814196Z",
"starttimeunix": 1544845512603814196,
"totaldatatransferred": 4718088
}
]
}
/client/upload/*upload_as [POST]¶
uploads file to dxchain network. If successfully uploaded file, nothing will be returned. Otherwise, specific error message will be returned.
| API Parameter | Description |
|---|---|
| upload_as | the file name that is used to upload the file to chain. When download file from the chain, this file name will be used as a key |
POST Data:
| Key | Value | Description |
|---|---|---|
| source | absolute path | source specifies the absolute path of the file that will be uploaded to chain |
Example Data:
data = {
'source' = /home/ubuntu/temp_folder/file_upload.txt
}
Example Usage:
$ curl --header "User-Agent: Dx-Agent" --user "":"dxchaingogogo" -d "source=%2Fhome%2Fubuntu%2Fdata%2FDxChain-Staff.csv" -X POST http://35.178.216.243:1688/client/upload/test.txt
Note： Currently, only sample uploading files on remote servers are supported, which include:
- /home/ubuntu/data/DxChain-2018-Plan.doc
- /home/ubuntu/data/DxChain_API_Doc.md
- /home/ubuntu/data/DxChain-Flyer.png
- /home/ubuntu/data/DxChain-Post.pdf
- /home/ubuntu/data/DxChain_SDK.zip
- /home/ubuntu/data/DxChain-Staff.csv
- /home/ubuntu/data/DxChain-Video-Closing.mp4
- /home/ubuntu/data/DxChain-Video-Opening.avi
- /home/ubuntu/data/DxChain-Whitepaper.pdf
/client/download/*filename?destination=*abs_path [GET]¶
downloads file from dxchain network. If successfully downloaded file, nothing will be returned. Otherwise, specific error message will be returned.
| API Parameter | Description |
|---|---|
| filename | name of the file saved on the chain |
| destination | the absolute path of the file |
Note: Currently, download destination must be within the directory /data/.
/client/delete/*filename [POST]¶
deletes file from dxchain network. If successfully deleted file, nothing will be returned. Otherwise, specific error message will be returned.
| API Parameter | Description |
|---|---|
| filename | the name of the file that will be deleted from the chain |
DxChainPy Toolkit¶
DxChainPy is a simple Python implementation for DxChain API, which allows users to build their own application based on DxChain Network.
Currently, the following chain data can be obtained from DxChainPy:
- network status
- consensus information
- wallet balance
- miner status
- provider settings
- client details
The operation below are also supported:
- uploading files
- downloading files
- deleting files
Currently, only sample uploading files on remote servers are supported, which include:
- /home/ubuntu/data/DxChain-2018-Plan.doc
- /home/ubuntu/data/DxChain_API_Doc.md
- /home/ubuntu/data/DxChain-Flyer.png
- /home/ubuntu/data/DxChain-Post.pdf
- /home/ubuntu/data/DxChain_SDK.zip
- /home/ubuntu/data/DxChain-Staff.csv
- /home/ubuntu/data/DxChain-Video-Closing.mp4
- /home/ubuntu/data/DxChain-Video-Opening.avi
- /home/ubuntu/data/DxChain-Whitepaper.pdf
The Github page for DxChainPy is here.