docs(conditions): Add LLM-friendly authoring resources by theref · Pull Request #12 · nucypher/taco-docs

theref · 2026-04-09T15:15:32Z

Summary

TACo conditions are becoming the primary integration surface, and adopters increasingly author them with LLM assistance. This PR adds six new pages under for-developers/taco-sdk/references/conditions/ designed to make hands-off, LLM-driven condition authoring reliable.

building-with-llms.md — recommended workflow, prompt template, and the validate → iterate loop. Tells the LLM exactly which four references to attach.
cookbook.md — 22 worked JSON examples covering every condition type plus common patterns (NFT-or-allowlist, time-windowed paid access, weather-based fallback, normalised balance, etc.). Includes the full `operations` table.
discord-tipping-bot-deep-dive.md — fully annotated walkthrough of a real complex Action Control condition: compound + sequential + ECDSA + JSONPath + snowflake math + on-chain CREATE2 derivation + nested ABI calldata validation. Addresses and brand names are anonymised.
context-variables.md — cheatsheet of built-in variables (`:userAddress`, `:signingConditionObject`, etc.), naming rules, and where they can/can't appear.
validating-conditions.md — drop-in 40-line script that catches schema errors locally before they hit the network. Includes valid/invalid output samples and a list of what it does and does not catch.
troubleshooting.md — common Zod and runtime errors mapped to fixes.

The schema reference is linked to `taco-web` `signing-epic` rather than vendored, so it remains the auto-generated source of truth.

`SUMMARY.md` and `conditions/README.md` updated to surface the new pages.

Notes for review

All examples and the deep-dive use signing-epic features (`signing-attribute`, `signing-abi-attribute`, variable `operations` including `keccak`/`create2`/`toTokenBaseUnits`). When `signing-epic` merges to `taco-web` `main`, the GitHub URLs across these files will need re-pointing — single find/replace.
Addresses in the deep-dive are placeholders (`0xUSDC_ON_BASE`, `0xAA_FACTORY`, etc.). Reviewers can cross-check structural accuracy against `nucypher/discord-taco-web`.
No changes to existing per-condition reference pages (`timecondition.md`, etc.) — those remain authoritative and are linked from the new index.

Test plan

GitBook builds the new pages without broken links
`SUMMARY.md` nav order renders as intended
Schema-reference link resolves on `signing-epic`
Sanity-check at least one cookbook example through `validate-conditions.ts`

Adds six new pages under conditions/ aimed at developers (and their LLMs) authoring conditions hands-off: - building-with-llms: workflow, prompt template, iteration loop - cookbook: 22 worked JSON examples covering every condition type - discord-tipping-bot-deep-dive: annotated walkthrough of a complex Action Control condition (addresses anonymised) - context-variables: cheatsheet of built-ins, naming rules, gotchas - validating-conditions: 40-line script + usage - troubleshooting: common Zod errors mapped to fixes Schema reference is linked directly to taco-web signing-epic so it stays the source of truth without drift. README and SUMMARY updated to surface the new pages.

Drop "most complex/intricate" language and "TACo supports today" phrasing from the deep-dive and cookbook. Conditions are arbitrarily expressive; the example is illustrative, not a ceiling.

Cookbook examples are now copy-paste runnable through validate-conditions.ts, which expects the full { "version": "1.0.0", "condition": {...} } shape that ConditionExpression.fromObj parses. Also drop a stray Collab.Land reference in example 12.

Adds links and integration snippets for the JSON Schema variant of the condition schema (sibling to condition-schemas.md), which lands in nucypher/taco-web#772. Covers three integration points: - Editor inline validation via $schema in conditions.json - LLM structured output via tool input_schema - Standalone validation in any language via ajv / jsonschema / etc. building-with-llms gains a JSON Schema integration section. validating-conditions clarifies when to use JSON Schema vs the TypeScript script. README and cookbook pick up shorter pointer notes.

derekpierre · 2026-04-09T20:32:33Z

+
+## Source
+
+A reference copy of this script lives in [`discord-taco-web/scripts/validate-conditions.ts`](https://github.com/nucypher/discord-taco-web/blob/main/scripts/validate-conditions.ts) and is used by the Discord tipping bot integration in CI.


Is this URL correct? Is this script actually available somewhere in signing-epic or main?

yeah that should be on theref repo, my bad. the script is doing anything fancy https://github.com/theref/discord-taco-web/blob/main/scripts/validate-conditions.ts

If the script is tested and works well, you can add it to the nucypher/taco-web repos.

Once this URL is fixed, I can approve.

cygnusv

Great work! My only comment is that my agent friend thought that information is scattered through several files. I created a single skill file that summarizes the process and references these new additions to the docs, although I'm not sure what's the best place to share this.

derekpierre

Nice work

Important comment about "then": true not being valid for an ifThenElse Condition.
Not in this PR, but we'll need a follow-up PR down the road to update the URLs that use the signing-epic branch to point to main once signing-epic gets merged and released.

derekpierre · 2026-04-14T19:30:37Z

+
+## 13. `SigningObjectAttributeCondition` — UserOperation field check
+
+Used in TACo Action Control. Validate that an attribute on the object being signed (e.g. an ERC-4337 `UserOperation`) matches an expected value.


derekpierre · 2026-04-14T19:42:33Z

+- Whether the JSON API endpoint will return data in the shape your JSONPath expects
+- Whether the user will satisfy the condition at decryption time
+
+For end-to-end testing, use the [TACo Playground](https://playground.taco.build/) or a local testnet (see [Quickstart](../../../access-control/quickstart-testnet.md)).


I don't think the TACo playground is up to date. Not sure our plan here. I guess validation as part of the playground is simpler to update than allowing creation of conditions...?

- Cookbook §18 and §21: replace invalid `"thenCondition": true` with real conditions. Only `elseCondition` accepts a boolean in the if-then-else schema. - Cookbook §19: fix NFT-or-allowlist example — replace the broken `eth_getBalance` + `"comparator": "in"` against an address list with a `ContextVariableCondition` on `:userAddress` (the shape `AddressAllowlistCondition` wraps internally). - Cookbook §9 (Solana JsonRpcCondition): hard-code the account address instead of accepting it via `:solanaAddress`. Added a note on when an authenticated channel would be the right pattern. - Cookbook §11 / §12: note that `:jwtToken`, `:message`, and `:signature` are default names that can be renamed — important when a single condition has multiple Jwt/Ecdsa children. - Cookbook §12: retitle as "verify an ECDSA signature" and clarify that `":timestamp:discordPayload"` is a concatenation of two context variables. - Cookbook §13 / §14 / TOC: mark signing-* entries as TACo Action Control only. - Update nesting limit across cookbook §16, building-with-llms prompt template, validating-conditions catch-list, and troubleshooting: 4 levels, counted collectively across CompoundCondition, IfThenElseCondition, and SequentialCondition (per nucypher/nucypher#3683 and taco-web 32f3673). - context-variables: restructure the built-in table to distinguish auto-populated (`:signingConditionObject` only), reserved (`:userAddress`, provided by AuthProvider at request time), and default names (`:message`, `:signature`, `:jwtToken`, which can be overridden). - building-with-llms: reference the JSON Schema export as the primary machine-readable source of truth in the LLM prompt template, with the markdown version alongside. - validating-conditions: fix the script source URL to point at theref/discord-taco-web (where it actually lives) with a note that the link will move once promoted into nucypher/taco-web. - Drop TACo Playground references across validating-conditions, troubleshooting, and building-with-llms — the playground is not currently up to date with signing-epic features. Point readers at the local testnet Quickstart instead.

cygnusv · 2026-04-15T14:34:41Z

Opened nucypher/taco-web#775 to track updating docs and skill file when signing epic is merged

Source-verification against taco-web signing-epic surfaced two inaccuracies in the previous commit's context-variables table: - `:nullAddress` is also auto-injected by the node (see `AUTOMATICALLY_INJECTED_CONTEXT_PARAMS` in `taco-web/packages/taco/src/conditions/context/context.ts`) — the previous table claimed `:signingConditionObject` was the only auto-populated variable. Added `:nullAddress` as a row. - Attribution: auto-injection happens on the node side at evaluation time, not by a client-side "signing flow". Reworded accordingly and linked the source file as the authority for future drift.

derekpierre

A couple comments about the tautology strategy for if-then-else condition.

Thanks for resolving the others 👏

derekpierre · 2026-04-16T20:10:06Z


 ## 18. `IfThenElseCondition` — branching

+`ifCondition` and `thenCondition` must both be full conditions — they cannot be booleans. Only `elseCondition` accepts a boolean shortcut (`true` means "admit", `false` means "deny"). If you want the "then" branch to pass unconditionally, use a `ContextVariableCondition` against a variable known to be true, or simply re-use the `ifCondition` verbatim.


I think in general if you are hoping to encompass logic that looks like:

if conditionA then return True else some other conditionB

Then this is just an OR condition i.e. OR(conditionA, conditionB)

Alternatively if were doing something like

if conditionA then return False else some other conditionB

Then this is just AND(NOT(conditionA), conditionB)

If you want the "then" branch to pass unconditionally, use a ContextVariableCondition against a variable known to be true, or simply re-use the ifCondition verbatim.

^ In other words, not so sure about this statement and feels like it can be removed. If the then condition is intended to be a boolean then just use a compound condition, OR or AND appropriately. No need to have an artificial then condition to pass / fail.

derekpierre · 2026-04-16T20:15:07Z

 ## 21. Pattern: weather-based discount with fallback

-If the weather API returns rain, anyone can decrypt; otherwise, only NFT holders.
+If the weather API returns rain, anyone can decrypt; otherwise, only NFT holders. `thenCondition` must be a real condition, so we re-use the rain check as a tautological pass (it already evaluated to true in the `ifCondition` branch).


Same comment as above about artificial then condition.

We can rethink the example to be: eg. a backup safety plan for attendees maybe? i.e. if there is rain, then check if wind speed > y, and if both are true anyone can decrypt, otherwise only NFT holders.

theref added 2 commits April 9, 2026 16:15

docs(conditions): Remove framing that understates expressivity

3dc7127

Drop "most complex/intricate" language and "TACo supports today" phrasing from the deep-dive and cookbook. Conditions are arbitrarily expressive; the example is illustrative, not a ceiling.

theref requested review from KPrasch, arjunhassard, cygnusv and derekpierre April 9, 2026 15:30

theref added 2 commits April 9, 2026 16:45

derekpierre reviewed Apr 9, 2026

View reviewed changes

cygnusv approved these changes Apr 10, 2026

View reviewed changes

cygnusv mentioned this pull request Apr 13, 2026

TACo condition authoring skill nucypher/taco-web#774

Closed

7 tasks

derekpierre requested changes Apr 14, 2026

View reviewed changes

derekpierre reviewed Apr 14, 2026

View reviewed changes

Comment thread for-developers/taco-sdk/references/conditions/building-with-llms.md Outdated

derekpierre requested changes Apr 16, 2026

View reviewed changes

derekpierre mentioned this pull request Apr 21, 2026

TACo condition authoring skill nucypher/taco-web#779

Open

7 tasks


		## Source

		A reference copy of this script lives in [`discord-taco-web/scripts/validate-conditions.ts`](https://github.com/nucypher/discord-taco-web/blob/main/scripts/validate-conditions.ts) and is used by the Discord tipping bot integration in CI.


		## 13. `SigningObjectAttributeCondition` — UserOperation field check

		Used in TACo Action Control. Validate that an attribute on the object being signed (e.g. an ERC-4337 `UserOperation`) matches an expected value.


		## 18. `IfThenElseCondition` — branching

		`ifCondition` and `thenCondition` must both be full conditions — they cannot be booleans. Only `elseCondition` accepts a boolean shortcut (`true` means "admit", `false` means "deny"). If you want the "then" branch to pass unconditionally, use a `ContextVariableCondition` against a variable known to be true, or simply re-use the `ifCondition` verbatim.

Conversation

theref commented Apr 9, 2026

Summary

Notes for review

Test plan

Uh oh!

derekpierre Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

theref Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

derekpierre Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

derekpierre Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

cygnusv left a comment

Choose a reason for hiding this comment

Uh oh!

derekpierre left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

derekpierre Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

derekpierre Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cygnusv commented Apr 15, 2026

Uh oh!

derekpierre left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

derekpierre Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

derekpierre Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

derekpierre Apr 10, 2026 •

edited

Loading

derekpierre left a comment •

edited

Loading

derekpierre Apr 14, 2026 •

edited

Loading

derekpierre left a comment •

edited

Loading