Fragment
is a contract that can be assigned to an Assignee
contract. The assignment and associated behaviors can be configured in a number of ways. Fragments assignments are referenced using the Patchwork-primitive type LiteRef
.
Fragment Types
Type | Description |
---|---|
SingleAssignable | May be assigned to only one assignee at a time |
MultiAssignable | May be assigned to multiple assignees simultaneously |
Ownership Models
SingleAssignable:
By default, aSingleAssignable
fragment will exhibit the following behavior:
- Unassigned = Owned by the Fragment’s token holder
- Assigned = Owned by the Assignee
MultiAssignable:
AMultiAssignable
can be assigned to many different assignees. They do not change ownership based on behavior and have a different API to reflect their assignment model.
Example:
An emoji library is created as MultiAssignable. A “happy” emoji is assigned to thousands of different assignees. The “happy” emoji is always owned by the original content creator.
Assignment Rules
LiteRefs
ALiteRef
is a 64 bit value with a layout of:
- Upper 8 bits = Reference Address ID
- Lower 58 bits = Reference Token ID
PatchworkLiteRef
contract. The Reference Address ID is determined by a call to registerReferenceAddress(address addr)
on the Assignee as described in the workflow below. The token ID is the token ID of the fragment.
LiteRefs have a limit of 255 registered addresses. It is not recommended to allow users to register addresses as this limit is easily reached in an unmanaged design.
Fragments must never have more than a 56 bit value of a TokenID in order to work as a LiteRef. This limits each Fragment to minting 72 quadrillion tokens if starting at 0. This large limit works for most applications, specifically if applications use incremental numbering of token IDs. Randomized token IDs must stay within the 56 bit space or errors will occur.
Workflow
Before assigning a fragment to an assignee, the fragment must be registered with the assignee by callingregisterReferenceAddress(fragmentAddress)
Once registered, assignments should always be performed through PatchworkProtocol
. The protocol enforces data integrity between contracts and also tracks assignments that will be visible in the patchwork explorer.
Assignment functions:
Metadata Modeling
Patchwork721s become LiteRef assignees via fields of typeliteref
added to the metadata schema.
LiteRefs may be single values, static or dynamic arrays.
Static arrays are most useful when a contract needs to inspect and react to the entire composition of fragments.
Dynamic arrays are most useful when a large, unknown number of assignments will be made and there is no requirement for the contract to read all of the values in a single transaction.
Cross-scope permissions
When a Fragment and Assignee are in 2 different scopes, the following rules apply:- The fragment must allow the assignment via the call to
allowAssignment()
- The fragment must be whitelisted in the fragment’s scope if enabled for the scope
- The fragment must not be locked
- The target (assignee) must be whitelisted in the target’s scope if enabled for the scope
- The target (assignee) must have the fragment registered for it