Creating trails can be a fairly technical process, and you’ll need to exercise caution when building with contracts you aren’t familiar with. Always try searching for a trail to build your app off of first, and reach out in the Discord to get a Trailblazer to help you.We also have a library of video guides to help you better understand to creation process.

Creating a Trail

To get started, you’ll have to sign up for a Herd account. Then, you click the “Trails” button on the sidebar. You may then proceed to create a new trail on Base or Ethereum.

A Farcaster account is highly recommended for publishing a trail, this is for both security and social discovery reasons.

Adding a Primary Node (Step)

Trails are a linear set of write functions to be executed. There is no ability to add branching logic or conditions at this time. As the creator, you are purely prefilling inputs to as many function inputs as you can/want before sharing it with others to execute. Think of it like pre-filling a form. There are three ways to add a primary step node right now:

Write Function: Directly select a write function from a contract to add by either pasting a contract address or selecting one from Sage’s memory.
1. See Primer on Herd Coterminal/Sage Chat for an intro to Sage.
Swap: We use 0x to easily route and swap between tokens. You can specify two tokens, and an amount to be swapped.
From Transactions: This adds a write function from the contract called at the start of a past transaction. We take the “to” address and all the inputs and create a step node with pre-filled inputs for you. More details on this option in the section below.

You can add nodes in between steps by clicking the [+] button on the vertical connecting line. For adding read/source nodes, you can click on the add button to the right of each write node.

Add steps from past transactions

The easiest way to add new trail nodes is in bulk from any wallet’s transactions. From the “Add Step” node, click “From Transactions → Search and Add Transactions” to get the view below. This allows you to reference past transactions for any wallet and select/order multiple directly:

Adding Source Nodes

Non-primary nodes are called “source” nodes, which provide the data for input values to other nodes. These can be easily added by clicking the ”+ Add Source Node” button on the right side of each step.

There are four types of source nodes:

Read Functions: these are view functions on any smart contract.
Events: these are events emitted from any contract in a transaction (derived from a previous step).
Code: these are typescript code blocks that are individually run at call time.
Encoded Write Functions: this takes a write function, and returns the encoded calldata for stuff like multicall/execute functions.

You’ll learn about how they are used in the derive methods section below.

Editing Node Inputs

Once you have added a node, you can click on the new node to pull up the edit panel. When a node is selected, any other nodes that have a purple outline are sources of data for this one, and any other nodes that have a blue outline are targets (rely on this one for data).

Derive Methods

All function inputs show up here with an input field and a “derive method” dropdown.

user_input: the user will be required to enter an input when they go through the trail
relational: this value will come from another node in the trail (a function input/output or an event). More on this later.
step_execution: this means getting the transaction hash from an execution of a specific primary node/step, and is only used in event nodes (to look up event data in that transaction).
creator_hardcoded: you hardcode a value for the user
user_wallet: the user’s connected wallet address will be used here
code: write arbitrary typescript code to transform inputs and outputs
encode_calldata: encode a write function to get it’s calldata (useful for multicall/batch and 7702 style transactions)

Before a Trail is considering valid/publishable, all non-user_input fields will have to have a value. All inputs are creator_hardcoded by default, meaning you will have to pick a value for the user.

Relational Selection

Typically, you would get relational data by calling a bunch of APIs/RPCs yourself to navigate past transactions or do eth_call’s against contracts. We simplify this by allowing you select the relevant data and create a data node for it. These data nodes will show up horizontally (to the right of the write function node). In the example above, I deploy a Split (a new contract) from a Split Factory. Then, I want to use the created Split address as the fee recipient for a Clanker token I deploy. This will create an event data node to the right, from which i can set the transaction relation to be the createSplit function step from the step beforehand. Basically, the logical flow is that: createSplit() → emits a SplitCreated() event → splitAddress from event used in input on deployToken() on Clanker. Please watch the video overview linked at the top of the page to understand this process better.

The relational popup will only show contracts that are in the Trail or in Sage memory. For transactions, it will only show past steps in the Trail.

If you set the relational input to be a read function, that read function can have a user_input input as well that will be shown together to the user all in the same step. Think of it as you’re building up all required input for a form from across different functions, which will roll up into this step.

Code Nodes

Select “code” in a derive method then ”+ new code node” to create a code node, or add it directly from the ”+ add source node” button. It comes with a default addition function, but you can edit this easily to do anything you want. Easiest way is to click the “copy” button and paste it into chatgpt/claude and ask it to write the code for you - then paste it back in here and save it. You can test out the code by running the “test code” button, or running the deno server locally for faster testing. To find relevant existing code nodes created by others, you can use the search in the ”+ Add Source Node” button/popup:

Decimals

You’ll see a “decimals” input field under any “int” type field, which must be hardcoded by the creator. On-chain there is no concept of “decimals”. In order to work around this, developers have had to add a bunch of zeros to basically simulate decimals. So for USDC (which has 6 decimals), if I want to transfer 5 USDC it will actually show up as 5000000 (5*10^6). You can see the decimals by checking the decimals() read function on any token. Decimals are commonly used for stuff like percentages as well, and can vary between 4-6 decimals. Please be very careful in setting decimals correctly. It is best to take a look at past transactions calling a given function for reference as to what number of decimals are correct. The Sage agent can still hallucinate here, so be careful and verify the amount is correct.

Arrays

Arrays can always be added to by the user, but you can define “defaults” and also “hardcoded” elements. For example, you can add yourself to a split array and the user won’t be able to remove your address. Defaults help simplify array elements on the consumer side, for example you should fill in the “decimal” defaults so the user does not have to worry about decimals on an array. Defaults can be edited by clicking “edit array defaults” next to the array value, which will pop up this form. Any new elements you add (or the user adds) will copy from these default inputs first. Arrays also come with a max length param, where you can optionally set a maximum number of elements for the user if needed.

Read Nodes

Any node (primary or source) in the trail can be turned into a “read” node by clicking the “read API” checkbox. This will tell the LLM/user that the data from that node can be useful for informing the next steps by the user. You’ll be able to see and test this in the “read data” section when you go to the trail overlook after publishing.

Adding Descriptions

You can add an intent in the “Customization” tab on the left side edit panel. This will be shown to the user as a “Creator says:” on the step.

You can also add an “intent” to each input by clicking the book icon within “edit inputs”. Here is an example of what the user sees when executing a trail on the Overlook:

Publishing

When your Trail is ready, go to the top left and click “Publish”. You will have to link your Farcaster account, which will be shown to users who use the Trail. Once done, you are ready to share the Trail link (which can be found again by clicking the share button next to “Unpublish”) and have a friend “walk” the Trail!

Any changes you make to the Trail after publishing will show up immediately. If you break the trail (i.e. inputs are not set) then the Trail will not be usable.The Trail link is just https://herd.eco/trails/{trailId}/overlook

Getting started

Creating Trails

Sharing & Using Trails

The Canvas: Creating Trails

Creating a Trail