​
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.

An example of a Patch is a contract that lets users mint a 1-5 star rating for any NFT. Those ratings are stored in Patch tokens which are soulbound to the NFT being rated. Another example of a Patch is an attestation service that stores user context in a Patch token soulbound to the user’s address.

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.

An example of a Fragment is a sword NFT that can be equipped to a character. The sword token contains all of the data related to the sword, and if the character NFT it’s assigned to is sold by the owner, the sword NFT is transfered along with it.

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.

An example of an Assignee is the character NFT from the example above. A character could have a certain number of equipment slots that each hold an equipment Fragment, and those slots can have specific rules for what type of equipment is allowed in each slot.

​
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.

Scopes currently cost nothing to claim and are created on a first-come-first-serve basis.

​
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?

1

Scope creation

Claim a Scope by calling the protocol’s claimScope() function with your desired Scope name.

You can defer this step until contract deployment where you can easily do it with a single line of code in your deploy script.
2

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..

When using our PDK, you’ll model your schemas in simple JSON and our codegen will take care of the rest.
3

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.

If you prefer to roll your own contracts, import the requisite Patchwork interfaces and adhere to the APIs outlined in our Contracts Reference material.
4

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.


Quickstart

Quick guide to get PDK installed and start writing your app.

Deploy your first app

Go from zero to sixty in 5 minutes with a simple app.

IntroductionQuickstart