# Identity

> NeuroChain identity — a stable address whose controlling keys can be rotated, and social recovery with guardians, a threshold and a timelock the owner can veto, all applied in consensus.

Source: https://docs.nro.world/ai/identity

A `.human` address starts as a pure function of one public key. An **identity** lets that address outlive the key: the set of keys that control it is kept in chain state, so keys can be **rotated** and, if lost, **recovered** — without changing the address, its balance, names or history.

## Before and after the first rotation

| State | Who controls the address |
|-------|--------------------------|
| Never rotated, no recovery set up | The key the address was derived from (`address = f(public key)`) |
| Identity record exists | **Only** the keys in the record. The original key stops working once it is removed |

The record is created the first time you rotate keys or set up recovery. Paid names (`.node`, `.app`, `.vault`, `.agent`) follow the identity of the `.human` wallet that owns them.

```bash
curl -s "$GATEWAY/api/v1/identity/neuro:<15 hex>.human"
# { "address": "…", "keys": ["<pk1>", "<pk2>"], "version": 2, "rotated_at": 4210, "recovery": { … } }
```

## Rotating keys

`POST /api/v1/identity/rotate` with `owner`, `add` (a public key to add, or empty), `remove` (a public key to remove, or empty), signed by a **currently active** key over:

```
nc-rotate|<owner>|<add>|<remove>|<nonce>
```

- The last remaining key cannot be removed.
- The signature covers the exact change, so no one can alter it on the way.
- Applied in consensus on every validator.

Typical move to a new device: add the new key from the old device, then remove the old key with the new one.

## Social recovery

If every key is lost, **guardians** can restore access.

### Set up

`POST /api/v1/identity/recovery/setup` — signed by an active key:

| Field | Rule |
|-------|------|
| `guardians` | One or more `.human` addresses, not your own |
| `threshold` | How many guardians must approve: 1 to the number of guardians |
| `timelock` | Blocks to wait after the threshold is reached, giving you time to veto |

Recovery is available for `.human` addresses only.

### Recover

1. **Request** — from a new device, `POST /api/v1/identity/recovery/request` with `target` (your address) and `new_key`, signed by the new key. Status `pending`.
2. **Approve** — each guardian calls `POST /api/v1/identity/recovery/approve` (`target`, `guardian`). When approvals reach the threshold the request becomes `armed`, with `executes_at = now + timelock`.
3. **Execute** — at `executes_at` every validator replaces the identity's keys with `new_key`, automatically.

At any point before execution:

| Who | Can | Endpoint |
|-----|-----|----------|
| You, with any active key | Veto it | `POST /api/v1/identity/recovery/cancel` |
| A guardian | Reject it | `POST /api/v1/identity/recovery/reject` |
| The requester | Withdraw it | `POST /api/v1/identity/recovery/withdraw` |

Reads: `GET /api/v1/identity/recovery/:addr` (configuration and open request), `GET /api/v1/identity/guardian-of/:addr` (whom you guard), `GET /api/v1/identity/recovery/initiated/:pk` (requests started by a new key).

::: tip Choose the timelock with care
The timelock is your window to notice a recovery you did not start. Too short, and colluding guardians can take the address before you react; too long, and a real recovery takes that long.
:::

## Planned

The identity record is meant to carry more than keys: a reputation built from on-chain behaviour, a zero-knowledge proof of it, and an IBC v2 packet that lets another chain read it. None of these exist yet.