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:06:39Z

+You are helping me author a TACo condition in JSON.
+
+Reference material (please read before writing any condition):
+- Schema (source of truth): https://github.com/nucypher/taco-web/blob/signing-epic/packages/taco/schema-docs/condition-schemas.md


Do you want to use the json schema file here?

derekpierre · 2026-04-14T19:14:55Z

+
+## Built-in context variables
+
+These are automatically populated by the SDK or by the network. You do **not** need to set them yourself.


We might need to clarify this a bit; a few clariifications:

":signingConditionObject" is the only context var that is automatically populated and does not need to be added to the condition context

":userAddress" is a context variable (reserved) whose value can only be provided by an AuthProvider at request time

":message", ":signature", ":jwtToken" are default context variables used by ECDSACondition/JWTCondition, but they are not "automatically populated", and they don;t have to be used i.e. the "context variable" for those entries can be called anything, but there is a default value if you don't want to specify your own. This is important because if you had multiple JWTConditions as part of the same condition, you don't necessarily need the same token to be used for both, each can use their own context variable for differentiating what token is for what condition. Same for ECDSACondition.

derekpierre · 2026-04-14T19:19:08Z

+9. [JsonRpcCondition — arbitrary JSON-RPC call](#9-jsonrpccondition--arbitrary-json-rpc)
+10. [JsonCondition — querying a passed-in payload](#10-jsoncondition--querying-a-context-payload)
+11. [JwtCondition — verify a signed JWT](#11-jwtcondition--verify-a-jwt)
+12. [EcdsaCondition — verify a signature](#12-ecdsacondition--verify-an-ed25519-signature)


Suggested change

12. [EcdsaCondition — verify a signature](#12-ecdsacondition--verify-an-ed25519-signature)

12. [EcdsaCondition — verify an ECDSA signature](#12-ecdsacondition--verify-an-ed25519-signature)

derekpierre · 2026-04-14T19:19:52Z

+13. [SigningObjectAttributeCondition — UserOperation field check](#13-signingobjectattributecondition--useroperation-field-check)
+14. [SigningObjectAbiAttributeCondition — UserOperation calldata check](#14-signingobjectabiattributecondition--validate-calldata)


We should mention that this only applies to TACo Action Control, since signing specific.

derekpierre · 2026-04-14T19:27:34Z

+
+```json
+{
+  "version": "1.0.0",


I think we should be careful here and use best practice type of examples i.e. having the requester specify the context variable for the wallet address is a bit awkward and not that practical/safe.

Instead you could use a hardcoded solana address for the param, or a blocktime rpc call - both examples can be seen here - https://github.com/nucypher/nucypher/blob/main/tests/acceptance/conditions/test_conditions.py#L907

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:34:43Z

+      "parameters": [":userAddress"],
+      "returnValueTest": { "comparator": ">", "value": 0 }
+    },
+    "thenCondition": true,


This is not valid.

Only the else condition can have a boolean, "then" must be a condition.

export const ifThenElseConditionSchema: z.ZodSchema = z.lazy(() => baseConditionSchema .extend({ conditionType: z .literal(IfThenElseConditionType) .default(IfThenElseConditionType), ifCondition: anyConditionSchema, thenCondition: anyConditionSchema, elseCondition: z.union([anyConditionSchema, z.boolean()]), })

derekpierre · 2026-04-14T19:36:14Z

+        "conditionType": "rpc",
+        "chain": 1,
+        "method": "eth_getBalance",
+        "parameters": [":userAddress", "latest"],
+        "returnValueTest": {
+          "comparator": "in",
+          "value": [
+            "0xALLOWED_ADDRESS_1",
+            "0xALLOWED_ADDRESS_2",
+            "0xALLOWED_ADDRESS_3"
+          ]


Not sure this makes sense. The balance (integer) is in a list of addresses?

Did you mean to use a ContextVariableCondition where the :userAddress context variable is in a list of allowed addresses?

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

+      "query": "$.current.rain",
+      "returnValueTest": { "comparator": ">", "value": 0 }
+    },
+    "thenCondition": true,


Same comment here about this not being valid.

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...?

derekpierre · 2026-04-14T19:58:32Z

+- Output a single JSON object (no prose around it) when I ask for a condition.
+- Every field must exist in the schema. Do not invent fields.
+- Context variables start with ":" and match /^:[a-zA-Z_][a-zA-Z0-9_]*$/.
+- CompoundCondition: max 5 operands, max 2 levels of nesting.


Couple things here:

Nested levals were increased from 2 to 4 - feat(conditions): add exponent operator and expand condition limits nucypher#3683, nucypher/taco-web@32f3673

Nested levels apply to MultiConditions i.e. CompoundCondition, IfThenElse, and SequentialCondition

There may be other spots in this PR where "2 levels of nesting" is mentioned.

(cc @cygnusv for also reflecting this in PR nucypher/taco-web#774)

- 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.

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

Open

7 tasks

derekpierre requested changes Apr 14, 2026

View reviewed changes

derekpierre reviewed Apr 14, 2026

View reviewed changes


		## 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.


		## Built-in context variables

		These are automatically populated by the SDK or by the network. You do not need to set them yourself.

	12. [EcdsaCondition — verify a signature](#12-ecdsacondition--verify-an-ed25519-signature)
	12. [EcdsaCondition — verify an ECDSA signature](#12-ecdsacondition--verify-an-ed25519-signature)

		13. [SigningObjectAttributeCondition — UserOperation field check](#13-signingobjectattributecondition--useroperation-field-check)
		14. [SigningObjectAbiAttributeCondition — UserOperation calldata check](#14-signingobjectabiattributecondition--validate-calldata)


		## 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.

Conversation

theref commented Apr 9, 2026

Summary

Notes for review

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

cygnusv commented Apr 15, 2026

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