Ownership RPC API

API documentation for 0xEssential's NFT Ownership RPC API

EIP-3668 standardizes an approach for contracts that require trusted, offchain data in order to perform a transaction. This standard is also sometimes called CCIP Read, and we often use OffchainLookup as a shorthand.

The EIP-3668 standard requires that a contract reverts with an OffchainLookup error when it requires some external data to perform the requested call or transaction. This custom error includes params that instruct the client how to fetch that external data and how to resubmit the transaction with the fetched offchain data.

0xEssential's OSS handles this whole exchange - our EssentialForwarder contract reverts with an OffchainLookup error with params that instruct the client to call our Ownership RPC API.

Typical integrations will use 0xEssential's deployed EssentialForwarder and Ownership RPC API. We provide the Ownership API source code and some documentation here for transparency and to allow developers to deploy their own instance if desired.

Source & Deployment

0xEssential has developed an open-source NodeJS EIP-3668 compliant RPC API that can be used with the EssentialForwarder contract.

The source code is available in the 0xEssential/ownership-rpc Github repo.

The API is deployed at https://middleware.nfight.xyz

The deployments of the EssentialForwarder on Mumbai and Matic are setup to use this API.

The API supports lookup of ERC-721 NFTs from any EVM compatible chain. It uses ERC721.ownerOf to perform the lookup.

Purpose & Logic

The Ownership RPC API is responsible for performing a live lookup of NFT ownership on the relevant EVM chain. The API exposes a single endpoint and expects parameters that are included in an OffchainLookup error.

Your client (i.e. essential-autotask) will call this API when it receives an EIP-3668 OffchainLookup error from an EssentialForwarder. The API does not serve other general purposes so is not documented.

The Ownership RPC API also nonces for added security - if the nonce param it receives do not match the EssentialForwarder contract state nonce for the signer, the API will error.

Once the RPC API looks up the current owner of the requested NFT, it uses private keys to sign a message that includes the owner and other relevant data. This signature is returned to the client.

The client then submits a meta-transaction using the API response and other data it received from the OffchainLookup error.

ENV Vars

0xEssential's Ownership API requires an Infura account to perform NFT ownership queries and a private key for the trusted ownership signer.

If you're deploying your own instance you need to provide these values or edit the source to use your preferred approach.

INFURA_KEY

An Infura API key is required to perform lookups of NFT ownership.

OWNERSHIP_SIGNER_PRIVATE_KEY

The Ownership RPC API signs a payload for each request using a trusted EOA. The API ENV needs the private key to sign a proof. This private key should correspond to the public key on the EssentialForwarder _ownershipSigner.

API Docs

The API is not intended for general consumption so we do not provide endpoint documentation. Review the EIP-3668 spec to understand the available endpoints.