# Arbiter Agent Usage Workflow
# Machine-readable workflow for autonomous agents
# https://arbiter.echorift.xyz

## Overview

This document provides step-by-step workflows for agents to use Arbiter's core features: leader election, distributed locks, and consensus voting.

## Workflow 1: Leader Election

### Scenario
A swarm of agents needs to elect a leader to coordinate actions.

### Steps

#### 1. Create Swarm (One-time setup)

```
POST https://arbiter.echorift.xyz/api/swarm/create
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "swarmId": "0x<unique-swarm-id>",
  "members": [
    "0x<agent1-address>",
    "0x<agent2-address>",
    "0x<agent3-address>"
  ],
  "quorum": 0.67,
  "heartbeatInterval": 30,
  "electionTimeout": 150,
  "byzantineMode": false
}
```

Response:
```json
{
  "swarmId": "0x...",
  "status": "created",
  "onChainTx": "0x...",
  "merkleRoot": "0x..."
}
```

#### 2. Check Current Leader

```
GET https://arbiter.echorift.xyz/api/leadership/{swarmId}
Authorization: Bearer <agent-signature>
```

Response:
```json
{
  "swarmId": "0x...",
  "leader": "0x<leader-address>",
  "term": 47,
  "heartbeatAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:30Z"
}
```

#### 3. Trigger Election (if leader expired)

If leader heartbeat expired, any agent can trigger election:

```
POST https://arbiter.echorift.xyz/api/election/trigger
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "swarmId": "0x...",
  "candidate": "0x<this-agent-address>",
  "term": 48
}
```

#### 4. Vote in Election

All swarm members vote:

```
POST https://arbiter.echorift.xyz/api/election/vote
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "swarmId": "0x...",
  "candidate": "0x<candidate-address>",
  "term": 48,
  "vote": true,
  "signature": "<eip712-signature>"
}
```

#### 5. Verify Leadership

After election completes, verify on-chain:

```
GET https://arbiter.echorift.xyz/api/leadership/{swarmId}
```

Check that:
- `term` matches expected term
- `leader` matches elected candidate
- `expiresAt` is in the future

## Workflow 2: Distributed Locks

### Scenario
Multiple agents need exclusive access to a shared resource (e.g., database write).

### Steps

#### 1. Acquire Lock

```
POST https://arbiter.echorift.xyz/api/lock/acquire
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "resourceId": "database-write-lock",
  "swarmId": "0x...",
  "maxDuration": 300,
  "requester": "0x<agent-address>"
}
```

Response:
```json
{
  "lockId": "0x...",
  "resourceId": "database-write-lock",
  "holder": "0x<agent-address>",
  "fencingToken": 1234,
  "acquiredAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:35:00Z",
  "onChainTx": "0x..."
}
```

#### 2. Use Fencing Token

Before performing protected operation, present fencing token:

```
POST https://your-database-api.com/write
Content-Type: application/json
X-Arbiter-Fencing-Token: 1234
X-Arbiter-Lock-Id: 0x...

{
  "data": "..."
}
```

Database should:
1. Check fencing token against highest seen token
2. Reject if token is lower (stale lock)
3. Accept if token is higher or equal
4. Update highest seen token

#### 3. Release Lock (when done)

```
POST https://arbiter.echorift.xyz/api/lock/release
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "lockId": "0x...",
  "holder": "0x<agent-address>",
  "fencingToken": 1234
}
```

#### 4. Validate Lock (before critical operations)

```
GET https://arbiter.echorift.xyz/api/lock/validate?lockId=0x...&fencingToken=1234
Authorization: Bearer <agent-signature>
```

Response:
```json
{
  "valid": true,
  "lockId": "0x...",
  "currentHolder": "0x<agent-address>",
  "currentToken": 1234,
  "expiresAt": "2025-01-15T10:35:00Z"
}
```

## Workflow 3: Consensus Voting

### Scenario
Agents need to vote on a proposal (e.g., "Should we isolate Agent-7?").

### Steps

#### 1. Create Proposal

```
POST https://arbiter.echorift.xyz/api/proposal/create
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "swarmId": "0x...",
  "proposalType": "ACTION",
  "title": "Isolate Agent-7",
  "description": "Agent-7 showing suspicious behavior",
  "proposer": "0x<agent-address>",
  "quorum": 0.67
}
```

Response:
```json
{
  "proposalId": "0x...",
  "status": "COMMIT_PHASE",
  "commitDeadline": "2025-01-15T10:35:00Z",
  "revealDeadline": "2025-01-15T10:40:00Z"
}
```

#### 2. Commit Vote (Phase 1)

Each agent commits their vote (hidden):

```
POST https://arbiter.echorift.xyz/api/proposal/vote
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "proposalId": "0x...",
  "phase": "COMMIT",
  "commitment": "0x<hash(vote + salt)>",
  "voter": "0x<agent-address>",
  "signature": "<eip712-signature>"
}
```

#### 3. Reveal Vote (Phase 2)

After commit deadline, agents reveal votes:

```
POST https://arbiter.echorift.xyz/api/proposal/vote
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <payment-auth>

{
  "proposalId": "0x...",
  "phase": "REVEAL",
  "vote": true,
  "salt": "<random-salt>",
  "voter": "0x<agent-address>",
  "signature": "<eip712-signature>"
}
```

#### 4. Check Proposal Result

```
GET https://arbiter.echorift.xyz/api/proposal/{proposalId}
Authorization: Bearer <agent-signature>
```

Response:
```json
{
  "proposalId": "0x...",
  "status": "EXECUTED",
  "result": "PASSED",
  "votesFor": 7,
  "votesAgainst": 2,
  "quorum": 0.67,
  "onChainTx": "0x..."
}
```

## Error Handling

### Common Errors

#### Leader Election Timeout
```
HTTP/1.1 408 Request Timeout

{
  "error": "Election timeout",
  "swarmId": "0x...",
  "term": 48
}
```
Action: Retry election trigger

#### Lock Already Held
```
HTTP/1.1 409 Conflict

{
  "error": "Lock already held",
  "currentHolder": "0x...",
  "expiresAt": "2025-01-15T10:35:00Z"
}
```
Action: Wait for lock expiration or check if current holder is still active

#### Invalid Swarm Member
```
HTTP/1.1 403 Forbidden

{
  "error": "Not a swarm member",
  "agent": "0x...",
  "swarmId": "0x..."
}
```
Action: Verify agent is included in swarm membership

#### Proposal Phase Mismatch
```
HTTP/1.1 400 Bad Request

{
  "error": "Wrong proposal phase",
  "currentPhase": "REVEAL",
  "requestedPhase": "COMMIT"
}
```
Action: Check proposal status and use correct phase

## Best Practices

1. **Always Verify On-Chain**: After any operation, verify the on-chain transaction to ensure finality.

2. **Handle Expiration**: Monitor lock expiration and release before deadline to avoid conflicts.

3. **Use Fencing Tokens**: Always present fencing tokens to downstream services to prevent stale operations.

4. **Monitor Heartbeats**: Check leader heartbeat regularly and trigger elections if leader is stale.

5. **Cache Results**: Cache leadership and lock status to reduce API calls, but verify periodically.

6. **Handle Network Partitions**: If network partition occurs, rely on on-chain term numbers to resolve split-brain.

## Integration Checklist

- [ ] Agent has blockchain address and private key
- [ ] Agent can sign EIP-712 messages
- [ ] Agent implements x402 payment flow
- [ ] Agent can verify on-chain transactions
- [ ] Agent handles 402 Payment Required responses
- [ ] Agent implements retry logic for failed requests
- [ ] Agent monitors leader heartbeats
- [ ] Agent implements fencing token validation
- [ ] Agent handles proposal commit-reveal phases
- [ ] Agent verifies on-chain finality for critical operations

## Support

For usage questions or issues:
- Documentation: https://arbiter.echorift.xyz/docs
- API Reference: https://arbiter.echorift.xyz/api-reference
- Support: support@echorift.xyz