# AISFOR-CHAIN Reward Service Integration

This guide is for AISFOR ecosystem services that submit PoSS reward events to AISFOR-CHAIN.

## Endpoints

- Dry-run: `POST /api/reward/dry-run`
- Live simulation write: `POST /api/reward`
- Manifest: `GET /api/reward/manifest`
- Readiness: `GET /api/reward/readiness`

Use dry-run first. Dry-run requires service authentication but does not write to the Reward Ledger.

## Authentication

Use HMAC signature v2 headers:

- `X-AISFOR-SERVICE`
- `X-AISFOR-TIMESTAMP`
- `X-AISFOR-NONCE`
- `X-AISFOR-SIGNATURE`

The signing helper is available at:

```js
const { postRewardPayload } = require('../lib/rewardIntegrationClient');
```

## CLI Example

Run a dry-run request with the configured service key:

```powershell
node scripts\reward-client-dry-run-example.js --service=AISFOR --base-url=http://127.0.0.1:4317
```

Run all configured service dry-run smoke checks:

```powershell
node scripts\reward-http-dry-run-smoke.js --base-url=http://127.0.0.1:4317
```

Show the current service rollout plan:

```powershell
node scripts\reward-rollout-status.js
```

Rehearse the controlled live simulation canary without writing:

```powershell
node scripts\reward-live-canary.js --service=AISFOR --base-url=http://127.0.0.1:4317
```

Check whether the live canary is allowed:

```powershell
node scripts\reward-live-canary-preflight.js
```

Check the latest canary result after dry-run or live execution:

```powershell
node scripts\reward-live-canary-postcheck.js
```

Show the current execution permit for a single controlled live simulation canary:

```powershell
node scripts\reward-live-canary-permit.js
```

Operators may record or revoke manual approval from `/admin/rewards`. Approval only records intent and the permitted command; it does not run the live simulation write.

Run the canary through the approval-gated wrapper after operator approval:

```powershell
node scripts\reward-live-canary-approved-run.js --base-url=http://127.0.0.1:4317 --confirm=LIVE_SIMULATION_WRITE
```

The wrapper refuses to run unless approval is recorded, the current permit still matches the approval, and the explicit confirmation token is present.

The lower-level canary command remains available for diagnostics:

```powershell
node scripts\reward-live-canary.js --service=AISFOR --base-url=http://127.0.0.1:4317 --confirm=LIVE_SIMULATION_WRITE
```

For a future live simulation write:

```powershell
node scripts\reward-client-dry-run-example.js --service=AISFOR --base-url=http://127.0.0.1:4317 --live=true
```

Live writes must remain simulation-only until testnet/mainnet policy is approved.

## Required Payload Fields

- `sourceService`
- `actorId`
- `category`
- `actionType`
- `idempotencyKey`

Recommended trace fields:

- `eventKey`
- `refType`
- `refId`
- `externalProofHash`
- `pointAmount`
- `sourceCreatedAt`
- `note`

## Guardrails

- Use one stable `idempotencyKey` per source event.
- Exclude refunds and cancelled events.
- Mark self-trading or suspicious commerce for review.
- Use dry-run before enabling live reward writes.
