Understanding EternalBTC: Real-Time On-Chain Price NFTs

The fusion of blockchain and art continually opens new possibilities in the world of NFTs (Non-Fungible Tokens). EternalBTC, the contract we'll explore today, isn't just digital art; it's a unique NFT contract possessing the remarkable ability to display the real-time BTC/USDC spot price from the Hyperliquid blockchain.

In this article, we'll dissect the `EternalBTC.sol` code, explaining the following technical highlights in an accessible way:

• Hyperliquid Precompile: How does it fetch BTC prices from a "special address" on the blockchain?
• Dynamic Metadata: How does the HTML and JavaScript (akin to a miniViem) embedded in the NFT's `tokenURI` achieve real-time price display?
• Owner Customization: The mechanism and significance of allowing NFT owners to update the RPC endpoint.

Let's peek into a future woven from on-chain data and NFTs!

The heart of the EternalBTC NFT is its ability to retrieve the BTC price from a Precompile contract available on the Hyperliquid blockchain.

What is a Precompile? Typically, smart contracts are code executed on the EVM (Ethereum Virtual Machine). However, Precompiles are mechanisms to call native blockchain functions (implemented outside the EVM for speed and efficiency) through specific, fixed addresses. They offer advantages like lower gas costs and faster execution.

EternalBTC utilizes the following precompile address to fetch the BTC/USDC spot price index:

Diagram 1

Price Fetching Mechanism (`getSpotPrice` & `getPriceFormatted`)

The `getSpotPrice` function performs a `staticcall` to this Precompile address. A `staticcall` is a read-only call that doesn't alter the blockchain state, making it safe for retrieving external information.

Diagram 2

Here's the breakdown:

1. `abi.encode(index)`: Generates data specifying which price index to retrieve (here, `142` corresponds to BTC/USDC).
2. `PRECOMPILE_ADDRESS.staticcall(...)`: Sends this data to the Precompile, requesting the price information.
3. `abi.decode(result, (uint64))`: Converts the byte array (`result`) returned by the Precompile into a `uint64` price data type.
4. `getPriceFormatted`: Takes the raw `uint64` price from `getSpotPrice` and uses `NFTSVG.formatPrice` to format it into a human-readable string (e.g., "65432.123").

This allows the EternalBTC contract to directly access reliable BTC price data from an on-chain source.

The true marvel of the EternalBTC NFT is its ability to **fetch and display the latest BTC price whenever the NFT is viewed**. This is achieved through HTML and JavaScript embedded within the NFT's metadata, specifically in the `animation_url` field.

The Structure of `tokenURI`

The ERC721 standard dictates that the `tokenURI` function returns the NFT's metadata (name, description, image, etc.) in JSON format. In EternalBTC, the `generateTokenURI` function dynamically creates this JSON.

Diagram 3

The key element here is `animation_url`. It contains the HTML content generated by `generateHTML`, stored as a **Base64-encoded Data URI**. When a wallet or marketplace interprets this `animation_url`, the embedded HTML/JavaScript runs in a browser (or similar environment).

`generateHTML` and Embedded JavaScript (miniViem)

The `generateHTML` function produces a complete HTML page as a string, including CSS for styling and JavaScript for executing the price display logic.

Diagram 4

What this JavaScript code does is essentially act as a **"miniViem"** (a very lightweight implementation of the core functionalities of the Viem library):

1. JSON-RPC Communication: The `sendJsonRpcRequest` function sends JSON-RPC requests like `eth_call` to the specified RPC endpoint.
2. ABI Encoding/Decoding: Functions like `encodeUint32` and `decodeString` prepare the data (function selector + arguments) needed to call contract functions via `eth_call` and interpret the return values from the contract.
3. Contract Interaction:
   • First, `getRPCURL` (the JavaScript version) uses `eth_call` to invoke the **contract's `getRPCURL(tokenId)` function**, attempting to retrieve the RPC endpoint URL set for that specific NFT. If none is set or retrieval fails, it falls back to the default RPC (`https://rpc.hyperliquid.xyz/evm`).
   • Next, `fetchAndDisplayPrice` uses the determined RPC endpoint (`actualRpc`) to call the **contract's `getPriceFormatted(priceIndex)` function** via `eth_call`.
4. Display Update: It decodes the formatted price string returned from `getPriceFormatted` using `decodeString` and displays it within the HTML element `#typewriter`. This is executed periodically (roughly every minute according to the code) by `schedulePriceUpdate`.
5. Visual Enhancements: Code involving `XorShift`, `overlappedScramble`, `initBGscramble`, etc., adds visual flair like a terminal-style background animation and a typewriter effect for the text, making the NFT visually engaging.

In essence, the environment displaying the NFT (the browser in a wallet or marketplace) queries the blockchain **at runtime** to fetch the latest price and update the display. If the blockchain state changes, the NFT's appearance follows suit.

Blockchain RPC endpoints can sometimes be unreliable or raise concerns about centralization and censorship resistance. EternalBTC addresses this by providing the `setRPCURL` function, allowing NFT owners to **set their own trusted RPC endpoint**.

Diagram 5

Here's how it works:

1. Only the owner of the NFT (or an address approved by the owner) can call `setRPCURL`.
2. This saves the custom RPC URL in the `_tokenRpcUrls` mapping, associated with that specific `tokenId`.
3. The JavaScript within the `animation_url`, as mentioned earlier, first calls the contract's `getRPCURL` function when fetching the price. If a custom URL is set for that token, it will use that custom URL instead of the default RPC.

This is a crucial feature that grants users the **freedom to choose their data retrieval path**, fostering a more decentralized and censorship-resistant NFT experience.

The `mint` function, where new EternalBTC NFTs are born, operates as follows:

Diagram 6

During minting, the price obtained via `getSpotPrice` is recorded as the `MintedPrice` attribute within the NFT's metadata (`attributes`) and is also used in generating the SVG image (`image`). Subsequently, the `tokenURI`, containing the `animation_url` with its real-time display capabilities, is set, bestowing the EternalBTC NFT with its unique value.