Create chainhook for NFT contract

[whoabuddy]

This will be the main chainhook that monitors and processes mint actions.

By sending Bitcoin to the artist address, the chainhook should automatically submit the relevant Bitcoin tx info to the Stacks contract to complete the mint.

[whoabuddy]

@lgalabru and @aulneau curious on your input here at a high-level.

For the initial mint we'll be monitoring a specific BTC address for transactions.

In response to Bitcoin being sent to that address, we want to make the associated mint transaction on the Stacks side.

We have the cbtc example as a starting point, and clarinet integrate will allow for devnet testing.

What does the process look like for moving from devnet to testnet/mainnet?

Are there any requirements we should think about up front or start setting up now? (noting #12 is on my list)

Any details are helpful! 🙏

[lgalabru]

hey @whoabuddy! when working on testnet / mainnet, there is a convenient replay mode that can be used locally, for working with real data. happy to hop on a call and give you a tour of this feature!

[whoabuddy]

This sounds great! Will arrange with you async, also curious if you have any best practice recommendations for #12 alongside it!

[whoabuddy]

Shoutout to @lgalabru for a great session, sharing the relevant notes here as an implementation guide once we get closer to this step.

Chainhook Description

A chainhook node is an event observer to a Stacks node that can access both Stacks and Bitcoin on-chain data.

Using this connection, we can automate a task that reacts to an on-chain event.

In our case, we want to monitor the artist address and when it receives Bitcoin, send the relevant Stacks TX to mint the Bitcoin NFT.

Chainhook Structure

The following folders define chainhook operations:

• chainhooks: YAML files that define what chain and event to monitor for, as well as what action to take
• deployments: YAML files that define the default setup for clarinet integrate as well as devnet actions used to trigger defined chainhooks
• serverless: a simple serverless API example that receives and processes events from a chainhook

Chainhook Development Flow

Running clarinet integrate and accessing devnet is the easiest way to test and play with chainhooks.

The files that need to be configured include:

• deployment: setup YAML for default devnet plan to deploy bitcoin-colors and supporting contracts
• deployment: setup YAML for simulated btc xfer to activate chainhook (devnet only)
• chainhook: setup YAML to monitor for btc xfer to authority (artist) address
• serverless: setup handler to receive http event and create relevant Stacks tx (devnet only)

All devnet addresses, Stacks and Bitcoin, come from devnet.toml and the defaults include comments to help understand which keys go with which addresses.

Moving to Testnet/Mainnet

At this stage, we'd start using the hosted chainhook implementation, which requires:

• deploying contracts to testnet/mainnet (can be done with Clarinet)
  • the testnet.toml and mainnet.toml files contain the keys used by Clarinet
• instead of deployment plans, testing would occur directly from wallets (e.g. Electrum or Xverse)
• instead of the serverless API, an endpoint will need to consume events, preferably with a caching layer
  • early thought on this: store events in KV queue, processing queue is iterate and fetch new

Hosted Chainhook Implementation

Chainhooks require the chainhook node, a Stacks node, and a Bitcoin node to operate.

Rather than run these ourselves, we plan to test and use Hiro's new hosted chainhook service.

It will provide the chainhook infrastructure to monitor and send events to a separate back-end.

We should be able to run a simple and scalable back-end using Cloudflare Workers and KV.

Clarinet Tips and Tricks

When in doubt, use clarinet help and clarinet <feature> help!

Generate default deployment plan: clarinet deployment generate --devnet

To run a deployment plan: clarinet deployment apply -p deployments/wrap-btc.devnet-plan.yaml

• the network used is included in the plan
• can be used to deploy contracts to testnet/mainnet

JSON to create a dyanamic chainhook: clarinet chainhooks check --output-json

• used by Clarinet under the hood
• YAML files are converted to JSON
• will be needed for NFT claim step

Add mainnet requirements, which re-maps mainnet contracts to work on devnet: clarinet requirements add SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C.bitcoin-whales