Architecture / Smart Contract Spec

Architecture / Smart Contract Spec

1. What This Spec IsCopy link

This document is the technical trust document for Yokefellow’s contract and event architecture. Its purpose is to describe the real stack underneath the platform in a way that advanced builders, auditors, technical partners, and serious operators can inspect. It is not the Whitepaper, not the Mechanics paper, and not the Developer Docs Hub. It does not argue for why Yokefellow matters. It explains how the current system is built underneath.

This spec should stay sober and structural. It should describe the contract map, which responsibilities live onchain, which responsibilities remain offchain, how the NFT stack is organized, how value movement works through the vault and settlement layer, how registry and factory relationships are enforced, what the indexer assumes, and where the main trust boundaries and failure points sit. That is the role this paper owns in the broader launch set.

2. System MapCopy link

At a high level, the current Yokefellow stack is built from a small number of core contract families plus an offchain indexing and permission layer.

The core onchain contracts are:

YES

BucketVaultV1

BucketSettlementV1

YFNftCollectionRegistry

YFNftCollectionFactory721

YFNftCollectionFactory1155

YFNftCollection721

YFNftCollection1155

Those contracts do not all solve the same problem. YES is the platform token. The vault is the bucket balance and custody layer. Settlement is the market, gasless-order, and bucket-transfer layer. The NFT registry and factories manage collection deployment and linkage. The collection contracts hold the actual NFT outputs. Together, they form the contract side of the platform.

Alongside that contract layer, Yokefellow also depends on an offchain platform layer. The database, API surface, SDK, and indexer are not replacements for the contracts. They are the coordination and readability layer around them. This includes route-level builder access, offering and request state, queue handling, activity mapping, ownership indexing, bucket-to-NFT control bindings, and permission refresh logic. The Mechanics paper already describes the principle here: onchain handles the durable, contract-backed layer; offchain coordinates readable surfaces, requests, queues, and operator-managed state.

3. Contract MapCopy link

3.1 YES

YES.sol is the platform token contract. It is an ERC-20 with permit support and access-controlled minting. It is not the whole platform. It is the contract that supports the platform’s economic layer. The current contract includes yearly emission logic, emission-year calculation, emission bounds, and a mint function gated by MINTER_ROLE. That means token issuance is deliberately controlled rather than open-ended. This aligns with the broader document set, which treats YES as the economic layer supporting activity across buckets and apps rather than as the whole identity of the product.

3.2 BucketVaultV1

BucketVaultV1.sol is the bucket custody and accounting contract. It holds bucket-scoped balances by token and tracks free and reserved balances. It is the contract where bucket-level deposits, withdrawals, reservations, unreservations, direct free-balance payments, refunds, and bucket-to-bucket transfers are actually enforced. The vault is also where bucket records are initialized and where bucket ownership and bucket operators are tracked onchain.

3.3 BucketSettlementV1

BucketSettlementV1.sol is the settlement and trading contract. It is built around signed order and fill intents, fee parameters, gasless posting and cancellation support, maker refund support, and a bucket-to-bucket transfer primitive. The contract does not hold bucket balances itself. It works against the vault, which remains the custody layer. Settlement is therefore the execution and market logic layer, not the balance ledger.

3.4 YFNftCollectionRegistry

YFNftCollectionRegistry.sol is the canonical registry for deployed collections. It records which collections exist, which standard they use, which owner they report, which bucket they are linked to, and which collection key they are grouped under. The registry is also where authorized factory relationships are enforced. Collections do not become part of the indexed NFT stack merely because they were deployed somewhere. The registry is the canonical record of recognized collections.

3.5 YFNftCollectionFactory721 and YFNftCollectionFactory1155

The factory contracts are the deployment layer for recognized collections. They deploy 721 or 1155 collection contracts and register them into the registry. They also support linked deployment paths that attach a collection to a bucket onchain id and a collection key at deployment time.

3.6 YFNftCollection721 and YFNftCollection1155

These are the actual NFT contracts used for output issuance. The 721 contract supports minting one token per issuance event, metadata controls, burn, max supply, minting lock, metadata lock, and transfer lock. The 1155 contract supports semi-fungible or batch-style token issuance, per-token supply tracking, burn and burn-batch, metadata controls, minting lock, metadata lock, and transfer lock. These are the collection contracts the player or participant ultimately receives outputs from.

4. Registry and Factory StructureCopy link

The current NFT architecture is registry-first, not discovery-by-factory-event alone. That matters because Yokefellow needs a canonical source of truth for recognized collections that can survive app changes, indexer rebuilds, and ownership sync. The registry tracks collection address, owner, deployer, standard, linked bucket onchain id, collection key, name, symbol, and deployment timestamp. It also supports collection-owner sync and indexed queries by owner, bucket, and key.

The registry is controlled by an owner and keeps an authorization list for factories. Only authorized factories can register collections through the intended path. That gives Yokefellow a clear recognition boundary: deployment through or registration into the registry is what makes a collection part of the canonical stack.

The two factory contracts exist to deploy collections of the appropriate standard and immediately register them into that registry. Each factory has a plain deploy path and a linked deploy path. The plain path creates a recognized collection. The linked path creates a recognized collection and attaches it to a bucket and collection key from the start. This is the current architecture’s answer to the earlier single-factory model. Collections are no longer discovered only because one legacy factory emitted one event. They are tracked through the registry as durable records.

This matters for indexing and technical trust. The indexer can rebuild NFT collection state from the registry even after resets or replays by reading allCollectionsLength, iterating allCollections, and reading each collection record. That architecture is more durable than assuming the app or indexer will always have the full deployment history in local memory.

5. Bucket Vault and SettlementCopy link

5.1 BucketVaultV1 as the custody layer

The vault is the base contract for bucket balances. It holds per-bucket, per-token free balances and reserved balances. Its responsibilities are intentionally narrow and strong:

initialize bucket records

track bucket ownership

track bucket operators

accept deposits

execute withdrawals

reserve and unreserve value

transfer free balances between buckets

allow operator-driven free-balance payments and refunds

settle bucket-side consequences of market or transfer activity

This is why the vault is the correct place for balance truth. It does not try to do price math or signature validation. The contract comments and code structure both reinforce that separation.

5.2 Bucket registration and ownership

The vault also serves as the onchain bucket registry layer for balance-bearing buckets. A bucket id is initialized onchain with an owner, and the contract tracks whether a bucket is registered, who owns it, which operators are allowed, and which bucket ids belong to which owner. This gives the contract layer a durable notion of bucket identity, bucket owner, and a narrow onchain operator authorization surface without pushing all bucket meaning into the frontend or database.

That onchain operator surface should still be read narrowly. The broader platform permission model is larger than the raw bucket-owner and bucket-operator facts stored in the vault. Yokefellow can still derive additional bucket-facing authority through indexed NFT ownership, active bindings, and offchain permission assignments above the contract layer. The vault establishes the hard ownership base. The platform may still interpret broader control relationships on top of that base.

5.3 Reservation model

The reservation model is important because settlement and market activity depend on it. Free balance is the portion of a bucket’s token balance not currently committed. Reserved balance is the portion spoken for by a pending action. This keeps the contract layer aligned with the platform’s larger accounting model and prevents the same funds from being used twice across market or transfer activity.

At the contract layer, those free and reserved balances are the main durable accounting states the vault enforces directly. That is the custody truth the rest of the platform has to respect.

5.4 Platform credit semantics above contract balances

The broader platform may still describe richer participation-facing balance semantics above that raw contract layer. Elsewhere in Yokefellow, value may be described as deposited, available, reserved, and spent in order to make funding posture, participation posture, and user-facing accounting easier to read. That broader language does not mean the vault stores four different balance types onchain. It means the platform interprets and presents contract-backed balance truth through a richer offchain participation model.

This is an important architecture boundary. The vault remains the custody source of truth. Readable credit semantics belong to the broader coordination layer that turns bucket balances into usable product surfaces. The platform can therefore speak in richer accounting language without pretending that every user-facing funding concept is a separate contract-level storage primitive.

5.5 Settlement as execution layer

The settlement contract sits above the vault. It handles posted orders, cancellations, fills, gasless posting and cancellation flows, maker refunds, fee parameters, and bucket-to-bucket transfer intent execution. It relies on EIP-712 typed data hashes and signature checking for order, fill, maker-refund, and bucket-transfer intent validation.

This separation is deliberate. Vault is the stateful custody layer. Settlement is the transactional execution layer. The two contracts are coupled, but they do different jobs.

5.6 Bucket-to-bucket transfer primitive

One especially important function in settlement is transferBetweenBuckets. This is the primitive for moving funds from one bucket context to another through a signed owner intent. In product terms, this supports the “account bucket to project bucket” style movement repeatedly described elsewhere in the system. Technically, it means Yokefellow has a native contract path for bucket-to-bucket deposit movement rather than requiring those flows to be represented as wallet exits and re-entries.

5.7 Fees and gasless execution

Settlement also owns fee parameters and gasless execution support. The current contract includes fee basis points, fee recipient, maximum gas refund in USDC, gasless post and cancel flows, skip events for soft-fail batch paths, and maker refund events. That means the architecture already anticipates relayed or operationally assisted market actions rather than assuming all flows are direct synchronous wallet interactions.

6. NFT Collection ModelCopy link

6.1 Collections

A collection is the contract-backed grouping of outputs. Technically, that means one deployed 721 or 1155 contract recorded in the registry. Conceptually, it means a grouped surface for related outputs that belong together under one bucket or one collection key. The vocabulary sheet already locks this term as the NFT grouping layer, and the Mechanics paper already places most of its detailed meaning here and in Architecture Spec.

6.2 Classes

Classes are not onchain contracts by themselves in the current architecture. They are platform-level output definitions that resolve into issuance against one of the deployed collection contracts. That means the collection contract is the onchain carrier, while the class is the offchain-defined output type the offering and issuance layers reason about. This is one of the most important architecture boundaries in the whole system. The chain does not need to know every class abstraction. The platform maps classes into issuance decisions against the registered collection layer.

6.3 721 model

The 721 contract is optimized for unique one-token issuance. It includes:

contract URI

base token URI

per-token URI override

max supply

minting lock

metadata lock

transfer lock

owner-only mint

burn support

This makes it suitable for unique outputs, ownership-signaling outputs, or individually meaningful bucket-linked results.

6.4 1155 model

The 1155 contract is optimized for token-id based quantities and batch issuance. It includes:

contract URI

base token URI

per-token URI override

per-token max supply

minting lock

metadata lock

transfer lock

owner-only mint

burn and burn-batch support

This makes it suitable for repeated class outputs, quantity-based issuance, craft inputs, and other multi-instance output surfaces.

6.5 Minting and ownership control

In both standards, minting is owner-only at the collection-contract level. That means whoever owns the collection contract controls issuance at the raw contract layer. That is the hard contract boundary underneath any broader issuance flow.

This matters because the platform may still coordinate request state, approval state, mint-job state, and readable issuance lifecycle offchain, but those layers do not replace the collection owner’s raw mint authority. They organize issuance. They do not override the contract’s ownership rule.

6.6 Issuance authority and execution posture

Collection ownership should therefore be read as the base issuance authority in the current architecture. In the intended operator-first posture, the operator of the bucket issuing the collection should normally own that collection and should therefore also be the party responsible for the signing and gas posture of mint execution.

That authority posture is narrower than the full offchain issuance flow. Yokefellow may still create request rows, approval rows, mint jobs, and readable status around that work, but the underlying contract execution boundary remains the collection owner. This keeps the architecture honest about who is actually issuing outputs at the contract layer. If the operator owns the collection, the operator is the issuer at the raw carrier layer even when Yokefellow coordinates the surrounding state and visibility.

6.7 Carrier-level controls versus platform-level controls

Carrier behavior should also be read across two levels.

At the collection-contract level, the 721 and 1155 carriers enforce owner-controlled minting plus collection-level minting, metadata, burn, and transfer controls. Those are the hard contract controls.

At the platform level, Yokefellow can still define class-level meaning, issuance posture, limits, and rights interpretation through offchain class definitions, offering configuration, bindings, metadata, and surrounding application logic. That means some of the finer-grained user-facing behavior of a right is shaped at the platform layer even when the hard enforcement boundary for mint authority or transfer locking sits at the collection-contract layer.

The practical rule is simple: collection contracts provide the hard carrier boundary, while class records and platform logic provide much of the more specific output meaning above that boundary.

7. Ownership and Control BindingsCopy link

This is one of the places where the Architecture Spec must stay exact about the onchain/offchain split.

Onchain, the system knows:

bucket ids and bucket owners in the vault

bucket operators in the vault

collection ownership in the collection contracts

collection registration and bucket/key linkage in the registry

Offchain, the system adds:

bucket-to-NFT control bindings

class-level bindings

token-level bindings

indexed NFT ownership

derived bucket permission assignments

operator-facing permission resolution

That means bindings are not one smart contract. They are a platform-level control layer built on top of contract truth. The contracts provide the durable ownership and recognized collection relationships. The platform then derives bucket-linked permission surfaces from those facts.

7.1 Permission derivation pipeline

The offchain control layer should be understood as a derivation pipeline rather than as one flat permission table. Recognized ownership facts are indexed from recognized collection contracts. Bindings then attach that recognized ownership to bucket-relevant control relationships. A permission-refresh layer derives bucket-facing authority from the combination of recognized ownership, active bindings, and the platform’s permission rules.

This is the architecture reason a held token does not automatically mean every possible power is active everywhere. The token ownership fact is one layer. The bucket binding is another. The derived permission assignment is another. Rights and authority become usable only when those layers are interpreted together in the specific surface that recognizes them.

This distinction also matters because main-app bucket bindings and broader app- or tool-level rights behavior are not the same thing. A bucket binding is the main-app bucket-layer connection. Broader capability, metadata, and code interpretation may still extend that right into other surfaces. The architecture should therefore name both layers clearly instead of implying that one binding record explains the entire rights model.

8. Events and Indexing AssumptionsCopy link

The architecture assumes that readable platform state is built from both direct contract events and direct onchain reads.

8.1 Vault events

The vault emits events for:

bucket initialization

bucket ownership changes

bucket operator changes

bucket registration

bucket-owner indexing

deposits

withdrawals

reserved and unreserved value

paid-from-free actions

free transfers

refunds from free balance

settled trade consequences

These events allow the indexer to build bucket activity and funding history without inventing contract state from scratch.

8.2 Settlement events

The settlement contract emits events for:

fee parameter changes

posted orders

cancellations

executed fills

skipped fills, posts, and cancellations

maker refund payments

bucket transfer execution

These events support market history, gasless execution visibility, and bucket transfer indexing.

8.3 Registry events

The registry emits events for:

factory authorization changes

collection registration

collection linkage

collection-owner sync

These events are critical because they let the indexer update collection records incrementally while still allowing full recovery from direct registry reads.

8.4 Collection events

The collection contracts emit mint, burn, metadata, supply, and transfer-related events. Ownership sync relies heavily on standard ERC transfer events plus direct owner or balance reads where necessary. This is how the platform maintains nft_ownership_index and then uses that as part of bucket permission derivation.

8.5 Indexer assumption

The core architecture assumption is that the indexer is not the source of truth, but it is the source of readability. The chain remains authoritative for balances, transfers, contract ownership, and registered collection facts. The platform’s indexer is responsible for replay, normalization, readable history, ownership indexing, and derived bucket-permission refresh. That is why event-model durability and replay safety matter so much in the architecture.

8.6 Queue-state assumption

The architecture should also be explicit that unresolved issuance work does not live in one generic queue. In the broader Yokefellow model, unresolved participation first appears as request-side state and later, if advanced, appears as mint-side execution work. The request queue and mint queue are therefore related but distinct parts of the architecture.

The request queue is the decision layer. It preserves real participation state while the system or operator decides whether that participation should move forward, be rejected, or remain pending. The mint queue is the execution layer. It preserves mint work that already exists and still needs to run, retry, or finish.

This distinction matters architecturally because approval, fulfillment, and mint execution are not identical stages. A request may be recognized and advanced without the final mint having happened yet. The platform’s queue model therefore belongs in the architecture as a real state boundary, not only as a UI or operator-surface detail.

9. Security BoundariesCopy link

The architecture has several clear trust and security boundaries.

The first boundary is between custody and execution. The vault holds balances and bucket identity. Settlement executes market and transfer logic against that custody layer. This keeps stateful balance truth separate from order and fill logic.

The second boundary is between recognized collections and arbitrary NFT contracts. The registry and factory authorization model determine which collections are part of the canonical Yokefellow stack. Not every random 721 or 1155 contract is treated as part of the platform.

The third boundary is between onchain ownership facts and offchain permission interpretation. Token ownership, bucket ownership, and registered collection linkage are contract facts. Bucket-linked control bindings and derived permission assignments are platform logic built on top of those facts.

The fourth boundary is between automatic and operator-managed outcomes. The contract layer can guarantee transfer, mint, burn, balance movement, and recognized collection structure. It does not guarantee every real-world fulfillment or bucket-side promise. That is a platform and operator boundary, not a contract boundary.

The fifth boundary is deploy authority. The current stack is owner- and role-controlled. Vault admin, settlement fee authority, registry owner, factory owner, and token minter role all matter. This is not a permissionless, governance-minimized launch design. It is a controlled deployment architecture.

10. Upgrade and Deploy AssumptionsCopy link

The current architecture is deploy-and-wire, not proxy-upgrade based. The deployment scripts create the contracts directly, then wire their relationships by granting the settlement operator role on the vault, setting settlement fee parameters, deploying the registry and both factories, and authorizing the factories in the registry. The deployment artifacts then write the canonical addresses into stack.json and nft-stack.json.

That means upgrades in the current architecture should be understood as redeploy-and-migrate events rather than in-place proxy implementation swaps. If vault, settlement, registry, or factory behavior changes materially, the deployment story is a new contract stack plus environment updates, indexer alignment, and migration handling where needed.

This matters for technical trust because it is a simpler and more inspectable posture than a hidden proxy layer, but it also means operational migration discipline matters more when the stack changes.

11. Failure ModesCopy link

The main contract-level and architecture-level failure modes are straightforward.

A contract bug in the vault can affect bucket custody, reservation logic, or operator-driven value movement.

A contract bug in settlement can affect market posting, cancellation, fill execution, fee charging, gasless relays, or bucket-to-bucket transfer flows.

A contract bug in the registry or factories can affect recognized collection deployment, linkage, or collection ownership tracking.

A collection-contract bug can affect minting, burn flows, transfer locking, or metadata management for one collection family.

A queue-state or issuance-lifecycle bug can also leave request state, mint-job state, or readable issuance progress inconsistent even when the underlying ownership and contract relationships remain intact.

An indexer failure can make readable platform state stale, incomplete, or delayed even while the chain remains authoritative.

An ownership-sync failure can leave bucket-linked permission assignments stale relative to actual token ownership.

A binding or permission-derivation bug can cause the platform to interpret a real onchain holding incorrectly at the application level even though the token ownership itself is still correct onchain.

An environment or deployment mismatch can point the app, ops layer, or indexer at the wrong contracts or partial stack.

These are the kinds of failure the Architecture Spec should name plainly. Broader user-facing risk language belongs later in Risk Disclosures, not here.

12. Verification and MonitoringCopy link

The architecture supports several forms of verification.

Contracts can be verified by source and deployment artifact against the published addresses for the active chain.

Deployment artifacts in the repo show the intended stack composition for a network, including YES, vault, settlement, registry, and both NFT factories.

Registry state can be verified by direct contract reads for all-collection enumeration and per-collection record inspection.

Vault state can be verified by direct reads for bucket records, balances, owners, and operators.

Settlement activity can be verified through emitted order, fill, cancel, refund, and bucket-transfer events.

Collection ownership can be verified directly on the collection contracts.

The platform’s monitoring layer should therefore focus on:

• indexer freshness

• replay safety

• ownership-sync freshness

• registry backfill success

• contract address correctness in environment

• event ingestion health

• request-queue health

• mint-queue health

• permission-refresh health

This paper should stop there. Operational trust posture, outage handling, and what end users should trust live in the Security, Trust, and Status paper, not in the Architecture Spec.

13. Closing FrameCopy link

The current Yokefellow architecture is a layered system, not one monolithic contract. YES supports the economic layer. BucketVaultV1 is the custody and bucket-balance layer. BucketSettlementV1 is the execution and market layer. The registry and factories define the recognized NFT deployment layer. The collection contracts hold the actual output surface. The indexer, ownership sync, and permission-refresh layers turn that contract structure into a usable platform.

That is the right way to understand the stack. It is not only “the NFT contracts,” not only “the market,” and not only “the app backend.” It is a designed architecture with clear boundaries between custody, execution, collection recognition, issuance, indexing, and permission interpretation. That is what this paper is supposed to make inspectable.