sCrypt: Ordinals oracle

This post was first published on Medium, and we republished with permission from the sCrypt team. YusufIdiMaina. Connect with the post’s author, Yusuf Idi Maina, on LinkedIn.

Bitcoin smart contracts possess the capability to determine the validity of satoshis within a UTXO, yet they face limitations when verifying the presence and quantity of 1SatOrdinals tokens in a UTXO. While on-chain miners can validate the number of satoshis, Ordinals tokens and specific NFTs are validated by an external indexer off-chain, which presents challenges in various applications such as token swaps and sales. To address this, oracles are introduced to ensure the authenticity and integrity of Ordinals tokens required when invoking a contract.

This tutorial will guide you through the process of using the WitnessOnChain oracle to validate transaction inputs referencing UTXOs containing Ordinals NFTs and BSV20 tokens.

WitnessOnChain API

The WitnessOnChain oracle offers an API to retrieve inscription details from an outpoint:

https://api.witnessonchain.com/v1/inscription/bsv/{network}/outpoint/{txid}/{vout}

API Response Structure

The response from the API is a signed message with the following structure:

Custom Type Definition and Parser Function

Based on this structure, we define a custom type `Msg` and a helper parser function to decode the message.

Implementing the Contract

In this section, we implement a demonstration contract that is successfully invoked only when the second input (input #1) of the spending transaction contains a specific amount of a certain BSV20 token.

To verify the oracle’s signed message, the oracle’s public key must be included in the contract. Additionally, to record the specific BSV20 token and its amount, we introduce two additional properties.

Methods

The public `unlock` method requires three parameters:

1. `msg`: The oracle’s signed message.
2. `sig`: The oracle’s signature.
3. `tokenInputIndex`: An index marking which input is the token input.

We first retrieve the token outpoint from `this.prevouts`. We then parse the message signed by the oracle and verify it against the outpoint. With this verification, we can confidently use the token information, such as amount and ID, in the remaining contract code.

Conclusion

Congratulations! You have successfully completed a tutorial on validating 1SatOrdinals inputs with an oracle. This process enhances the security and reliability of smart contracts dealing with Ordinals tokens and NFTs by leveraging external validation mechanisms.

For a full example contract and its corresponding test, please refer to our boilerplate repo.

Watch: sCrypt Hackathon 2024 (16th March 2024, AM)