Cross-web data read/write with Refractors

Refractors play a crucial role in facilitating seamless communication and data exchange between on-chain applications and off-chain services. This section provides a technical overview of how Refractors enable the execution of Refract Framework Tokens (RFTs) and handle return data from Off-chain Service Endpoints (OSEs).

RFT Execution

To execute an RFT and redeem its encapsulated service, the user or dApp owning the RFT must invoke the use() function within the RFT object itself. This function call emits a useRFTEvent(), which is picked up by the Refractor reverse oracle and relayed to the corresponding OSE for execution.

Data Input Encryption

In cases where an off-chain service requires data input (e.g., shipping address for a Shopify product), the user or dApp can encrypt the data using the OSE's public address key and the AES encryption scheme. The encrypted data is then stored within the RFT object's dynamic data fields, making it accessible to the OSE for execution.

Service Execution Status Updates

As the service execution begins, the OSE updates the utilityState data field of the RFT to "processing" to indicate that the service order is being fulfilled. Once the service execution is completed (e.g., the end user receives the cup of coffee promised by the RFT), the OSE marks the RFT's utilityState data field as "used". RFTs with a "used" state can still be traded but have no redemption value.

OSE Return Data Handling

Some off-chain services may yield return data (e.g., fetching the latest weather data from weather.com for a specific location). In such cases, the RFT object serves as a data container for OSEs to post the return data.

Writing Return Data to RFT

When an RFT is executed, it is not immediately "burned" or deleted. Instead, the OSE can write the return data into the dynamic fields of the RFT, even if the RFT is owned by another entity. This is possible because the OSE is the original signer and creator of the RFT.

It is recommended, but not required, to have the return data in JSON format and map the individual root fields in JSON to individual dynamic data fields of the same name within the RFT. This allows dApps to directly read the return data by accessing the corresponding dynamic data fields.

Here's an example of mapping return data JSON to RFT dynamic data fields:

Return data JSON:

{
  "Date": "2024-5-15",
  "Weather": "Sunny",
  "Wind_speed": [12, 0, 12, 4]
}

RFT dynamic data fields:

Date="2024-5-15"
Weather="Sunny"
Wind_speed=[12, 0, 12, 4]

On-chain Event Trigger Callback

Refractors can be configured to automatically trigger a webhook when specific on-chain events are emitted. For example, when a PlayerOpenGiftboxEvent is emitted, the Refractor can be set up to invoke a designated callback function or API endpoint.

Conclusion

By leveraging Refractors for cross-web service and data execution, developers can seamlessly integrate on-chain applications with off-chain services, enabling powerful and interactive experiences. The ability to encrypt data inputs, handle return data, and trigger callbacks based on on-chain events provides a flexible and secure framework for building decentralized applications that interact with the real world.