Patchwork 101
A 10 minute primer to help you understand how Patchwork works at a high level
What is Patchwork and what does it do?
Patchwork is an Ethereum protocol and set of accompanying standards & tools to help you build apps backed by rich onchain data. Patchwork data is mutable, transferable, interactable by smart contracts, and can be expressed through a variety of different ownership models. Patchwork lets you permissionlessly affix / “soulbind” your datasets to any onchain entity, or build them as standalone properties.
How does it work?
Patchwork stores your app data entirely onchain in data containers that ultimately mimic a database. Patchwork data containers are Patchwork721 contracts & tokens, which are ERC721s that inherit special Patchwork interfaces for handling efficient data storage and protocol interaction.
The schematic blueprints (columns) for the data live in the Patchwork721 contract, and the datasets themselves live in the minted NFTs within the contract, with each token acting as a row and the token’s ID acting as a primary key. Schemas and datasets have full data availability in the EVM and are queryable by any smart contract.
All of the orchestration for your data’s lifecycle is handled by the protocol, working in tandem with your scope permissions, contract logic, and end-user agency to ensure absolute integrity of your data.
Patchwork721 and its extensions
The Patchwork721 standard is a flavor of ERC721 with added features centered around the protocol and data storage. It uses IPatchworkMetadata
interfaces to intelligently structure-pack your data, resulting in a hyper-optimized and storage-efficient EVM footprint, and significant gas savings compared to using Solidity structs.
There are three primary macro extension types for the Patchwork721 standard: Patch, Fragment, and Assignee (aka LiteRef). These extensions are not exclusive and can be used together in a single contract (with some edge-case limitations) for advanced use cases. For example, a Patch can also be an Assignee.
Patchwork721 without extensions
By itself, Patchwork721 offers great utility for new projects planning to use plain ERC721. Because they’re an extension of ERC721 they have all the standard functionality and utility of a regular NFT, while offering a higher degree of data-richness and data-availability in the EVM.
Patchwork721 Patch
Patches are Patchwork721s that are permanently & permissionlessly affixed (ie. soulbound
) to a target onchain entity (can be a contract address, EOA, non-fungible token, etc.). Patches allow anyone to add context to and build on top of existing projects.
Patchwork721 Fragment
An important aspect of Patchwork’s rich utility comes from the use of discrete data entities called Fragments. Fragments are individual blocks of data encapsulated in a separate Patchwork721 token. They can be assigned to (and unassigned from) a parent Patchwork721, and can be bought, sold, and traded by users just like any regular NFT. While a Fragment is assigned, ownership changes made to its parent cascade to the Fragment and its siblings atomically.
Patchwork721 Assignee
Assignee contracts inherit the ability to hold and own Fragments. They contain a special storage scheme to efficiently hold references to those Fragments, called LiteRefs
. As mentioned above, when an Assignee is transfered, it carries along its full tree of assigned Fragments.
What are Scopes?
Scopes are developer-reserved namespaces in the Patchwork ecosystem that ➊ contain application rules and permissions for your app, ➋ connect your contracts to protocol-level utility, and ➌ accrue fees paid to your contracts’ payable functions. Any protocol-capable contract you deploy will be organized into the Scope you claimed for your app.
What’s this PDK thing?
Our PDK is a low-code CLI tool that takes a simple JSON file documenting your contract schema and spits out an almost-ready-to-deploy Solidity contract. Because the Patchwork metadata standard uses some complex structure packing to be as storage-efficient as possible, we recommend using our PDK to bootstrap contract creation. We take care of 95% of the contract generation work for you so you can focus more on bringing your app to market and less on writing esoteric packing and unpacking logic, writing getters and setters for your data, figuring out the right interfaces for a specific implmentation, etc..
What’s the development process?
Scope creation
Claim a Scope by calling the protocol’s claimScope()
function with your desired Scope name.
Data modeling
Document your fields and their corresponding types that your data will adhere to. We currently have 20 different field types you can use in your schemas, as well as support for fixed-length and dynamic arrays, Fragment references, etc..
Contract generation
Use our PDK to quickly and easily generate the brunt of your contracts. It ingests a JSON file that documents your contract details and desired data fields and spits out lovely Solidity. Add in any additional business logic you need enforced at the contract level, then you’re ready to deploy.
Data orchestration
Once your contracts have been deployed and granted Scope permissions, your app is Patchwork-ready and is all set to create and handle data.
Your actual data lifecycle is entirely dependent on your use case and contract logic, but at a macro level the typical end result is the same. A top-level Patchwork721 contract outlines your database columns, and each token minted in those contracts acts as a database row. Fragments can be used to encapsulate one or more of each row’s field data as a discrete Patchwork-flavored ERC721 token; those Fragments can be traded, moved to around to different tokens, etc..
All of the orchestration for your data’s lifecycle is handled by the protocol, working in tandem with your scope permissions, contract logic, and end-user agency to ensure absolute integrity of your data.
What about indexing?
The protocol emits context-rich events for the full spectrum of Patchwork interactions, making it trivially simple to index, use with Syndicate APIs, or react to directly using Typescript libraries. Check out the events documentation.
How do I get started?
The best way to dive into Patchwork is to scan through the information in the Working with Patchwork section of the docs, check out the Quickstart guide, and get your feet wet with our simple app tutorial on the Deploying your first app page. We’ll walk you through the steps of installing PDK, writing your first schema, deploying your contract, and creating your first set of onchain data.