Yokefellow - Builder Docs
Example App Spec
Snake Test as a concrete bucket-linked reference app built on Yokefellow rails.
Yokefellow Developer Docs Hub
Example App Spec
Snake Test
Reference implementation for a bucket-linked game surface built on Yokefellow's real rails.
At a glance
| Purpose | Show one believable Yokefellow app end to end, from first read through funding, participation, NFT issuance, queue state, and lifecycle confirmation. |
|---|---|
| What it proves | That a real game surface can sit on top of buckets, offerings, account credit, NFTs, request rows, event matching, minting, and queue handling without inventing a separate backend model. |
| Key paths | Instant buy, random loot box, request flow, earned event flow, crafted upgrade flow, deposit, withdraw, wallet entitlements, and queued mint work. |
| Why it matters | It turns the other builder docs into one concrete app shape that technical readers can picture and product teams can copy. |
1. What This Spec Is
This document is the reference implementation document inside the Developer Docs Hub. Its job is to show one believable app built on the real Yokefellow surface from first read through participation, NFT issuance, wallet state, funding flows, queue handling, and lifecycle confirmation. It is not the Quickstart, not the SDK Guide, not the API Reference, and not the Integration Playbook. It is the place where those documents become concrete in one app.
The goal is simple: make it obvious that a Yokefellow app is not a separate system with a few Yokefellow hooks attached. It is a surface built on top of the same shared stack: accounts, buckets, offerings, NFTs, issuance, wallet-aware state, account credit, transaction lifecycle, queue work, and bucket-linked control.
2. Why Snake Test Is the Right Reference App
Snake Test is the right example because it proves more than one part of the platform at once. It is not only a game interface. It is a bucket-linked app surface that uses Yokefellow's existing rails instead of inventing a separate app economy, reward model, request system, or issuance model.
That matters because Yokefellow is not supposed to become a pile of isolated apps. The thesis is that different user-facing experiences can be built on the same primitives. Snake Test proves that thesis through something concrete: a playable app that still runs on bucket context, offering paths, funding state, wallet entitlements, queue surfaces, and NFT outputs from the main engine.
3. The Current Proof Surface
Snake Test today should be described as a controlled proof app rather than a vague future concept. In the repo, it already proves a real bucket-linked game surface with a readable header, wallet connection state, funding panel, instant offerings, request offerings, earned offerings, craft offerings, owned-state panels, queue panels, pending-request panels, and game-event submission.
That distinction matters. The spec should not read like Snake Test merely could support these things someday. It should read like Snake Test is the reference surface where those rails are already being exercised together.
4. Core Yokefellow Objects Used by the App
A bucket is the core participation surface for the app. It holds the game's public context, related offerings, funding state, and bucket-linked outputs. That matches Yokefellow's system definition of the bucket as a programmable funding and participation surface rather than just a page or wallet.
Offerings are the structured participation paths inside that bucket. In Snake Test they are not generic store listings. They are the controlled paths through which a player buys, opens, requests, earns, or crafts outputs.
NFTs are the concrete output layer the app uses. The player is not only receiving rights in abstract language. The player is receiving NFT-backed outputs from collections and classes configured through Yokefellow's issuance model.
YES is the participation and funding currency used by the app. Deposits, pricing, debits, and participation happen on the same YES layer used across Yokefellow rather than through an isolated game currency.
Wallet and entitlement state are how the app knows what the player currently holds, what is pending, and what has already resolved. Queue and request state matter because not every outcome is instant, and Snake Test should preserve that truth instead of hiding it.
Real screen model
The cleanest way to understand Snake Test is to name the visible app surfaces and what each one proves.
| Surface | What it shows | What it proves |
|---|---|---|
| Bucket and header | Which bucket the game belongs to and the current public participation context. | The app still starts from the bucket as the main anchor. |
| Wallet and funding | Connected wallet state plus account-credit balances such as available, withdrawable, deposited, spent, and reserved YES. | Funding is part of the product surface, not a hidden backend concern. |
| Instant offerings | Fixed purchases and random loot-box openings through the real buy path. | A game can use standard offering rails for direct participation. |
| Request offerings | Request-mode paths that create visible request rows and may reserve payment before later queue handling. | Not every participation path resolves immediately. |
| Earned offerings | Gameplay-linked paths unlocked through submitted events such as run_completed. | App-triggered outcomes can still stay on Yokefellow rails. |
| Craft offerings | Upgrade paths driven by offering inputRules, including hold and burn behavior. | Complex game logic can still run through the same offering and NFT model. |
| Owned, pending, and queued state | Owned outputs, pending requests, queued jobs, and reveal state. | Resolved, pending, and operator-processed outcomes stay visibly separate. |
5. Real Participation Paths in the Repo
Snake Test should explicitly document the participation paths the repo already proves, because that is what makes this spec stronger than a generic example app narrative.
5.1 Fixed purchase outputs
The app includes direct purchase offerings that use the real buy path. Some are straightforward fixed-output purchases where the player buys a specific snake class. This is the clearest example of offering-to-class resolution and immediate NFT-backed output delivery.
5.2 Random loot-box outputs
The app also includes random-output offerings that behave like loot boxes without leaving the offering model. The player is still entering a Yokefellow offering. The difference is that the offering resolves against a weighted output set rather than one fixed class. The reveal is productized as a game moment, but the underlying resolution still belongs to the bucket offering surface.
5.3 Earned gameplay outcomes
Snake Test also proves event-driven earned logic. When a run completes, the app can submit a structured offering event instead of inventing a separate game reward backend. That event can match an earned offering, create request state, auto-fulfill into mint work, or resolve through the configured selection and fulfillment rules.
5.4 Request-based participation
The app includes request-mode offerings that create visible request rows first. These are not described as broken or delayed purchases. They are honest request paths. The player enters the path now, sees pending state now, and later resolution happens through the queue and operator-aware surfaces.
5.5 Crafted outputs
Craft is the most important missing corrective area. In Snake Test, crafting is not just another buy button with different copy. It is a real offering path that checks configured inputRules, validates what the wallet already holds, applies burn or hold logic by rule, and then resolves into a crafted output.
A good concrete product example is a rainbow-style upgrade path built from previously acquired snake colors. The important point is not the cosmetic theme by itself. The important point is that the upgrade still uses Yokefellow's offering, NFT, and issuance model instead of a separate game-only crafting system.
6. The Craft Path in Detail
The spec should state the craft path plainly. Snake Test uses the real /craft route. The offering carries JSON inputRules. Those rules can require NFTs to be burned or merely held. The server validates those rules against the player's actual holdings before the craft can proceed.
If a burnable rule requires approval, the app surfaces that honestly instead of failing silently. The player may need to approve the relevant collection for the operator wallet before a burn can execute. Once the requirements are satisfied, the system records the craft request, consumes the configured inputs where required, creates the mint record, and mints the crafted output.
That is exactly the kind of behavior this spec should highlight because it shows Yokefellow can support game-like upgrade mechanics without abandoning its shared primitives.
| Craft rule. Craft behavior should be described as offering-driven, not game-hardcoded. The important recipe lives in the offering inputRules and the NFT holdings the wallet actually has. That keeps craft logic on Yokefellow's rails and makes the game surface a presenter of real platform state rather than a separate rules engine. |
|---|
7. Main User Journeys
The main user journeys should be written as real flows rather than vague examples.
7.1 First load
The app reads a live bucket first. Before the player takes any action, the app already knows which Yokefellow surface it is presenting.
7.2 Connect wallet and load player state
Once a wallet is present, the app re-reads bucket state with wallet context and loads wallet entitlements, request history, and queue-related state. The product changes from public view to player-specific view without changing systems underneath.
7.3 Deposit YES into account credit
The player prepares a deposit, performs the wallet-side transaction, checks status, and finalizes where required. The app should show available and withdrawable account credit afterward instead of only flashing a success message.
7.4 Buy a fixed output
The player chooses a direct-buy offering and receives the resulting NFT-backed output when the flow resolves. The owned-state surface should then confirm the result.
7.5 Open a loot box
The player enters a random-output buy path and receives one class from the configured weighted set. The reveal can feel playful, but it should still be described as a structured offering resolution path.
7.6 Finish a run and submit an earned event
The player finishes a gameplay run, the app submits the event, and the resulting earned-path state becomes visible through request, queue, or entitlement surfaces depending on the configured offering.
7.7 Enter a request path
The player enters a request-mode offering and sees explicit pending workflow state until it is approved, rejected, queued, or fulfilled later.
7.8 Craft an upgraded output
The player uses previously acquired NFT-backed inputs to enter the craft path, satisfies hold or burn requirements, and receives the crafted result when the route resolves.
7.9 Run the queue and confirm outstanding work
Where mint work is still queued, the operator-aware surface can inspect it, run queued jobs, and refresh the result. This keeps delayed issuance inside the same app story rather than forcing users into a separate admin mental model.
8. Funding and Lifecycle Behavior
Snake Test should not describe funding as one vague wallet balance. In the repo, the funding surface is an account-credit surface inside the bucket. That means the player can see available, withdrawable, deposited, spent, and reserved posture instead of one flattened number.
Deposit and withdraw are also not the same lifecycle. Deposit prepares approval and transaction steps, then moves through status and finalization. Withdraw prepares a signable message, submits the signed request, and then polls transaction status. The app is stronger when it keeps that distinction visible.
9. Wallet State, Request State, and Queue State
Snake Test should show three different categories of state clearly: what the player already owns, what is still pending, and what still needs queue or mint processing. That grouped presentation is one of the best practical demonstrations of the Yokefellow model.
Owned state should come from real wallet-linked holdings and minted outputs. Pending state should include unresolved request rows. Queue state should include mint jobs and queued colors that still need execution or confirmation. Keeping those lanes separate prevents the app from pretending every action is resolved the moment the first call returns.
10. Data and Integration Pattern
The app should still follow the same broad integration structure established by the rest of the builder docs. Start from the bucket catalog because the bucket is the primary app anchor. Then load funding state where funding matters, wallet entitlements where owned or pending output state matters, request history where request-based participation exists, and queue state where issuance is not instant.
On the write side, Snake Test proves a believable mix of actions: deposit, withdraw, direct buy, random buy, request creation, craft, earned-event submission, queue execution, transaction status checks, and finalization where required. That is what makes it a real reference app rather than a thin demo.
11. How Rights Fit Without Erasing NFTs
Rights still matter in this example app, but they should be described in the right relationship to the NFT layer. A right is the meaning or utility the player receives. The NFT is often the concrete output or carrier of that meaning. The bucket gives that output context. The offering defines the path through which it was received.
That keeps the Rights paper intact while preventing the Example App Spec from drifting into a vague abstraction that hides the actual collections, classes, minting, burns, holdings, and queue work the player is interacting with.
12. What This App Proves About Yokefellow
First, a Yokefellow app is built on the same underlying platform surface, not beside it. Snake Test still depends on buckets, offerings, account credit, NFTs, request state, queue work, and lifecycle state from the main engine.
Second, NFTs are not optional decoration. They are part of the real output and participation structure of the app through collections, classes, issuance, and crafted transformation paths.
Third, YES is not abstract token branding. It is the shared economic layer supporting participation inside the app, including direct buys and bucket account credit.
Fourth, pending, queued, reviewed, and finalized states are part of the product experience, not just backend details. Snake Test is stronger because it keeps those states visible.
Fifth, the same Yokefellow stack can support a game surface without inventing a separate participation system. That is the engine case this example app exists to make concrete.
13. Acceptance Standard
A finished Example App Spec should let a builder understand what the app is, which Yokefellow primitives it uses, how bucket context, offerings, NFTs, YES, account credit, wallet state, request state, queue state, and lifecycle state fit together, what the main user journeys are, and what this app proves about the wider platform.
Most importantly, it should leave the reader with one unmistakable conclusion: Snake Test is not an isolated mini-game. It is a bucket-linked Yokefellow app surface proving that direct buys, loot boxes, earned events, request rows, queue work, and crafted NFT upgrades can all live on the same shared rails.