> For the complete documentation index, see [llms.txt](https://shepherd-1.gitbook.io/shepherd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shepherd-1.gitbook.io/shepherd/how-to-use/setup.md).

# Setup

### Overview

Shepherd needs three things from your project:

1. Source code (<mark style="color:red;">`src/`</mark>) - Your Solidity contracts
2. Compiled artifacts (<mark style="color:red;">`out/`</mark>) - ABIs and bytecode from <mark style="color:red;">`forge build`</mark>
3. Deployment data (<mark style="color:red;">`broadcast/`</mark>) - Contract addresses from local Anvil deployment

***

### Prerequisites

Before you begin, ensure you have:

* A Foundry project with contracts in <mark style="color:red;">`src/`</mark>
* Foundry installed (<mark style="color:red;">`forge --version`</mark> to check)
* A deployment script (e.g. <mark style="color:red;">`script/Deploy.s.sol`</mark>)

***

### Step 1: Build Your Contracts

Compile your contacts to generate the required artifacts:

```markup
forge build
```

This creates the <mark style="color:red;">`out/`</mark> directory with the following structure:

```
out/
├── MyContract.sol/
│   └── MyContract.json          # ABI, bytecode, metadata
├── MyToken.sol/
│   └── MyToken.json
└── MyVault.sol/
    └── MyVault.json
```

#### Verify Build Success

Check that <mark style="color:red;">`out/`</mark> exists and contains folders ending in <mark style="color:red;">`.sol`</mark>:

```
ls out/
# Expected output: MyContract.sol/  MyToken.sol/  MyVault.sol/
```

**Common Issues:**

* Empty <mark style="color:red;">`out/`</mark> folder → Compilation failed, check error messages
* Flat structure (no <mark style="color:red;">`.sol/`</mark> folders) → Wrong compiler, must use Foundry

***

### Step 2: Deploy to Local Anvil

#### 2.1 Start Anvil

Open a terminal and start a local Anvil node (adjust according to your own codebase size):

```
anvil
```

**Keep this terminal running.** Anvil will display test accounts and listen on [<mark style="color:red;">`http://localhost:8545`</mark>](http://localhost:8545/).

#### 2.2 Deploy Your Contracts

In a new terminal, deploy your contracts with the <mark style="color:red;">`--broadcast`</mark> flag:

```
forge script script/Deploy.s.sol \
  --rpc-url http://localhost:8545/ \
  --broadcast
```

**The** <mark style="color:red;">`--broadcast`</mark> **flag is critical.** Without it, deployment data won't be saved.

#### Verify Deployment Success

Check that the <mark style="color:red;">`broadcast/`</mark> folder was created:

```
ls broadcast/
# Expected output: Deploy.s.sol/
```

Check for the deployment data:

```
ls broadcast/Deploy.s.sol/31337/
# Expected output: run-latest.json  run-<timestamp>.json
```

Expected structure:

```
broadcast/
└── Deploy.s.sol/              # Your deploy script name
    └── 31337/                 # Anvil chain ID (always 31337)
        ├── run-latest.json    # Symlink to most recent run
        └── run-1234567890.json
```

Common Issues:

* No <mark style="color:red;">`broadcast/`</mark> folder → Missing <mark style="color:red;">`--broadcast`</mark> flag, redeploy&#x20;
* No <mark style="color:red;">`31337/`</mark> folder → Deployed to wrong network, use Anvil&#x20;
* No <mark style="color:red;">`run-latest.json`</mark> → Old Foundry version or failed deployment

***

### Step 3: Package Your Project

Now package your project into a .zip file for Shepherd.

#### 3.1 Run the Packaging Commands

From your repository root, execute (if you have a different repository layout, please refer to the section below to conform to the required asset .zip structure):

```
# Clean and create assets directory
rm -rf my-assets
mkdir -p my-assets

# Copy source code and build artifacts
cp -R src my-assets/
cp -R out my-assets/

# Copy deployment data (replace <YOUR_SCRIPT_NAME> with your actual script)
mkdir -p my-assets/broadcast/<YOUR_SCRIPT_NAME>/31337
cp broadcast/<YOUR_SCRIPT_NAME>/31337/run-latest.json \
   my-assets/broadcast/<YOUR_SCRIPT_NAME>/31337/

# (Optional) Include your deployment script for reference
mkdir -p my-assets/script
cp script/<YOUR_SCRIPT_NAME> my-assets/script/

# Create the ZIP file
( cd my-assets && zip -r ../my-assets.zip . -x "*/.DS_Store" )
```

#### 3.2 Replace the Placeholder

Replace <mark style="color:red;">`<YOUR_SCRIPT_NAME>`</mark> with your actual script filename.

Example for <mark style="color:red;">`Deploy.s.sol`</mark>:

```
rm -rf my-assets
mkdir -p my-assets

cp -R src my-assets/
cp -R out my-assets/

mkdir -p my-assets/broadcast/Deploy.s.sol/31337
cp broadcast/Deploy.s.sol/31337/run-latest.json \
   my-assets/broadcast/Deploy.s.sol/31337/

mkdir -p my-assets/script
cp script/Deploy.s.sol my-assets/script/

( cd my-assets && zip -r ../my-assets.zip . -x "*/.DS_Store" )
```

#### 3.3 Verify Your Package (Example)

Check the .zip contents:

```
unzip -l my-assets.zip
```

You should see:

```
Archive:  my-assets.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  10-08-2025 15:30   src/
     1234  10-08-2025 15:30   src/MyContract.sol
     5678  10-08-2025 15:30   src/MyToken.sol
        0  10-08-2025 15:30   out/
        0  10-08-2025 15:30   out/MyContract.sol/
    45678  10-08-2025 15:30   out/MyContract.sol/MyContract.json
        0  10-08-2025 15:30   broadcast/
        0  10-08-2025 15:30   broadcast/Deploy.s.sol/
        0  10-08-2025 15:30   broadcast/Deploy.s.sol/31337/
     8901  10-08-2025 15:30   broadcast/Deploy.s.sol/31337/run-latest.json
---------                     -------
   123456                     10 files
```

Your <mark style="color:red;">`my-assets.zip`</mark> is ready!

***

### Required ZIP Structure

Shepherd expects this exact structure:

```
my-assets.zip
├── src/                              ✅ Required
│   ├── MyContract.sol
│   ├── MyToken.sol
│   └── interfaces/
│       └── IMyContract.sol
│
├── out/                              ✅ Required - Foundry build output
│   ├── MyContract.sol/               ✅ Directory named: FileName.sol
│   │   └── MyContract.json           ✅ Contains ABI, bytecode, metadata
│   └── MyToken.sol/
│       └── MyToken.json
│
└── broadcast/                        ✅ Required - Deployment data
    └── Deploy.s.sol/                 ✅ Your deploy script name
        └── 31337/                    ✅ Must be Anvil chain ID
            └── run-latest.json       ✅ Contains deployment addresses
```

#### What Each File Must Contain

<mark style="color:red;">`out/MyContract.sol/MyContract.json`</mark>

```
{
  "abi": [...],                      // Contract ABI
  "bytecode": {
    "object": "0x6080604052..."      // Creation bytecode
  },
  "deployedBytecode": {
    "object": "0x6080604052..."      // Deployed bytecode
  },
  "metadata": {
    "sources": {                     // Source file references
      "src/MyContract.sol": {...}
    }
  }
}
```

<mark style="color:red;">`broadcast/Deploy.s.sol/31337/run-latest.json`</mark>

```
{
  "transactions": [
    {
      "transactionType": "CREATE",   // Must be "CREATE"
      "contractName": "MyContract",  // Must match artifact name
      "contractAddress": "0x5FbDB..." // Deployed address
    }
  ]
}
```

***

### Step 4: Creating Your Tunnel URL

In a new terminal, run the following command to receive a Tunnel URL.

```
cloudflared tunnel --url http://localhost:8545
```

After running the command, you will find your cloudflare Tunnel URL in a box looking something like the below:

```
2025-10-09T03:21:07Z INF Requesting new quick Tunnel on trycloudflare.com...
2025-10-09T03:21:10Z INF +--------------------------------------------------------------------------------------------+
2025-10-09T03:21:10Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
2025-10-09T03:21:10Z INF |  https://sir-keys-elections-von.trycloudflare.com                                          |
2025-10-09T03:21:10Z INF +--------------------------------------------------------------------------------------------+
```

**Common Issues:**

If the command does not yield a Tunnel URL, be sure to install cloudfared (easier with brew install).

***

### Checklist

Before moving on to running a test, make sure that you have:

1. **Contract assets .zip file** ready and checked against [required .zip structure](#required-zip-structure).
2. **Cloudfare Tunnel URL**&#x20;
3. **Github repository URL**