Overview
The concepts a developer needs before building. Five things, one big idea: the signed agreement is the executable.
What you're getting
A platform plus two drop-in React components for building apps where parties negotiate, sign, and execute structured agreements. You point your app at it; it handles identity, the AI surface, the deal lifecycle, multi-party signatures, and on-chain execution.
You don't run any of this infrastructure. You don't implement key management, JWT validation, agent runtimes, deal state machines, ZKP, or chain integration. You make HTTP / GraphQL calls and render the responses.
The big idea
The platform's one defining choice: the signed agreement is the executable. When two parties sign over a deal, what they sign is a canonical-JSON plan with a single SHA-256 hash. That same hash is what gets compiled and executed on-chain.
There is no separate "legal document" and "execution layer" with humans bridging them. There is one object that lives in both places at once. The rendered agreement (recitals, clauses, governing law) and the actions that run when activated come out of the same definition.
Everything else in the platform — agents, workspaces, signatures, payments, swaps, collateral — composes around that central idea.
The big picture
The platform gives you one identity surface, one federated GraphQL gateway for reads and mutations, payments REST polling for work that settles on chain, and agents REST/SSE for collaboration. Sign in via auth REST, use the GraphQL gateway for execution and joined views, then poll message status when execution is asynchronous.
Your app
│
├───────────────┬───────────────────┬────────────────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌─────────────────┐ ┌────────────────┐ ┌────────────┐
│ Auth │ │ GraphQL Gateway │ │ Payments REST │ │ Agents │
│ REST │ │ reads + writes │ │ message status │ │ REST/SSE │
└──────────┘ └─────────────────┘ └────────────────┘ └────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────┐
│ YieldFabric services │ ← one JWT works everywhere
└─────────────────────────────────────┘
Async on-chain mutations return a messageId; poll Payments REST.
Who someone is. Login, sessions, signing keys, multi-sig signatures, delegation.
Where parties + AI work out terms. Workspaces, threads, knowledge graphs, agreement drafting, the Proposed → Signed → Active state machine.
What an activated deal does — the on-chain actions that carry out its terms. Payments, swaps, repo, collateral.
One JWT works everywhere. For most consumer apps you'll use four public hosts: auth REST (auth.yieldfabric.com) for sign-in, the federated gateway (api.yieldfabric.com/graphql) for GraphQL reads and mutations, payments REST (pay.yieldfabric.com) for message-status polling, plus agents REST/SSE (agents.yieldfabric.com) when your app uses workspaces or AI collaboration. Full surface
Five things you'll work with
Almost every feature you build uses some combination of these five. The Deal is the central object; the rest support it.
Account
A party in the system, with login + signing keys. Every entity that can sign agreements has one — your users, the other side, agents acting on behalf of a workspace.
In your app: Your app authenticates a party once. The same JWT works against every YF endpoint and is what they sign agreements with.
Workspace
A bounded scope where parties + AI negotiate. Holds threads, documents, knowledge graphs, AI agent members, and the audit log of everything that happened — including the deals reached inside it.
In your app: When two parties open a conversation about a possible arrangement, your app creates (or finds) a workspace they're both members of. All discussion, drafts, and the final signed deal live there.
Agent
An AI participant inside a workspace. Reads documents, drafts proposed terms, suggests structures, helps interpret what each party wants. Agents never act directly — they propose, humans sign.
In your app: A "deal structurer" agent reads the conversation, drafts a candidate agreement with terms + clauses + cashflow, and pushes it as an Intent. The parties review and either sign or push back.
Deal
central objectThe central object. A multi-party agreement with parties, terms, signatures, a typed action plan, agreement metadata (recitals, governing law, dispute resolution), and a lifecycle: Draft → Proposed → Accepted → Active → Completed. The plan_hash is what parties sign over and what gets executed.
In your app: Once parties converge on terms, your app calls proposeDeal — the plan locks, a hash is computed, the counterparty signs, the deal activates. The same object renders as a legal-style markdown agreement and compiles to an executable workflow.
Execution
What an Active deal does. Compiles to a workflow that runs the actions the deal's plan specifies — payments, contract creation, swaps, collateral locks, periodic processing. Status events stream back to your app via SSE.
In your app: Once a deal activates, your app subscribes to its event stream and shows the user step-by-step progress: signatures collected, payments sent, obligations created, collateral locked. The audit trail keys back to the same plan_hash that was signed.
A typical app flow
How those five concepts string together when an agreement actually gets done.
- 1
Parties log in
Your app uses @yieldfabric/wallet (or calls auth directly). Each party gets a JWT.
- 2
Open or join a workspace
The bounded scope for this negotiation. Members include both parties and the AI agents helping them.
- 3
Optionally: ingest documents
A spec, a prior contract, a regulation. The platform extracts entities into a knowledge graph the agents can read while drafting.
- 4
Conversation drafts the agreement
Parties chat, the agent reads along, identifies terms, drafts candidate plans. When the parties converge, the agent emits a proposed deal as an Intent.
- 5
Parties sign
One click each. The signature is over the plan_hash — what they're agreeing to is exactly what will run. This is the only moment that turns proposal into commitment.
- 6
The system executes
The signed deal compiles into a workflow. Multi-party gates collected if needed, on-chain actions run, audit log written. Your app subscribes to SSE and updates the UI.
Variations: a one-shot payment doesn't need a workspace + deal — call the instant-send mutation directly. A deal can be drafted manually without an agent. A signed deal can have a periodic phase that keeps running for months (coupon payments, scheduled releases). The flow scales up and down with the substance of what's being agreed.
What you don't build
Things you call instead of implement. Each item below is one less thing to think about.
Identity & sessions
JWT lifecycle, refresh, social/wallet/email login providers, multi-sig signature collection, delegated tokens for acting on behalf of a group.
AI agent runtime
Agent registry, scoped memory, tool dispatch, conversation analysis, agent-spec authoring. Plug in OpenAI / Anthropic keys; YF handles the rest.
Knowledge ingestion
PDF parsing, embeddings, entity extraction, RAG retrieval, content-hash dedup. Drop a file in; query frames out.
Workspace runtime
Groups, members, roles, threads, SSE event streaming with per-user privacy filtering, presence, cross-server event relay.
Deal lifecycle
Plan validation + canonical-JSON hashing, propose/sign/activate state machine, multi-party signature collection, the agreement document renderer.
On-chain execution
ZKP transaction construction, validation + execution pipeline, bitemporal audit projection, status event streaming back to your app.
Three things worth remembering
The signed plan IS the executable.
What parties sign over is the same canonical object the system runs. There's no gap to manage between agreement and execution. Build your UI to reflect that: show parties what they're committing to in the same form the system will act on.
Agents propose. Humans sign.
No state-changing action happens without an explicit signature from the party authorising it. The Intent → Confirm boundary is the structural locus of agreement — keep your UI honest about it and the rest falls into place.
Use the right completion channel.
Workspace UX is live over SSE. Backend services should poll the payments message-status endpoint for on-chain settlement so they do not miss the completion event.
Where to go next
Quick Start
Run through the typical flow end-to-end against a live deployment.
Deal Management System (DMS)
The deep dive on the heart of the platform — DealPlan, the signing lifecycle, the agreement projection, plan compilation to execution.
Agents, knowledge & workspaces
Where parties and AI converge on terms before they sign. Workspaces, threads, agents, knowledge graphs, Intents.
Building with YieldFabric
Every common operation as curl + GraphQL. Errors, idempotency, pitfalls.