fulfill-git-escrow

# Fulfill Git Escrow

You are helping the user fulfill a git escrow bounty. This means submitting code that passes a failing test suite to claim the escrowed token reward.

There are two modes:
- **Mode A (Write + Submit)**: You write the solution code, commit it, and submit. This is the default when no `--solution-repo` is provided by the user.
- **Mode B (Submit Existing)**: The user already has a solution repo and commit. You just submit the fulfillment.

Determine the mode from the user's input:
- If they provide `--solution-repo`, use **Mode B**.
- Otherwise, use **Mode A**.

The escrow UID is always required.

## Step 1: Check CLI availability

Run `git-escrows --help` to verify the CLI is installed. If it fails, try `npx git-escrows --help` or `bunx git-escrows --help`. Use whichever works for all subsequent commands. If none work, tell the user to install with `npm i -g git-escrows`.

## Step 2: Check .env configuration

Check if a `.env` file exists in the current directory. If not, tell the user they need one and suggest running:
```
git-escrows new-client --privateKey "0x..." --network "sepolia"
```

## Step 3: Validate the escrow

Run `git-escrows list --verbose --format json` and find the escrow matching the provided UID. Confirm:
- The escrow exists and is **open**
- Note the test repo URL, test commit hash, reward amount, and oracle address

If no escrow UID was provided, ask the user for one. You can help them browse with `git-escrows list --status open`.

## Mode A: Write Solution + Submit

### A1: Understand the tests

Clone or read the test repository to understand what the tests expect:
1. Identify the test repo URL and commit from the escrow details
2. Clone it to a temporary location: `git clone <url> /tmp/escrow-tests-<uid> && cd /tmp/escrow-tests-<uid> && git checkout <commit>`
3. Read the test files to understand:
   - What functions/modules/APIs the tests import
   - What behavior they assert
   - What test framework is used
   - The project structure expected

### A2: Write the solution

In the **current working directory** (or a subdirectory the user specifies):
1. Create/modify files to implement the code that will make the tests pass
2. Follow the project structure the tests expect (e.g., if tests import from `src/math.ts`, create that file)
3. Include any necessary config files (package.json, Cargo.toml, etc.)
4. Ensure the test framework's dependencies are accounted for

### A3: Commit and get repo details

1. Stage and commit the solution: `git add -A && git commit -m "solution for escrow <uid>"`
2. Get the commit hash: `git rev-parse HEAD`
3. Get the remote URL: `git remote get-url origin`
   - If no remote exists, ask the user to push to a public git repo and provide the URL

### A4: Submit the fulfillment

```
git-escrows fulfill \
  --escrow-uid "<uid>" \
  --solution-repo "<repo-url>" \
  --solution-commit "<commit-hash>"
```

## Mode B: Submit Existing Solution

### B1: Gather parameters

From the user's input, extract:
- `--solution-repo`: The git repo URL with the solution
- `--solution-commit`: The commit hash of the solution

If either is missing, ask the user.

### B2: Submit the fulfillment

```
git-escrows fulfill \
  --escrow-uid "<uid>" \
  --solution-repo "<repo-url>" \
  --solution-commit "<commit-hash>"
```

## Step 4: Report results (both modes)

After successful execution:
- Report the **Fulfillment UID** prominently
- Explain that the oracle will now automatically test the solution
- Provide the collect command for after arbitration passes:
  ```
  git-escrows collect --escrow-uid <escrow-uid> --fulfillment-uid <fulfillment-uid>
  ```
- Suggest checking status with: `git-escrows list --verbose`

If the command fails, help diagnose the issue (escrow already fulfilled, wrong network, key not registered, etc.). If the user's git key isn't registered, suggest `git-escrows register-key`.