# Developer Client Notes

This file contains low-level notes for building external clients or debugging the Contractless RPC client flow. It is not required for normal node setup.

## RPC Clients

RPC clients are not treated the same as mining nodes. A client must follow the handshake format exactly, or the server may classify it as a node/miner instead of a client. When that happens, client tools can hang, be rejected or behave unexpectedly.

### Required Client Handshake Rules

1. Use a valid wallet address and signature in the handshake.

- The client must load a real wallet locally.
- The wallet encryption key is used only locally to open the wallet and sign the handshake.
- The wallet encryption key is not sent over the stream.
- The wallet address is sent as part of the handshake identity.

2. The opening handshake message must be `aced`.

- The client signs the hash of `aced`.
- The server verifies that signature against the wallet address supplied in the handshake.

3. A client must advertise its IP with port `0`.

- Example: `127.0.0.1:0`
- This is the rule that tells the server the connection is a client-style RPC connection rather than a mining node connection.
- The server checks whether the submitted `ip:port` is externally reachable.
- If the submitted port is open, the connection is treated as a miner/node.
- If the submitted port is `0` or not reachable, the connection is treated as a client.

4. The client timestamp must be within 1 second of the server timestamp.

- If the timestamp is too far off, the handshake is rejected.

5. The submitted IP must match the caller IP seen by the server.

- The server compares the claimed IP in the handshake against the actual remote peer IP.

### Handshake Byte Layout

The client sends:

- `2` bytes: message (`aced`)
- `65` bytes: recoverable signature
- `21` bytes: wallet address
- `4` bytes: timestamp
- `18` bytes: `ip:port`

Total client handshake size:

- `110` bytes

The server returns:

- `2` bytes: message
- `65` bytes: recoverable signature
- `21` bytes: wallet address

Total server handshake size:

- `88` bytes

### Server Return Messages

After the client handshake is accepted:

- miner/node connections receive `face`
- client connections receive `ecaf`

RPC clients should expect `ecaf`.

If you do not follow the client rules above, especially the `ip:0` rule, the server can classify your connection as a mining/node connection instead of a client connection. That will cause errors for standalone RPC tools.

### RPC Request Format After Handshake

After the handshake succeeds, the client sends:

- `1` byte: command
- `3` bytes: request uid
- command-specific payload bytes if required

Normal RPC replies are returned as:

- `1` byte: reply command (`111`)
- `3` bytes: request uid
- `2` bytes: payload length
- payload bytes

### Practical Note For Standalone Tools

Standalone tools in `src/bin` should behave like clients, not mining nodes. Their handshake should therefore:

- use a real wallet
- send `aced`
- sign it correctly
- advertise `your_ip:0`

If a standalone tool advertises a real RPC/mining port instead of `0`, the server may treat it as a node connection and the tool can fail in confusing ways.