> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/guides/dag-construction/math-branching-dag-entry.md). # Entry Groups {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Extend a branching DAG with explicit entry groups and verify that each supported input path produces the intended execution. {% endhint %} This guide builds on the [Build the Quickstart guide](/guides/dag-construction/math-branching-dag-builder.md) by extending the example to support multiple entry points using entry groups. You'll take the original `math_branching.json` DAG and add an alternative entry path that allows users to directly provide two numbers for multiplication instead of adding a constant to the input. {% hint style="info" %} Prerequisites: complete the [setup guide](/guides/getting-started/setup.md) before extending the DAG. {% endhint %} The Tool FQNs and schemas in this follow-on page are illustrative placeholders, not provisioned deployment identities. Replace every `` FQN, port, output variant, and value type with the exact `nexus tool inspect --tool-fqn ` result or a provider-reviewed `MetaSchema` record before saving, validating, publishing, or scheduling. If the target provider has not supplied the inspection tuple, stop; do not treat the historical-looking math names below as runnable Tools. ### What You'll Learn * How to add multiple entry points to a DAG * How to define and use entry groups * How to ensure DAG validity with multiple entry paths * How different entry groups affect execution flow #### Understanding Entry Groups Entry groups define named sets of entry points for a DAG. They allow you to: * Provide multiple ways to start a DAG execution * Group related entry vertices * Explicitly specify which vertices should be considered entry points {% hint style="success" %} Without entry groups, a DAG uses the default entry mechanism (vertices with unsatisfied input ports become entry points). With entry groups, you gain explicit control over how the DAG can be started. {% endhint %} **Why Use Entry Groups?** The explanation above should allow you to understand why, given a certain DAG definition, you might want to have explicit control over how the DAG execution can start. However, you might be thinking: *Why design the DAG like this in the first place? Could you not simply split this up into independent DAGs?* The answer is yes, yes you could. Whether you choose to split up different entry configurations into separate DAGs or define a composite DAG with flexibility through entry groups, will be a design choice depending on your specific preferences and use case. Nexus is agnostic to these design choices and provides you the ability to do both! #### The Extended DAG We'll extend our original branching math DAG by: 1. Adding a new vertex `mul_inputs` that takes two user-provided inputs and multiplies them 2. Connecting this multiplication result to the same comparison step as the original addition result 3. Creating two explicit entry groups to select between the addition path and the multiplication path Here's a visual representation of the extended workflow:
Choose add_entry or mul_entry inputs

Phase 1: Bind independent add_entry and mul_entry inputs. Keyed facts: add_entry binds User Input: a plus fixed b = -3 into xyz.taluslabs.math.i64.add@1; mul_entry binds independent User Input: a and User Input: b into xyz.taluslabs.math.i64.mul@1.

Use one comparison result for all conditional paths

Phase 2: Use one comparison result for all conditional paths. Keyed facts: xyz.taluslabs.math.i64.add@1 and xyz.taluslabs.math.i64.mul@1 feed xyz.taluslabs.math.i64.cmp@1; the shared comparison result remains one guarded decision.

Conditional Tool branches produce final variants

Phase 3: Route guarded branches to exact Tool results. Keyed facts: xyz.taluslabs.math.i64.cmp@1 selects lt, gt, and eq; xyz.taluslabs.math.i64.mul@1 serves the lt and gt branches; xyz.taluslabs.math.i64.add@1 serves eq; defaults are b = -3, b = 7, and b = 1, and one terminal result per branch.

This diagram shows the extended workflow with two entry paths: 1. The original addition path that takes one input and adds `-3` to it 2. A new multiplication path that takes two inputs and multiplies them Both paths connect to the same comparison vertex, which then branches based on whether the result is negative, positive, or zero. Entry groups ensure only one path is active during execution. #### Step-by-Step Construction Let's build the `math_branching_entry_group.json` file step by step. Any `jsonc` block below is an illustrative fragment with comments or omitted siblings. Save, validate, and publish only the strict complete `json` block under [Putting It All Together](#putting-it-all-together). **1. Define Vertices (`vertices` list)** We'll start with the vertices from our original DAG and add the new `mul_inputs` vertex: ```json { "vertices": [ { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "add_input_and_default", "entry_ports": [ { "name": "a" } ] }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_inputs", "entry_ports": [ { "name": "a" }, { "name": "b" } ] }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "is_negative" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_by_neg_3" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_by_7" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "add_1" } ] } ``` Note that we explicitly list both `a` and `b` as `entry_ports` for the `mul_inputs` vertex because both will be provided by the user, not by default values or edges. **2. Define Edges (`edges` list)** Now we'll define the edges, including a new edge from our new `mul_inputs` vertex to the comparison step: ```json { "edges": [ { "from": { "vertex": "add_input_and_default", "output_variant": "ok", "output_port": "result" }, "to": { "vertex": "is_negative", "input_port": "a" } }, { "from": { "vertex": "mul_inputs", "output_variant": "ok", "output_port": "result" }, "to": { "vertex": "is_negative", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "lt", "output_port": "a" }, "to": { "vertex": "mul_by_neg_3", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "gt", "output_port": "a" }, "to": { "vertex": "mul_by_7", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "eq", "output_port": "a" }, "to": { "vertex": "add_1", "input_port": "a" } } ] } ``` The key addition is the second edge, which connects the output of our new `mul_inputs` vertex to the same input port of the `is_negative` vertex that `add_input_and_default` connects to. **3. Set Default Values (`default_values` list)** We'll keep the same default values as the original DAG: ```json { "default_values": [ { "vertex": "add_input_and_default", "input_port": "b", "value": { "one": { "kind": "data", "data": -3 } } }, { "vertex": "is_negative", "input_port": "b", "value": { "one": { "kind": "data", "data": 0 } } }, { "vertex": "mul_by_neg_3", "input_port": "b", "value": { "one": { "kind": "data", "data": -3 } } }, { "vertex": "mul_by_7", "input_port": "b", "value": { "one": { "kind": "data", "data": 7 } } }, { "vertex": "add_1", "input_port": "b", "value": { "one": { "kind": "data", "data": 1 } } } ] } ``` **4. Specify outputs (`outputs` list)** Outputs will also remain identical. ```jsonc { // ... other sections ... "outputs": [ { "vertex": "mul_by_neg_3", "output_variant": "ok", "output_port": "result" }, { "vertex": "mul_by_7", "output_variant": "ok", "output_port": "result" }, { "vertex": "add_1", "output_variant": "ok", "output_port": "result" } ] } ``` Notice that we do not add any default values for the `mul_inputs` vertex, as both its input ports will be provided by the user. **4. Define Entry Groups (`entry_groups` list)** This is where the major addition happens. We'll define two entry groups: ```json { "entry_groups": [ { "name": "add_entry", "vertices": ["add_input_and_default"] }, { "name": "mul_entry", "vertices": ["mul_inputs"] } ] } ``` Each entry group has a name and a list of vertices When executing the DAG, you'll specify which entry group to use, and the DAG will expect inputs for *entry ports* defined on the specified vertices. **5. Why Entry Groups Are Required** Without entry groups, the DAG would have an issue: both `add_input_and_default` and `mul_inputs` would be considered entry vertices, but both connect to the same input port of `is_negative`. This creates a potential race condition against the DAG input model described in the [`dag`](/reference/move/nexus_interface/dag.md) and [`graph`](/reference/move/nexus_interface/graph.md) reference pages. With entry groups, we explicitly specify which entry paths are valid and ensure they won't be active simultaneously. #### Putting It All Together Combining these sections gives us the complete `math_branching_entry_group.json`:
Complete DAG Definition ```json { "vertices": [ { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "add_input_and_default", "entry_ports": [ { "name": "a" } ] }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_inputs", "entry_ports": [ { "name": "a" }, { "name": "b" } ] }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "is_negative" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_by_neg_3" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "mul_by_7" }, { "kind": { "variant": "off_chain", "tool_fqn": "" }, "name": "add_1" } ], "edges": [ { "from": { "vertex": "add_input_and_default", "output_variant": "ok", "output_port": "result" }, "to": { "vertex": "is_negative", "input_port": "a" } }, { "from": { "vertex": "mul_inputs", "output_variant": "ok", "output_port": "result" }, "to": { "vertex": "is_negative", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "lt", "output_port": "a" }, "to": { "vertex": "mul_by_neg_3", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "gt", "output_port": "a" }, "to": { "vertex": "mul_by_7", "input_port": "a" } }, { "from": { "vertex": "is_negative", "output_variant": "eq", "output_port": "a" }, "to": { "vertex": "add_1", "input_port": "a" } } ], "default_values": [ { "vertex": "add_input_and_default", "input_port": "b", "value": { "one": { "kind": "data", "data": -3 } } }, { "vertex": "is_negative", "input_port": "b", "value": { "one": { "kind": "data", "data": 0 } } }, { "vertex": "mul_by_neg_3", "input_port": "b", "value": { "one": { "kind": "data", "data": -3 } } }, { "vertex": "mul_by_7", "input_port": "b", "value": { "one": { "kind": "data", "data": 7 } } }, { "vertex": "add_1", "input_port": "b", "value": { "one": { "kind": "data", "data": 1 } } } ], "entry_groups": [ { "name": "add_entry", "vertices": ["add_input_and_default"] }, { "name": "mul_entry", "vertices": ["mul_inputs"] } ], "outputs": [ { "vertex": "mul_by_neg_3", "output_variant": "ok", "output_port": "result" }, { "vertex": "mul_by_7", "output_variant": "ok", "output_port": "result" }, { "vertex": "add_1", "output_variant": "ok", "output_port": "result" } ] } ```
#### Validation and Execution The JSON remains a template until the exact provider Tool inspection tuple has replaced every placeholder. A successful local JSON shape check is not deployment evidence; stop before these commands when the provider FQNs, `MetaSchema`, or deployment/registry tuple is unavailable. **Validating the DAG** Use the `nexus dag validate` command to validate the DAG structure: ```bash nexus dag validate --path ./math_branching_entry_group.json ``` This ensures your DAG conforms to all the rules, including those related to entry groups and potential race conditions. **Publishing the DAG** After validation, publish the DAG: ```bash # Publish the DAG nexus dag publish --path ./math_branching_entry_group.json # Example output: Published DAG with Object ID: ``` **Executing the DAG with Different Entry Groups** The key difference when executing this DAG is that you must specify which entry group to use: These `--dag-id` examples use the operator-provisioned default Agent and executor. Preflight it before either schedule: ```bash nexus tap default-agent show --json ``` If the readback reports `AgentRegistry missing default agent` or `EDefaultDagExecutorMissing`, stop and hand the deployment to the network operator; do not continue with a failing schedule or attempt to bootstrap the shared executor from this guide. **Using the Addition Entry Group** ```bash # Schedule using the 'add_entry' group with a=10 nexus task schedule --dag-id --entry-group add_entry --input-json '{"add_input_and_default": {"a": 10}}' --prepay-amount-mist 50000000 --occurrence-budget-mist 50000000 --now # Example flow: (10 + -3) = 7. 7 > 0 (gt). 7 * 7 = 49. ``` **Using the Multiplication Entry Group** ```bash # Schedule using the 'mul_entry' group with a=5, b=2 nexus task schedule --dag-id --entry-group mul_entry --input-json '{"mul_inputs": {"a": 5, "b": 2}}' --prepay-amount-mist 50000000 --occurrence-budget-mist 50000000 --now # Example flow: (5 * 2) = 10. 10 > 0 (gt). 10 * 7 = 70. ``` Note that with the `mul_entry` group, you must provide values for both input ports `a` and `b` of the `mul_inputs` vertex. #### The Power of Entry Groups This example demonstrates several key advantages of entry groups: 1. **Multiple Entry Points**: The DAG now supports two different ways to start execution. 2. **Explicit Control**: Each entry group clearly defines which values need to be provided. 3. **Conflict Prevention**: Without entry groups, having both paths active could cause a race condition at the `is_negative.a` input port. 4. **Runtime Selection**: Users can choose which entry point to use when executing the DAG. #### Summary In this guide, we extended our original branching math DAG to support multiple entry points using entry groups. We: 1. Added a new vertex that provides an alternative way to generate a value for comparison 2. Connected this vertex to the same downstream processing flow 3. Created explicit entry groups to control which entry path is active 4. Demonstrated how to execute the DAG with different entry groups Entry groups are a powerful feature of Nexus DAGs that enable more flexible and modular workflows while maintaining the safety guarantees of the DAG execution model. They allow a single DAG to support multiple different starting states and input combinations while preventing potential race conditions. For more advanced usage of entry groups and other DAG features, refer to the [DAG Construction Guide](/guides/dag-construction.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/guides/dag-construction/math-branching-dag-entry.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.