Yokefellow - Builder Docs
Integration Playbook
Implementation guidance for structuring real apps around buckets, offerings, wallet state, funding flows, and lifecycle state.
1. What This Playbook Is
The Integration Playbook is the practical guide for turning Yokefellowâs developer surface into a real product surface. Use it when your team already understands the basic SDK or API shape and now needs to decide how buckets, offerings, outputs, wallet state, funding flows, and lifecycle state should fit together inside an app or partner integration. This document is about product wiring. It is not the place to repeat first-run setup, endpoint lookup tables, or full-system philosophy. Those jobs already belong to the Quickstart, API Reference, Example App Spec, and broader launch documents.
This document sits in the middle of the Developer Docs Hub for a reason. The Quickstart proves that your environment and lifecycle handling work at least once. The SDK Guide explains the packaged client and the major read and write families. The API Reference explains the direct route surface. The Example App Spec shows one full reference integration in use. The Playbook begins after that point, when the builderâs question changes from âhow do I call thisâ to âhow should this app actually be structured around Yokefellowâs primitives.â
One practical boundary should stay clear from the start: public route reachability, authenticated integration recognition, wallet context, and wallet signing are related, but they are not the same proof. A builder who can read a public bucket has not automatically proved app auth, and a builder who can prepare a lifecycle flow has not automatically proved the same thing either. Those layers should stay separate before the product is wired above them.
The Playbook should therefore be read as implementation guidance for real product surfaces. A good integration is not only one that can call the API successfully. It is one that chooses the right primitive as its anchor, keeps lifecycle state visible, refreshes the right surfaces after writes, and does not hide the difference between pending, reviewable, and resolved states. That is the level this document is written for.
2. Start from the Primitive Your App Is Built Around
The cleanest way to structure a Yokefellow integration is to begin with the primitive the app is actually built around. That rule already exists in the SDK Guide, and it should become the organizing principle of the Playbook. A builder should not start by scattering route calls across the app and hoping the product shape emerges later. The better approach is to decide what the app is fundamentally centered on, then let that choice determine which reads, writes, and lifecycle state matter most.
These anchors are not meant to act like isolated silos. A real app may mix bucket, offering, wallet, and funding surfaces. The practical rule is still to choose which one is primary, then treat the others as supporting surfaces around it.
If the app is bucket-centered, start with bucket reads and treat the bucket as the main participation surface. In the current surface, that usually means using the bucket catalog as the first anchor, then layering in funding state, request history, and wallet-aware views as needed. This pattern fits apps where the user arrives at one bucket and needs to understand what the bucket exposes, what they can do there, and what has changed after they act. Quickstart already frames the bucket as the best first anchor because it gives the integration a live participation surface to work against.
If the app is offering-centered, start with offering writes and the reads that confirm what those writes became. In the current surface, that means request-based paths should center on offering-request creation and request-history confirmation, while direct participation paths should center on buy or craft actions and the reads that show the resulting state. The key idea is that offerings are not generic storefront objects. They are structured participation paths, and the app should be built to reflect that. The Mechanics and Rights docs already lock this framing: an offering is the structured way a bucket makes participation available, and it is not automatically a sale, a mint, or a promise. The offering is the path, not the whole meaning of the result.
If the app is user-state-centered, start with wallet entitlements, bucket reads with wallet context, and request or lifecycle reads where pending state matters. This fits apps that need to answer questions like what this wallet currently holds, what is still pending, what rights-related outputs are already resolved, and what the user can do next. The SDK Guide already treats wallet entitlements as the right surface when the app is centered on what one wallet has or can do, and it explicitly distinguishes wallet context from request auth.
If the app is funding-centered, start with funding preparation, wallet-side execution, transaction status, and finalization flows rather than treating funding as a side effect of some other surface. Deposit, withdraw, and transfer-between-buckets are not just background mechanics. In apps built around moving YES into, out of, or between Yokefellow surfaces, those lifecycle flows are the product. The Playbook should therefore tell builders to design the UI around preparation, chain-side execution, status, finalization where required, and post-action refresh, not around a fake instant-success model.
This is the core Playbook rule: decide what the app is built around first, then let that choice determine which Yokefellow surfaces are primary and which are supporting. That keeps the integration aligned with the platformâs primitives instead of turning it into a pile of unrelated calls.
3. Bucket-Centered Integration Pattern
A bucket-centered app should treat the bucket as the main participation surface, not as a thin wrapper around several unrelated objects. In practice, that means the app should begin from one broad bucket read, render the participation surface from that anchor, and only then pull in narrower supporting state where the feature needs it. In the current surface, the bucket catalog is usually the best starting point because it gives the app one live object to anchor to rather than forcing the builder to assemble the first screen from scattered calls. Quickstart already uses the bucket catalog as the clearest first real read for that reason, and the API Reference treats it as a composed bucket-centered object rather than a narrow detail lookup.
The first job of a bucket-centered integration is to answer four product questions cleanly. What is this bucket. What does it currently expose. What can this participant do here. What changed after the last action. If the app cannot answer those four questions from one coherent bucket-centered view, the integration is probably too fragmented. That is why bucket catalog and bucket funding should be treated as product surfaces rather than as low-level data sources. They are the builderâs main tools for keeping the app centered on the bucket itself.
A good bucket-centered flow usually starts with a non-wallet bucket view, then layers wallet-aware state when the user connects. The non-wallet view tells the user what the bucket is offering in general. The wallet-aware view tells the user what changes for them specifically. In the current surface, this is already supported directly by passing wallet context into bucket reads rather than inventing a second product model for connected users. That is the cleaner pattern because the app stays centered on the same bucket while the participant-specific state becomes more precise.
A bucket-centered app should also refresh bucket state after participation writes instead of assuming the write response alone is enough to keep the UI honest. If a user creates an offering request, buys an offering, submits a craft path, or completes a funding step, the app should re-read the bucket-centered surface that actually matters to that feature. In some cases that will be bucket catalog. In others it may be bucket funding or request state alongside the bucket view. Quickstart already makes the broader point here: do not stop at âthe call returned.â Confirm the resulting state through the surface your app is supposed to support. The Playbook should turn that into a bucket integration rule: after a bucket-scoped action, refresh the bucket-scoped surface that carries the user-visible result.
Finally, a bucket-centered app should not try to flatten every bucket into the same visual product. The bucket is the core primitive, but the product surface still depends on what the bucket is for. Some bucket-centered apps will emphasize offerings. Some will emphasize rights-related state. Some will emphasize funding. Some will emphasize operator-managed or queued outcomes. The integration pattern should stay stable even when the product emphasis changes: start with the bucket, keep the bucket as the anchor, and layer the rest of the state around it in service of that one participation surface rather than forcing every bucket into one generic screen model.
4. Offering Integration Pattern
An offering-centered integration should treat offerings as participation paths, not as generic items. That distinction matters because Yokefellow offerings are broader than sales objects. An offering can define a purchase path, an earned path, a request path, an application path, or a grant path, and the app should be built to reflect that difference rather than flattening everything into a simple buy button. The Rights and Mechanics documents are already explicit here: an offering is the structured way a bucket makes participation available, and it is not automatically a sale, a mint, or a promise. It is the path a user enters, not the whole meaning of the right or output that may later result from that path.
The first job of an offering integration is to make the path legible before the user acts. The app should show what kind of participation path the offering is, what the user is trying to do, and what kind of result the path may lead to. A request path should not be presented like an instant purchase. A direct-buy path should not be presented like a review-dependent application. A craft path should not be presented as if it behaves exactly like a normal buy flow. If the app hides those distinctions, the integration is not preserving the structure the offering is meant to provide.
For request-based offerings, the product pattern is straightforward. The app creates request state, then confirms that request through request history or related bucket state instead of guessing from the immediate response. This is one of the clearest entry paths because it creates real state without forcing the builder to begin with a chain-backed funding lifecycle. Quickstart already uses offering request as the cleanest first app-level write for that reason, and the SDK Guide already treats request history as the confirming read after request creation. That pattern should remain the default for any app whose offering path is centered on review, queueing, or later resolution.
For direct participation flows, the app should treat buy or craft as real participation writes rather than as generic commerce actions. The main difference from a request flow is not only the write method. It is the kind of state the app should expect afterward. A direct path may resolve through fixed, choice, or random output logic, and it may still depend on auto mint, pending request, manual review, delayed resolution, queue work, or later lifecycle confirmation depending on how the offering is configured. The Playbook should therefore tell builders not to assume that âbuyâ means âdone.â The app still has to confirm what the action became inside Yokefellow.
A good offering integration also keeps the bucket visible. Offerings live inside the bucketâs participation surface, so the app should avoid making them feel detached from the bucket that issued them. The user should be able to tell what initiative the offering belongs to, what bucket context shapes its meaning, and where the resulting output or right is meant to matter. This keeps the Playbook aligned with the rest of the doc set: the bucket remains the participation surface, and the offering is the structured path inside it.
Finally, the app should confirm offering outcomes through the right follow-up surface. Request-based offerings should normally confirm through request history. Wallet-centered apps may also confirm through entitlements or bucket reads with wallet context. Operator-aware apps may confirm through queue state when the result is still pending or reviewable. The principle is the same one already established in Quickstart and the SDK Guide: the write is only one step in the product flow. The app must read the resulting state from the surface that actually matters to the feature it is building.
5. Rights-Related Output Handling
A good Yokefellow integration should not treat user result state as one flat âowned itemsâ list. The platformâs user-facing result state is broader than that. In the current surface, wallet-facing output state can involve owned mints, indexed holdings, pending requests, queued mint work, capabilities, bucket permissions, and other bucket-scoped meaning around what the user can do or what a result means in context. That means the app should be built to show three different things clearly: what the user already has, what is still pending, and what rights-related state is available only in a particular bucket context.
The safest pattern is to start with wallet entitlements when the feature is user-state-centered, then layer bucket context and other supporting state on top where the bucket matters to the meaning of the result. A wallet-only view can answer what the user currently holds or has in flight. A bucket-aware view can answer what those holdings and pending states mean inside one initiative. That is the cleaner product model because Yokefellow outputs are often bucket-linked in meaning even when the wallet is the holder.
An integration should therefore avoid two common mistakes. The first is treating NFTs as the whole product meaning. The second is treating pending request or queued mint state as if it were already resolved output. The Rights paper already locks the conceptual rule here: the offering is the path, the right is the user-facing meaning, and the NFT may be the container that carries it. The Mechanics paper adds the operational distinction that request-state and mint-state are not the same stage. The Playbook version of that rule is more practical: surface the resolved result, surface pending state separately, and keep the bucket context visible where it shapes what the result actually does.
A clean UI usually needs at least three lanes of result state. One lane for resolved holdings. One lane for pending or reviewable outcomes. One lane for bucket-scoped power or meaning. Resolved holdings may include minted outputs or indexed holdings already attached to the wallet. Pending state may include offering requests that are still unresolved or mint jobs that are still queued after approval. Bucket-scoped meaning may include permissions, capabilities, bindings, or bucket-linked credit context that only makes sense inside the bucket that issued or attached it. If those are all dumped into one generic inventory screen, the user loses the structure Yokefellow is trying to preserve.
The practical rule is simple: read entitlements as a grouped state surface, not as a single ownership table. Then present that grouped state honestly. Show what is owned. Show what is pending. Show what is bucket-linked. Show what still depends on operator action or later fulfillment. That keeps the integration aligned with the platformâs actual output model instead of flattening it into generic NFT inventory behavior.
6. Funding Flow Integration
A funding-centered integration should treat deposit, withdraw, and transfer-between-buckets as real product flows, not as invisible service calls hidden behind one confirm button. In the current surface, these actions are explicitly lifecycle-driven. Deposit and transfer-between-buckets return preparation data for chain-side execution and later finalization where required. Withdraw returns a signature preparation step, then a signed submit step, then transaction status tracking. That means the app should be designed around flow stages instead of around the fiction that funding is instant.
A clean funding flow has four visible phases. First, the app prepares the action through Yokefellow. Second, the app hands the user into the wallet-side or signature-side step the returned flow requires. Third, the app tracks transaction status. Fourth, the app completes any explicit Yokefellow-side finalization where the lifecycle still requires it, then refreshes the affected surfaces. The SDK Guide already sets this pattern for funding flows, and the API Reference reflects the same structure from the implemented routes.
For deposits, the app should present the flow as prepare, approve if needed, submit transaction, track status, then finalize. For withdraws, the app should present the flow as prepare message, sign message, submit signed request, then track status. For transfer-between-buckets, the app should present the flow as prepare transaction, submit transaction, track status, then finalize. Those differences matter because the user experience should mirror the real lifecycle shape. A withdraw should not be modeled like a deposit if the actual next action is signature submission instead of direct onchain call preparation, and it should not be described as using the same explicit finalization path as deposit and transfer-between-buckets because the current route surface does not do that.
A good funding integration also refreshes the right surfaces after the action progresses. Bucket-centered funding views should refresh bucket funding or bucket snapshot state. Wallet-centered views should refresh wallet-aware state when the funding action affects what the user can do next. If the funding flow is tied to a participation path, the app may also need to refresh offering-related or entitlement-related state after the transaction is recognized. Quickstart already establishes the rule behind this: confirm the resulting state through the surface the app is supposed to support, not only through the fact that the write returned.
The most important thing is not to hide lifecycle state from the user. If the app has prepared a deposit but the transaction is not confirmed, say that. If the transaction is confirmed but finalization is still pending, say that. If the withdraw signature is prepared but not yet submitted, say that. A funding flow is much easier to trust when the app shows the real stage the user is in rather than compressing the whole thing into one vague âprocessingâ label. The app should also preserve the lifecycle metadata it will need to resume cleanly after refresh, reconnect, or navigation, especially transaction hash, lifecycle kind, and returned next-step context.
7. Lifecycle State as Product State
9. Error Handling in Real Integrations
A real Yokefellow integration should treat error handling as product behavior, not just logging behavior. The API Reference owns the route-level error model, but the Playbook needs to answer a different question: what should the app do when the surface behaves correctly and still returns something the user needs to understand? That includes malformed input, auth failure, object absence, lifecycle incompletion, review-dependent waiting, queue delay, and true operation failure. If those all collapse into one generic error banner, the app loses too much meaning.
The first rule is to distinguish setup failure from user-action failure. If the app cannot authenticate, cannot reach the intended environment, or cannot load the primary bucket or wallet context, that is not the same kind of problem as a failed participation attempt or a still-pending transaction. The user should be able to tell whether the app is misconfigured, whether access failed, or whether the action they just took is still moving through the expected flow. Quickstart already makes part of this clear by requiring one expected error case and by treating visible failure as part of the first successful integration path.
The second rule is to separate ânot yet completeâ from âfailed.â This matters throughout Yokefellow. A request may be pending review. A mint may be queued. A deposit may be awaiting confirmation. A transfer may be confirmed onchain but still pending finalization. None of those states should be presented as hard failure. At the same time, none should be silently presented as success. The product should tell the truth about the stage the user is in. The SDK Guide already frames this as lifecycle handling rather than exceptional recovery, and the Playbook should turn that into a UI and state-management rule.
The third rule is to keep retry paths honest. A user should only be offered a retry when the next action is actually safe and meaningful. If a request creation failed because the offering id was invalid, the retry path is not âtry again blindly.â If a withdraw is waiting for signature submission, the next action is not âstart over.â If a mint job is queued but not failed, the right product response may be to show status and expected follow-up rather than to expose a reset button. Good integration behavior comes from reading the state the platform returned, not from assuming every stalled-looking state is the same kind of failure.
The fourth rule is to keep the affected surface readable after failure. If a user attempts a request and it fails, the bucket should still render. If a funding flow stalls, the app should still show the bucket or wallet state that existed before the action. If a queue item is unresolved, the app should still surface the latest known request or entitlement state. A good Yokefellow integration does not let a failed write wipe out the readability of the participation surface itself.
The practical rule is this: show what failed, show what did not fail, show what is still pending, and only show success when Yokefellowâs own state says the action is actually resolved. That keeps the product aligned with the platformâs lifecycle model and makes the integration easier to trust.
8. Operator-Aware Flows
A Yokefellow integration should be operator-aware whenever the feature depends on requests, review, queue processing, delayed fulfillment, or bucket-linked control. The platform does not pretend every meaningful result is instant or fully automatic. Some outcomes depend on request review. Some depend on mint-queue processing. Some depend on event-driven matching. Some depend on bucket permissions, capabilities, or bindings. The app should preserve that reality instead of building only for the happy path where everything resolves immediately.
The first operator-aware pattern is request review. If the app exposes request-based participation, it should also decide how pending requests become visible to the operator side and how those operator actions affect the participant side. In the current surface, request objects carry rich state around status, selection, payment capture or release, review metadata, resolution metadata, and related mint outcomes. That means an operator surface should not treat requests as simple approve or deny toggles. It should treat them as participation objects moving through a real resolution path. It should also keep clear that request review is the decision layer, not the same thing as mint execution.
The second operator-aware pattern is issuance and queue handling. A queued mint job is not just a backend implementation detail. It is part of the state of the userâs outcome. If the app includes an operator console or an advanced participant view, it should decide when to surface queue state, when queued work should remain operator-facing, and when to present the result as queued versus actually issued. This is especially important in apps where fulfillment speed affects user trust. The key distinction is simple: request queue is for review and advancement, while mint queue is for execution.
The third operator-aware pattern is earned and event-driven participation. In the current surface, offering-event submission can record an app event, evaluate earned-mode offerings, apply eligibility and claim-policy checks, create offering requests where the event qualifies, and in some cases auto-fulfill into queued mint work. That means an app built around achievements, game events, app milestones, or similar behavior should not model earned participation as a purely local app concept. It should model it as a Yokefellow participation flow that may create request state, pending state, or queued issuance depending on the offeringâs configuration. That is a good example of why operator-aware and system-aware flows belong in the Playbook instead of being left to guesswork.
The fourth operator-aware pattern is bucket-linked authority. Some surfaces are not only about participation. They are about control, permissions, capabilities, bindings, or bucket-scoped rights that let someone act in relation to the bucket. An app that exposes bucket management, posting, review, issuance, or other privileged actions should keep that bucket-linked authority visible and scoped correctly. Do not flatten operator power into generic admin UI language if the actual meaning is bucket-linked and contextual.
The practical rule is simple: where review, queueing, earned-event evaluation, or bucket-linked control exists, the app should expose enough state for the right actor to understand what is happening and what is still required. That is how an integration stays honest to the platformâs operator model instead of pretending everything is instant, global, or automatic.
9. Error Handling in Real Integrations
A real Yokefellow integration should treat error handling as product behavior, not just logging behavior. The API Reference owns the route-level error model, but the Playbook needs to answer a different question: what should the app do when the surface behaves correctly and still returns something the user needs to understand? That includes malformed input, auth failure, object absence, lifecycle incompletion, review-dependent waiting, queue delay, stale readable state, and true operation failure. If those all collapse into one generic error banner, the app loses too much meaning.
The first rule is to distinguish setup failure from user-action failure. If the app cannot authenticate, cannot reach the intended environment, or cannot load the primary bucket or wallet context, that is not the same kind of problem as a failed participation attempt or a still-pending transaction. The user should be able to tell whether the app is misconfigured, whether access failed, whether the readable surface is delayed, or whether the action they just took is still moving through the expected flow. Quickstart already makes part of this clear by requiring one expected error case and by treating visible failure as part of the first successful integration path.
The second rule is to separate not-yet-complete from failed. This matters throughout Yokefellow. A request may be pending review. A mint may be queued. A deposit may be awaiting confirmation. A transfer may be confirmed onchain but still pending finalization. None of those states should be presented as hard failure. At the same time, none should be silently presented as success. The product should tell the truth about the stage the user is in. The SDK Guide frames this as lifecycle handling rather than exceptional recovery, and the API Reference makes clear that lifecycle-incomplete is not the same thing as lifecycle-failed. The Playbook should turn that into a UI and state-management rule.
The third rule is to keep retry paths honest. A user should only be offered a retry when the next action is actually safe and meaningful. If a request creation failed because the offering id was invalid, the retry path is not try again blindly. If a withdraw is waiting for signature submission, the next action is not start over. If a mint job is queued but not failed, the right product response may be to show status and expected follow-up rather than to expose a reset button. Good integration behavior comes from reading the state the platform returned, not from assuming every stalled-looking state is the same kind of failure. Good error handling should preserve enough information to retry, resume, or inspect the issue cleanly where appropriate.
The fourth rule is to keep the affected surface readable after failure. If a user attempts a request and it fails, the bucket should still render. If a funding flow stalls, the app should still show the bucket or wallet state that existed before the action. If a queue item is unresolved, the app should still surface the latest known request, entitlement, or bucket state. A good Yokefellow integration does not let a failed write wipe out the readability of the participation surface itself. It should preserve enough lifecycle and refresh context to recover cleanly after refresh, reconnect, or navigation.
The practical rule is this: show what failed, show what did not fail, show what is still pending, and only show success when Yokefellowâs own state says the action is actually resolved. That keeps the product aligned with the platformâs lifecycle model and makes the integration easier to trust.
10. Production Checklist
Once the integration works in development, the next question is whether it is structured well enough to ship. This is where the production-minded guidance of the Playbook belongs. The point is not to restate every endpoint. The point is to make sure the app is behaving like a real Yokefellow integration rather than like a thin demo over a few successful requests.
A production-ready integration should confirm that it is pointed at the correct environment and correct v1 surface, that its auth posture matches the routes it uses, and that it is not confusing public reads with app-auth reads. It should also confirm that wallet context is being passed only where relevant and is not being treated as the same thing as integration auth. These are basic requirements, but they matter because the rest of the product model depends on them being correct.
A production-ready integration should also have an explicit post-write refresh strategy. Bucket-centered apps should know when they re-read bucket catalog or bucket funding. Wallet-centered apps should know when they re-read entitlements or request state. Funding-centered apps should know how they poll transaction status, when they finalize where required or continue the signed-submit path where required, and what they refresh afterward. The product should not depend on guesswork or manual refresh for its main lifecycle transitions. Quickstart and the SDK Guide both point toward this by making lifecycle confirmation part of the intended flow rather than an optional extra.
A production-ready integration should preserve resumable lifecycle state. If the app depends on transaction hashes, relevant request or queue identifiers, or returned next-step context, it should store enough information to survive refresh, reconnect, or navigation. It should not require the user to remain on one uninterrupted screen for every meaningful action. This matters especially for funding flows, request-based paths, and any feature that includes queued or operator-reviewed outcomes.
A production-ready integration should also make pending state visible and specific. Do not use one generic âprocessingâ label for request review, queue wait, chain confirmation, and finalization. Do not hide operator-aware or delayed-resolution paths behind instant-success language. Do not imply that every output is already owned just because the participation step completed. The point of Yokefellowâs structure is to keep these states legible. The app should preserve that legibility.
Finally, a production-ready integration should test one real happy path and one real imperfect path for each primary feature. For a bucket-centered app, that usually means one successful bucket-centered participation flow and one flow that remains pending or fails visibly. For a funding-centered app, that usually means one successful transaction lifecycle and one interrupted or incomplete lifecycle that the app can resume or explain. That is the practical standard for shipping something that respects the platformâs actual behavior instead of only its cleanest demo path.
11. Where to Go Next
Once a builder understands how to anchor the app on the right primitive, how to integrate offerings, outputs, funding flows, lifecycle state, operator-aware behavior, and production handling, the next document should be the Example App Spec. The Playbook explains how to structure a real Yokefellow integration in general terms. The Example App Spec shows one believable implementation that carries those patterns through one full product surface from first read to resolved outcome. That is the cleanest handoff because it lets the Playbook stay reusable while the Example App Spec becomes concrete.
If the builder instead needs route lookup, request-shape clarity, or response-shape confirmation while implementing, the right fallback is the API Reference. If the builder needs packaged-client behavior, auth posture, lifecycle helpers, or common client flows, the right fallback is the SDK Guide. If the builder needs to re-prove the environment, the first real read, or the smallest working lifecycle path, the right fallback is the Quickstart. The Hub already gives these documents distinct jobs, and the Playbook should reinforce that separation instead of trying to absorb them.