Building with Sense API

This document describes how Sense can be used and configured across various external backends.

Summary:

Users or Applications can make use of our state-of-the-art duplication detection algorithms 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. use /openapi/sense/upload API to upload the image and get image_id and estimated_fee

2. You'll need to burn 20% of the estimated_fee to start sense 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/sense/start/<<image_id>> to start sense register task. Use the transaction id and your pastelid. Expect a task_id in response.

4. Call /openapi/sense/start/<<task_id>>/state: connect with this Websocket to monitor the status of Sense 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/sense/<<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/sense/download?pid=<<pastel_id>>&txid=<<tx_id>> to download the duplication detection results for the provided image. 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 access the NFT fingerprints and their relative rareness scores, and add such to a registry of NFTs as a way to timestamp or “claim” the underlying data in a decentralized, trust-less 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 Sense 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, which then return the Relative Rareness Score in a JSON.

The process begins with Image upload call through walletnode. It returns and image 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 download the JSON results once the process completes.

Each time the user calls Sene API,the NFT is passed and added to a dedicated SQLite database hosted by the SuperNodes on Pastel. The JSON results returned from the API request are compared among the multiple SuperNodes randomly assigned to perform such calculations. If each result matches, the top-ranked SuperNode adds the JSON file to Pastel's Storage Layer via Kademlia. We then create a new Pastel Blockchain ticket, the Action_Registration_Ticket, which is signed by both the user's PastelID and the PastelIDs of each SuperNode that handled the request. This Pastel Blockchain ticket contains the SHA3-256 hash of the JSON file in Kademlia containing the results of running the Sense Protocol on the NFT as well as the SHA3-256 hash of the original NFT data. The same NFT hash is included in the JSON metadata of the corresponding NFT on the user's platform.

Once the Sense Protocol is completed by the Supernodes, they create and sign the Action_Registration_Ticket with their PastelIDs. The user then signs the Action_Registration_Ticket with the user's PastelID, at which point the final signed Action_Registration_Ticket would be written to the Pastel blockchain by the Supernodes which counter-signed it.

At this point, the user has a sense Action_Registration_Ticket on Pastel. The NFT provided by the user also has its own fingerprint vector added to the SQLite database. Thus, the next time that relatively same image is submitted to Pastel in a new sense Action_Registration_Ticket , the new NFT would result in a lower relative rareness score as it would be compared to the previous ticket for the similar NFT. In addition, the other data resulting from running the Sense Protocol on the image, such as the rareness score and the NFT perceptual hashes, would all be stored in Kademlia in a JSON file. To ensure redundancy, we create several variants of this JSON by adding a nonce to the end of each one, resulting in a different SHA3-256 hash for each copy, which are then all stored in Kademlia separately.

Because only Supernodes in Pastel can directly access Kademlia, we could set up some public-facing servers that are also Pastel Supernodes with a REST API that would respond to public requests; in these requests, users could submit an image file hash and get as a result the corresponding JSON file from Kademlia, assuming that this particular image had been submitted previously. But to avoid needing to rely on some external service, Rarible might elect to set up their own Pastel Walletnode so that they could set up an API like that on their own and cover the cost of serving it at scale.

Action Registration Ticket

1. PastelID of the caller.

2. Current Block number & Block Hash.

3. Action type (cascade or sense). sense 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.

Action registration ticket contains following data

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 can download the results in JSON using Walletnode's download API for Sense.