using.md
1 --- 2 outline: [2, 3] 3 --- 4 # Codex 사용하기 5 6 [REST API](/developers/api)를 사용하여 Codex와 상호작용할 수 있습니다. 이 문서에서는 몇 가지 유용한 예제를 보여드리겠습니다. 7 8 또한 [Codex App UI](https://app.codex.storage)를 확인할 수 있습니다. 9 10 [Linux/macOS](#linux-macos)와 [Windows](#windows)의 명령줄 인터프리터는 약간 다르게 작동하므로 사용 중인 OS에 맞는 단계를 사용하세요. 11 12 ## Linux/macOS 13 14 ### Overview 15 1. [Debug](#debug) 16 2. [Upload a file](#upload-a-file) 17 3. [Download a file](#download-a-file) 18 4. [Local data](#local-data) 19 5. [Create storage availability](#create-storage-availability) 20 6. [Purchase storage](#purchase-storage) 21 7. [View purchase status](#view-purchase-status) 22 23 ### Debug 24 An easy way to check that your node is up and running is: 25 26 ```shell 27 curl http://localhost:8080/api/codex/v1/debug/info \ 28 -w '\n' 29 ``` 30 31 This will return a JSON structure with plenty of information about your local node. It contains peer information that may be useful when troubleshooting connection issues. 32 33 ### Upload a file 34 > [!Warning] 35 > Once you upload a file to Codex, other nodes in the network can download it. Please do not upload anything you don't want others to access, or, properly encrypt your data *first*. 36 37 ```shell 38 curl -X POST \ 39 http://localhost:8080/api/codex/v1/data \ 40 -H 'Content-Type: application/octet-stream' \ 41 -w '\n' \ 42 -T <FILE> 43 ``` 44 45 On successful upload, you'll receive a CID. This can be used to download the file from any node in the network. 46 47 > [!TIP] 48 > Are you on the [Codex Discord server](https://discord.gg/codex-storage)? Post your CID in the [# :wireless: | share-cids](https://discord.com/channels/895609329053474826/1278383098102284369) channel, see if others are able to download it. Codex does not (yet?) provide file metadata, so if you want others to be able to open your file, tell them which extension to give it. 49 50 ### Download a file 51 When you have a CID of data you want to download, you can use the following commands: 52 53 ```shell 54 # paste your CID from the previous step here between the quotes 55 CID="..." 56 ``` 57 58 ```shell 59 curl "http://localhost:8080/api/codex/v1/data/${CID}/network/stream" \ 60 -o "${CID}.png" 61 ``` 62 63 Please use the correct extension for the downloaded file, because Codex does not store yet content-type or extension information. 64 65 ### Local data 66 You can view which datasets are currently being stored by your node: 67 68 ```shell 69 curl http://localhost:8080/api/codex/v1/data \ 70 -w '\n' 71 ``` 72 73 ### Create storage availability 74 > [!WARNING] 75 > This step requires that Codex was started with the [`prover`](/learn/run#codex-storage-node) option. 76 77 In order to start selling storage space to the network, you must configure your node with the following command. Once configured, the node will monitor on-chain requests-for-storage and will automatically enter into contracts that meet these specifications. In order to enter and maintain storage contracts, your node is required to submit zero-knowledge storage proofs. The calculation of these proofs will increase the CPU and RAM usage of Codex. 78 79 ```shell 80 curl -X POST \ 81 http://localhost:8080/api/codex/v1/sales/availability \ 82 -H 'Content-Type: application/json' \ 83 -w '\n' \ 84 -d '{ 85 "totalSize": "8000000", 86 "duration": "7200", 87 "minPrice": "10", 88 "maxCollateral": "10" 89 }' 90 ``` 91 92 For descriptions of each parameter, please view the [spec](https://api.codex.storage/#tag/Marketplace/operation/offerStorage). 93 94 ### Purchase storage 95 To purchase storage space from the network, first you must upload your data. Once you have the CID, use the following to create a request-for-storage. 96 97 Set your CID: 98 99 ```shell 100 # paste your CID from the previous step here between the quotes 101 CID="..." 102 echo "CID: ${CID}" 103 ``` 104 105 Next you can run: 106 107 ```shell 108 curl -X POST \ 109 "http://localhost:8080/api/codex/v1/storage/request/${CID}" \ 110 -w '\n' \ 111 -d '{ 112 "duration": "3600", 113 "reward": "1", 114 "proofProbability": "5", 115 "expiry": "1200", 116 "nodes": 5, 117 "tolerance": 2, 118 "collateral": "1" 119 }' 120 ``` 121 122 For descriptions of each parameter, please view the [spec](https://api.codex.storage/#tag/Marketplace/operation/createStorageRequest). 123 124 When successful, this request will return a Purchase-ID. 125 126 ### View purchase status 127 Using a Purchase-ID, you can check the status of your request-for-storage contract: 128 129 ```shell 130 # paste your PURCHASE_ID from the previous step here between the quotes 131 PURCHASE_ID="..." 132 ``` 133 134 Then: 135 136 ```shell 137 curl "http://localhost:8080/api/codex/v1/storage/purchases/${PURCHASE_ID}" \ 138 -w '\n' 139 ``` 140 141 This will display state and error information for your purchase. 142 | State | Description | 143 |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 144 | Pending | Request is waiting for chain confirmation. | 145 | Submitted | Request is on-chain. Hosts may now attempt to download the data. | 146 | Started | Hosts have downloaded the data and provided proof-of-storage. | 147 | Failed | The request was started, but (too many) hosts failed to provide proof-of-storage on time. While the data may still be available in the network, for the purpose of the purchase it is considered lost. | 148 | Finished | The request was started successfully and the duration has elapsed. | 149 | Expired | (Not enough) hosts have submitted proof-of-storage before the request's expiry elapsed. | 150 | Errored | An unfortunate state of affairs. The 'error' field should tell you more. | 151 152 ## Windows 153 154 ### Overview {#overview-windows} 155 1. [Debug](#debug-windows) 156 2. [Upload a file](#upload-a-file-windows) 157 3. [Download a file](#download-a-file-windows) 158 4. [Local data](#local-data-windows) 159 5. [Create storage availability](#create-storage-availability-windows) 160 6. [Purchase storage](#purchase-storage-windows) 161 7. [View purchase status](#view-purchase-status-windows) 162 163 ### Debug {#debug-windows} 164 An easy way to check that your node is up and running is: 165 166 ```batch 167 curl http://localhost:8080/api/codex/v1/debug/info 168 ``` 169 170 This will return a JSON structure with plenty of information about your local node. It contains peer information that may be useful when troubleshooting connection issues. 171 172 ### Upload a file {#upload-a-file-windows} 173 > [!Warning] 174 > Once you upload a file to Codex, other nodes in the network can download it. Please do not upload anything you don't want others to access, or, properly encrypt your data *first*. 175 176 ```batch 177 curl -X POST ^ 178 http://localhost:8080/api/codex/v1/data ^ 179 -H "Content-Type: application/octet-stream" ^ 180 -T <FILE> 181 ``` 182 183 On successful upload, you'll receive a CID. This can be used to download the file from any node in the network. 184 185 > [!TIP] 186 > Are you on the [Codex Discord server](https://discord.gg/codex-storage)? Post your CID in the [# :wireless: | share-cids](https://discord.com/channels/895609329053474826/1278383098102284369) channel, see if others are able to download it. Codex does not (yet?) provide file metadata, so if you want others to be able to open your file, tell them which extension to give it. 187 188 ### Download a file {#download-a-file-windows} 189 When you have a CID of data you want to download, you can use the following commands: 190 191 ```batch 192 :: paste your CID from the previous step here between the quotes 193 set CID="..." 194 ``` 195 196 ```batch 197 curl "http://localhost:8080/api/codex/v1/data/%CID%/network/stream" ^ 198 -o "%CID%.png" 199 ``` 200 201 Please use the correct extension for the downloaded file, because Codex does not store yet content-type or extension information. 202 203 ### Local data {#local-data-windows} 204 You can view which datasets are currently being stored by your node: 205 206 ```batch 207 curl http://localhost:8080/api/codex/v1/data 208 ``` 209 210 ### Create storage availability {#create-storage-availability-windows} 211 > [!WARNING] 212 > This step requires that Codex was started with the [`prover`](/learn/run#codex-storage-node) option. 213 214 In order to start selling storage space to the network, you must configure your node with the following command. Once configured, the node will monitor on-chain requests-for-storage and will automatically enter into contracts that meet these specifications. In order to enter and maintain storage contracts, your node is required to submit zero-knowledge storage proofs. The calculation of these proofs will increase the CPU and RAM usage of Codex. 215 216 ```batch 217 curl -X POST ^ 218 http://localhost:8080/api/codex/v1/sales/availability ^ 219 -H "Content-Type: application/json" ^ 220 -d "{""totalSize"": ""8000000"", ""duration"": ""7200"", ""minPrice"": ""10"", ""maxCollateral"": ""10""}" 221 ``` 222 223 For descriptions of each parameter, please view the [spec](https://api.codex.storage/#tag/Marketplace/operation/offerStorage). 224 225 ### Purchase storage {#purchase-storage-windows} 226 To purchase storage space from the network, first you must upload your data. Once you have the CID, use the following to create a request-for-storage. 227 228 Set your CID: 229 230 ```batch 231 :: paste your CID from the previous step here between the quotes 232 set CID="..." 233 echo CID: %CID% 234 ``` 235 236 Next you can run: 237 238 ```batch 239 curl -X POST ^ 240 "http://localhost:8080/api/codex/v1/storage/request/%CID%" ^ 241 -H "Content-Type: application/json" ^ 242 -d "{""duration"": ""3600"",""reward"": ""1"", ""proofProbability"": ""5"", ""expiry"": ""1200"", ""nodes"": 5, ""tolerance"": 2, ""collateral"": ""1""}" 243 ``` 244 245 For descriptions of each parameter, please view the [spec](https://api.codex.storage/#tag/Marketplace/operation/createStorageRequest). 246 247 When successful, this request will return a Purchase-ID. 248 249 ### View purchase status {#view-purchase-status-windows} 250 Using a Purchase-ID, you can check the status of your request-for-storage contract: 251 252 ```batch 253 :: paste your PURCHASE_ID from the previous step here between the quotes 254 set PURCHASE_ID="..." 255 ``` 256 257 Then: 258 259 ```batch 260 curl "http://localhost:8080/api/codex/v1/storage/purchases/%PURCHASE_ID%" 261 ``` 262 263 This will display state and error information for your purchase. 264 | State | Description | 265 |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 266 | Pending | Request is waiting for chain confirmation. | 267 | Submitted | Request is on-chain. Hosts may now attempt to download the data. | 268 | Started | Hosts have downloaded the data and provided proof-of-storage. | 269 | Failed | The request was started, but (too many) hosts failed to provide proof-of-storage on time. While the data may still be available in the network, for the purpose of the purchase it is considered lost. | 270 | Finished | The request was started successfully and the duration has elapsed. | 271 | Expired | (Not enough) hosts have submitted proof-of-storage before the request's expiry elapsed. | 272 | Errored | An unfortunate state of affairs. The 'error' field should tell you more. | 273 274 ## Known issues 275 1. We add a new line to the API calls to get more readable output, please check [[rest] Add line ending on responses #771](https://github.com/codex-storage/nim-codex/issues/771) for more details.