# ChimeraSettle Gateway (`chsettle`)

ChimeraSettle is a dummy settlement gateway for dev/test flows.
It simulates settlement outcomes deterministically, without real fund movement.

## What It Simulates

- Fast success
- Slow success
- Immediate failure
- Timeout-like failure
- Stuck pending/processing
- Retry-like progression before success
- Deterministic chaos bucket

## How Behavior Is Chosen

Selection order:

1. Explicit scenario override from request metadata:
- `chsettle_scenario`
- `scenario` (alias)

2. Amount bucket routing based on:
- `amount_minor % 1000`

3. Hash fallback using idempotency key (if amount cannot be parsed)

## Scenario Overrides

Accepted override values (aliases supported in code):

- `fast_success`
- `slow_success`
- `fail_immediate`
- `fail_timeout`
- `stuck_pending` (also `stuck`)
- `retry_then_success`
- `webhook_delayed_success`
- `slow_then_fail`
- `partial_progress_stuck`
- `chaos`

## Amount Bucket Map (`%1000`)

| Slot range | Scenario |
|---|---|
| `000-099` | `fast_success` |
| `100-199` | `slow_success` |
| `200-299` | `fail_immediate` |
| `300-399` | `fail_timeout` |
| `400-499` | `stuck_pending` |
| `500-599` | `retry_then_success` |
| `600-699` | `webhook_delayed_success` |
| `700-799` | `slow_then_fail` |
| `800-899` | `partial_progress_stuck` |
| `900-999` | `chaos` (deterministic by idempotency key) |

## Request Usage

### Through Connector `SubmitOperation`

Use operation param:

- `scenario` (optional)

or put it inside `metadata` as:

- `chsettle_scenario`

### Through Gateway `SubmitTransfer`

Set metadata key directly:

- `chsettle_scenario`

## Dev Environment

Compose service:

- `dev-chsettle-gateway`

Ports:

- gRPC: `50080`
- metrics: `9406`

Start only this gateway:

```bash
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d dev-chsettle-gateway
```

## Logging

ChimeraSettle emits:

- `info` logs for scenario decisions and transition milestones
- `warn` logs for recoverable/non-fatal errors
- `error` logs for startup-fatal failures
- detailed `debug` logs for request execution tracing
