IP-NFTs: Everything you need to know as a developer
IP-NFTs are non fungible tokens that represent legally binding intellectual property (IP) currently being used within decentralized science (DeSci). Here, we outline their inner workings and how you could utilize their metadata schema, data layer and smart contract methods to create your own intellectual property representation on EVM based blockchains. To get started with the general idea and scope of IP-NFTs, we recommend to first read our vision of the future of research and our non technical intro into IP-NFT mints for users.
Tokens in a Nutshell
Non fungible tokens (NFTs) are smart contract based assets that associate a unique token identifier with the blockchain address of its respective owner. Their underlying smart contracts define rules on how they are minted (brought into existence), transferred or burned (destroyed). It also can restrict their ability to be transferred or offer features that are unlocked for individual token holders. Two standard NFT implementations have emerged in the Ethereum ecosystem so far: the classic ERC-721 defines a unique ownership relationship between asset ids and their owners. It adds a rudimentary metadata standard by exposing a tokenURI(uint) method that yields an individual (or common) link to the metadata of each asset id. The slightly newer multi token standard ERC-1155 is not fully compatible to ERC-721 but also allows users to mint and distribute several tokens of the same “kind”, not unlike several instances of a rare - but not unique - gem. An ERC-1155 token kind with only one instance effectively represents assets in the same way as ERC-721 does.
When it comes to web3 based ownership of assets, those two ERCs are the gold standard, they’re supported by all major marketplaces and countless projects have built an ecosystem around them for trading, locking, voting and fractionalizing. NFTs can represent real world assets and brand values, too. We’re using them to represent an ownership aspect for the most abstract asset class of them all: intellectual property.
Tokenizing Intellectual Property with NFTs
While there’s no final answer on how real world IP can be represented by a blockchain based asset, IP-NFTs refer to legally binding paper agreements that are attached to their metadata as digital copies (PDFs). Those agreements denominate the owning entity of an intellectual property as the holder of an NFT on a certain collection. The current NFT owner can legally prove that they’re holding the IP rights by downloading and verifying the attached legal documents on their own machine. Not all agreements are meant to be visible to the general public though, so mostly these documents shall be encrypted in a way that only the current NFT holder or users they granted read access can decrypt them — an aspect that’s also known as “token gated” content.
Once represented as an NFT, all known token mechanics become operational on the IP: it can be traded on open marketplaces, being bid and asked upon, it can be fractionalized to represent distributed ownership rights or even locked into token synthesizers to farm tokens that represent voting rights on other protocols. It’s not the IP-NFT protocol itself that unleashes these possibilities, it’s the NFT ecosystem that’s unlocked once they have been minted by their initial holders.
Technical Foundations
IP-NFTs are ERC-1155 assets on Ethereum blockchains. Their relevant collection contract is deployed on mainnet and on Görli testnet. Each token’s metadata is stored as a file descriptor URI (e.g. ar://HxXKCIE0skR4siRNYeLKI61Vwg_TJ5PJTbxQmtO0EPo) that must be resolved client side, e.g. by using decentralized storage network gateways (Arweave or IPFS). The contract is non enumerable, i.e. users can’t simply query their owned assets on chain but rather must rely on reading the respective event logs to build their own off chain state. We’ve deployed subgraphs on mainnet and on Görli that can be queried for asset ownership and other IP-NFT related information. Here’s a GraphQL example on how to do that:
query IPNFTsOf($owner: ID!)
{
ipnfts(where: {owner: $owner}) {
id
owner
createdAt
tokenURI
}
}Variables:
{
"owner": "0xd1f5B9Dc9F5d55523aB25839f8785aaC74EDE98F"
}Result:
{
"data": {
"ipnfts": [
...
{
"id": "21",
"owner": "0xd1f5b9dc9f5d55523ab25839f8785aac74ede98f",
"createdAt": "1671818892",
"tokenURI": "ar://HxXKCIE0skR4siRNYeLKI61Vwg_TJ5PJTbxQmtO0EPo"
}
]
}
}Interacting with Smart Contracts
A detailed instruction on how accounts can interact with blockchain based smart contracts is far out of scope of this article. If you’re new to that space, it’s highly adviseable to familiarize yourself with the fundamentals of Ethereum development and understand how clients interact with deployed contracts using providers, signers, transactions and contract ABIs.
We’ve deployed the contracts as UUPS proxies that are owned and upgradeable by the Molecule developer team, thus the contract you’re interacting with and the contract that contains the current logic are different. Make sure to always invoke functions on the UUPS proxy — its official addresses can be found on the public repo’s README file. The implementation contracts have been verified on Etherscan, so you can easily retrieve their ABIs.
Reserving Token IDs
IP-NFTs can generally be minted by arbitrary accounts. However, to keep the collection’s items as clean and valid as possible, we added a guard in front of the mintReservation method that requires a minter to hold a valid mintpass. To retrieve a mintpass for mainnet usage, users can submit this self service form that notifies the Molecule team to drop a new mintpass for the requestor. On testnets users can simply issue mintpasses for themselves, either by following the interactive flow on the official IP-NFT minting UI or by calling one of our dedicated mintpass dispenser contract’s dispense methods on chain.
Once holding a mintpass, the next step on the minting journey is to reserve an IP-NFT token id by calling the IP-NFT contract’s reserve() method. This capturing step is necessary because the legal documents attached to the final IP-NFT are referring to the NFT’s token id that only becomes available after the mint has occurred. Minters will use the token id to craft the legal documents that outline the rights and obligations of owning that NFT in the real world. A selection of premade contract templates for IP-NFTs can be found on Github.
Assemble and Upload Metadata
The JSON metadata documents behind IP-NFTs are required to strictly validate against a well defined JSON schema that’s flexible enough to cover many relevant use cases. Here’s a visual tool to investigate a valid IP-NFT’s metadata interactively. Note that the generic fields name, image and description are located on the document’s root level as required by ERC-1155, whereas the agreements and project_details structures are modeled as rich property definitions.
{
"schema_version": "0.0.1",
"name": "Our awesome test IP-NFT",
"description": "Lorem ipsum dolor sit amet, ...",
"image": "ar://7De6dRLDaMhMeC6Utm9bB9PRbcvKdi-rw_sDM8pJSMU",
"external_url": "https://ip-nft.com/1",
"properties": {
"type": "IP-NFT",
"agreements": [
{
"type": "License Agreement",
"url": "ar://4FG3GR8qCdLo923tVBC85NTYHaaAc3TvCsF3aZwum_o",
"mime_type": "application/pdf",
"content_hash": "bagaaiera7ftqs3jmnoph3zgq67bgjrszlqtxkk5ygadgjvnihukrqioipndq",
}
],
"project_details": {
"industry": "Pharmaceutical R&D",
"organization": "Newcastle University, UK",
"topic": "Aging",
"research_lead": {
"name": "Chuck Norris",
"email": "chuck@norris.com"
}
}
}
}Validate Metadata Correctness
To validate IP-NFT metatadata documents against that schema, you can use arbitrary JSON schema tools. Ajv is one of the most powerful ones in Javascript. We’re omitting the code to retrieve schema or documents for brevity’s sake but in a nutshell validation boils down to:
import Ajv from "ajv";
import addFormats from "ajv-formats";
(async () => {
const ipnftSchema = JSON.parse(ipnftSchemaJson);
const document = JSON.parse(ipnftMetadataJson);
const ajv = new Ajv();
addFormats(ajv);
const validateIpnft = ajv.compile(ipnftSchema);
const validationResult = validateIpnft(document);
})();Link to External Resources
IP-NFT metadata documents require you to refer to external resources, e.g. the image or agreements[].url fields. While you can choose to go with the well known https:// protocol, it’s advisable to use web3-native decentralized storage pointers like ar:// or ipfs:// instead. Clients are supposed to resolve them to their respective http gateway counterparts and most NFT related services and frontends can handle them. You don’t need to run an Arweave or IPFS node yourself - Ardrive or web3.storage are excellent helper services that get the job done and our official IP-NFT minting UI uses Bundlr to efficiently upload files to the Arweave network with near instant finalization.
Here’s a nodejs example on how to upload a JSON document using web3.storage (it’s simpler to do this within a browser context, though):
import dotenv from "dotenv";
import { Blob } from "node:buffer";
import { Web3Storage } from "web3.storage";
dotenv.config();
const w3sClient = new Web3Storage({ token: process.env.W3S_TOKEN });
(async () => {
const content = {
uploaded_at: new Date().toISOString(),
};
const binaryContent = new Blob([JSON.stringify(content)], {
type: "application/json",
});
const file = {
name: "filename.json",
stream: () => binaryContent.stream(),
};
//@ts-ignore
const cid = await w3sClient.put([file], {
name: "some.json",
wrapWithDirectory: false,
});
console.log(cid);
})();results in an IPFS CIDv1:
bafkreicrhuxfzrydht6tmd4kyy6pkbhspqthswg6xbiqlaztmf774ojxhqTo resolve the published content, you can request it from any public IPFS http gateway. You’ll experience the lowest latency when querying a gateway close to the node that you used for uploading; web3.storage offers https://w3s.link for that purpose. Requesting https://w3s.link/ipfs/bafkreicrhuxfzrydht6tmd4kyy6pkbhspqthswg6xbiqlaztmf774ojxhq yields
{"uploaded_at":"2023-01-02T22:45:17.788Z"}Decentralized Encryption and IP-NFT Token Gating
An IP-NFT’s most important metadata property are its agreements, another term for legal documents attached to it. These documents refer to the IP-NFT smart contract’s (“collection”) address and the IP-NFT’s token id. The agreements’ content might contain confidential information about the involved parties and hence should be encrypted before being uploaded. Decentralized and permissionless encryption is a non trivial requirement that we solve by relying on Lit Protocol.
Lit runs a network of nodes that derive signing and encryption keys by multiparty computation / threshold cryptography on trusted computing enclaves. The nodes themselves only know parts of the private key that effectively is fully assembled on the client side after all conditions for key retrieval have been met. Lit protocol allows gating any content behind access control conditions that are backed by blockchain state, therefore it’s disclosing decryption keys only to holders of an NFT or users that meet a certain condition on chain.
Lit’s documentation lays out the encryption process in detail. To instantiate a Lit SDK instance that’s capable of encrypting or decrypting content, it needs an EIP-4361 compatible signature that proves control over the current user’s account. Once authenticated we can request a new symmetric key to encrypt our content and ultimately ask the Lit network nodes to store its key shares along with an access control condition. That request yields an encrypted decryption key (😵💫) that has been created by the network nodes.
import LitJsSdk from '@lit-protocol/sdk-browser'
const litClient = new LitJsSdk.LitNodeClient()
await client.connect() //connects to Lit network nodes
const file: Blob | File = //some file
const { encryptedFile, symmetricKey } = await LitJsSdk.encryptFile({ file })
//you can reuse a Siwe / EIP-4361 compatible signed message here, see https://login.xyz/
const authSig = await LitJsSdk.checkAndSignAuthMessage({ chain: "ethereum" });
accessControlConditions = {
conditionType: 'evmBasic',
contractAddress: tokenContractAddress,
standardContractType: 'ERC1155',
chain: "ethereum",
method: 'balanceOf',
parameters: [':userAddress', tokenId],
returnValueTest: {
comparator: '>',
value: '0' // user owns more than 0 of this token id
}
}
const u8encryptedSymmetricKey = await litClient.saveEncryptionKey({
unifiedAccessControlConditions: accessControlConditions,
symmetricKey,
authSig,
chain,
permanent: false
})A user who wants to decrypt the content must again initialize the SDK using a signed message that proves control over their address. Next, they ask several network nodes to present their key shares of the encrypted key by presenting the access control conditions and the encrypted symmetric key to the network. If the network nodes find that the account matches the given conditions, each one yields its key share for the encrypted decryption key. With that, the SDK decrypts the key the content has initially been encrypted with.
const authSig = await LitJsSdk.checkAndSignAuthMessage({ chain: "ethereum" });
const symmetricKey = await litClient.getEncryptionKey({
unifiedAccessControlConditions: accessControlConditions,
toDecrypt: encryptedSymmetricKey,
chain: "ethereum",
authSig
})An IP-NFT metadata’s agreements item can store the encrypted symmetric key and its access control conditions inside its encryption field. Note that the IP-NFT JSON schema of access_control_conditions is externally defined by Lit protocol.
"agreements": [
{
"type": "License Agreement",
"url": "ar://4FG3GR8qCdLo923tVBC85NTYHaaAc3TvCsF3aZwum_o",
"mime_type": "application/pdf",
"content_hash": "bagaaiera7ftqs3jmnoph3zgq67bgjrszlqtxkk5ygadgjvnihukrqioipndq",
"encryption": {
"protocol": "lit",
"encrypted_sym_key": "fcbeaf3af31c7104d1d1f7099a6c6f6fda5803a4f7a0bef93256f3377450291872ad07bed3e9402cb47cc932c8f48219e56b84c06becd5ec0ee83ef2c0c93b932fb675c7932fa8df0ad164f17642b32415e382081577a403c19da2eff22c9083fa134ad1f370c2bec449adcdea790498637c7238b7d67cf2d69507a962656d3200000000000000205e4ad4e6323e06862babc934f740bc2e566d175a5da23bb4f1b35635e5cc3768cd040e8776307ea038484ff42033c18f",
"access_control_conditions": [
{
"conditionType": "evmBasic",
"contractAddress": "0xa1c301d77f701037f491c074e1bd9d4ac24cf5e5",
"standardContractType": "ERC1155",
"chain": "goerli",
"method": "balanceOf",
"parameters": [
":userAddress",
"6"
],
"returnValueTest": {
"comparator": ">",
"value": "0"
}
}
]
}
}
]Using Multisig Wallet Signers
Due to the high value nature of IP-NFTs you might feel tempted to use a multisig wallet for the minting process, maybe because you’d like to prove that the IP-NFT has been created by a dedicated group of individuals. This works fine for all contract function invocations but is not supported by Lit protocol. Multisig wallets (or contract wallets to be precise) cannot sign messages in the way it’s required to authenticate against Lit nodes because they’re not based on a private key. This might once be possible by utilizing EIP-1271 compatible wallet signatures but is not supported at the time of writing.
The recommended workaround is to denote a dedicated trusted member of the multisig that’s supposed to initially own the minted IP-NFT. This could be the researcher, a core contributor or maintainer of the project. The IP-NFT contract’s mintReservation function takes a recipient parameter (to) that defines the NFT’s initial owner. Note, that the account that invokes the mint function is required to hold a mint pass, not the receiver.
Granting Read Access to Third Parties
Another shortcoming related to Lit’s requirement of private key based authentication signatures is that multisig token holders cannot prove their address to the protocol. To allow multisig members to decrypt the accompanying agreement documents, the IP-NFT contract contains a grantReadAccess. It can be invoked by the current token holder (e.g. a multisig) to grant certain accounts (e.g. some of their members or potential buyers) read access to the underlying content for a limited amount of time. Its counterpart canRead yields a boolean whether the reader is currently allowed access. For the current owner of an IP-NFT this method always returns true.
To make read grants work inside Lit protocol, one can craft a custom contract access control condition that not only takes the current IP-NFT ownership into account but also lets users pass that currently are granted read access:
"encryption": {
"protocol": "lit",
"encrypted_sym_key": "...",
"access_control_conditions": [
{
"conditionType": "evmContract",
//the IP-NFT UUPS proxy contract address
"contractAddress": "0x36444254795ce6E748cf0317EEE4c4271325D92A",
"chain": "goerli",
"functionName": "canRead",
"functionParams": [
":userAddress",
"10"
],
"functionAbi": {
"name": "canRead",
"inputs": [
{
"internalType": "address",
"name": "reader",
"type": "address"
},
{
"internalType": "uint256",
"name": "tokenId",
"type": "uint256"
}
],
"outputs": [
{
"internalType": "bool",
"name": "",
"type": "bool"
}
],
"stateMutability": "view",
"type": "function"
},
"returnValueTest": {
"key": "",
"comparator": "=",
"value": "true"
}
}
]
}Proving Content Integrity
Since agreement documents are encrypted before being stored, each agreement item may contain a content_hash that downloaders can use to prove the legal documents’ content integrity after they’ve decrypted it. When using IPFS as storage layer this hash is not adding much value since the network’s content ids already provide an untamperable way of guaranteeing content integrity, however they’re not derived from the original content and hard to prove without an IPFS node at hand.
The content_hash field shall contain the sha-256 digest of the attachment’s binary content, encoded as a multihash compatible to CIDv1. This allows clients to decode the content hash and verify a document’s content without being aware of the hashing algorithm used. This is how it looks like in Typescript using the multiformats NPM package:
import { CID } from "multiformats/cid";
import * as json from "multiformats/codecs/json";
import { sha256 } from "multiformats/hashes/sha2";
const checksum = async (u8: Uint8Array) => {
//https://multiformats.io/multihash/
const digest = await sha256.digest(u8);
return CID.create(1, json.code, digest);
};
const verifyChecksum = async (
u8: Uint8Array,
_cid: string
): Promise<boolean> => {
const cid = CID.parse(_cid);
//https://github.com/multiformats/multicodec/blob/master/table.csv#L9
console.log("hash algo used: 0x%s", cid.multihash.code.toString(16));
const digest = await sha256.digest(u8);
return cid.multihash.bytes.every((el, i) => el === digest.bytes[i]);
};
(async () => {
const binaryContent = new TextEncoder().encode("This is the content");
const cid = await checksum(binaryContent);
const valid = await verifyChecksum(binaryContent, cid.toString());
console.log(cid, valid);
})();Putting it all together: The IP-NFT Minting Flow for Developers
To sum up, minting an IP-NFT technically requires the following steps:
- Get a Mintpass for the account that’s supposed to finally invoke the
mintReservationfunction. - invoke the IPNFT contract’s
reserve()function to reserve a token id. This will revert if the caller is not holding a valid Mintpass. Get the reserved token id by parsing the method’s event logs - upload an image to a (de)centralised network of your choice
- use the token id and the IPNFT contract’s address to create legal documents
- compute a checksum over the original documents
- optionally encrypt the documents with a Lit access control condition
- assemble a metadata structure containing the file pointers, access control conditions, encrypted symmetric key and checksum
- verify that this metadata structure is valid
- upload the metadata to a (de)centralised network of your choice
- invoke
mintReservationon the IPNFT contract with
address to: the recipient of the minted NFT (e.g. a Multisig wallet)uint256 reservationId: the token id you’ve reserveduint256 mintPassId: the Mintpass id that’s going to be redeemed during the mintstring memory tokenURI: the URI that resolves to the metadata
Conclusion
IP-NFTs are DeSci primitives that allow researchers, institutions and laboratories to prematurely mint the legal implications of their work as a tradable and verifiable asset. They deal as fundamental ownership anchors that can be used to refer and gate access to other kinds of protectable content, e.g. machine learning models, data streams or non public documents. Being built on well known standard interfaces, they can be traded or fractionalized using a vast range of protocols that already exist today.
As you have learnt here, the minting process of IP-NFTs is not a trivial task, particularly if they’re containing references to encrypted content. However, their metadata schema is designed to be flexible enough to cover many IP related use cases and the IP-NFT’s contract interface should be simple to interact with.
The IP-NFT contract is deployed as an upgradeable contract that’s maintained by the Molecule core team and we’re planning to add more exciting features to it in the near future. You can find all relevant sources on our official Github repo and runnable versions of the code samples depicted in this article in the accompanying samples repo.
