Building with Cascade API

If you'd like to store files on the blockchain, but not necessarily make an NFT or perform dupe-detection, you can use the Cascade API interface.

Summary:

Users or Applications can make use of Pastel's storage layer via our Walletnode application. We've already discussed how to install and run walletnode in previous section & How you can create your PastelID which is required to work with the APIs here.

Once you have walletnode up & running and also have a registered PastelID, you can follow these steps.

1. Call endpoint /openapi/cascade/upload to upload the file and get file_id and estimated_fee

2. You'll need to burn 20% of the estimated_fee to start cascade register task. Send 20% of the estimated burn fee (rounded up) to the burn address PtpasteLBurnAddressXXXXXXXXXXbJ5ndd (so if the estimated burn fee is 100 PSL, send 20). Note the response transaction id.

3. Call /openapi/cascade/start/<<file_id>> to start cascade register task. Use the transaction id and your pastelid. Expect a task_id in response.

4. Call /openapi/cascade/start/<<task_id>>/state: connect with this websocket to monitor the status of Cascade register task. This will, over time, allow you to see the state of the supernodes as they process it. When this yields "Task Completed" your art has been processed by the blockchain!

5. Use /openapi/cascade/<<task_id>>/history` to see task status history and details because websocket mentioned in (4) will only remain active until the registration process is active.

6. Use /openapi/cascade/download?pid=<<pastel_id>>&txid=<<tx_id>> to download the original file any time. tx_id is the RegistrationTXID or reg_txid you'll see in response of (4) and (5).

Background

Any existing platform, project, or protocol can use Pastel's storage layer to store any type of file(s) in a secure & decentralized way - without needing to migrate their existing backend infrastructure.

The user first creates a PastelID for their underlying project, which will be used to submit all Cascade Requests API calls on the Pastel Network. Each call submits a request via HTTP to walletnode which in turn communicates with the network of Pastel SuperNodes viagRPC to store user's file in the network's storage layer.

The process begins with File upload call through walletnode. It returns file ID and estimated fee. The user first needs to burn 20% of the returned fee to the burn address PtpasteLBurnAddressXXXXXXXXXXbJ5ndd. The TxID of this transaction is used in the subsequent API call which starts the process. The user can access the file anytime after the process completes successfully.

WalletNode, upon receiving cascade request, connects with the network of SuperNodes and then sends requests to connected SuperNodes to verify if the request is a valid one. Mainly, SuperNodes verify the Burn TxID (The TxID of the 20% burn of estimated fee that the user or connecting app needs to do). After that, WalletNode uploads the file to connected SuperNodes for further processing and then generates RaptorQ Identifier files, calculates hash of the data file and size of the file as the fee is multiple of the size of the file in Megabytes. WalletNode then creates an action ticket and signs & sends it to connected SuperNodes.

SupeNodes, on the other hand, creates action registration ticket as mentioned here.

Action Registration Ticket

Action registration ticket contains following data

1. PastelID of the caller.

2. Current Block number & Block Hash.

3. Action type (cascade or sense). cascade in this case.

4. Signatures of the SuperNodes taking part in the process.

5. Storage Fee in PSL.

6. Key: a unique value to identify this ticket.

7. Label: the BurnTxID of the initial 20% burn transaction.

This action registration ticket is sent to blockchain for registration of this cascade action. Walletnode then waits until there are confirmations from enough nodes about the action registration.

Action Activation Ticket

Action activation ticket has the following data

1. TxID of the Action Registration ticket.

2. PastelID of the action caller

3. Ticket storage fee in PSL, should match the storage fee from the Action Registration Ticket

4. Base64-encoded signature of the ticket created using the Action Caller's Pastel ID

5. Block at which Action was called (Action Registration ticket was created)

Once it gets enough confirmations on action registration ticket, WalletNode then creates corresponding Action Activation ticket and wait for enough confirmations from Blockchain before it marks the cascade request as a successful one.

Once the process is completed successfully, the user's file is stored on Pastel's storage layer in a secure & decentralized way and it can be retrieved anytime in its original shape & form.