[Discussion] Bread Wallet Backend

### 2.6 Backend: how an entry is stored

The server keeps one store per `profileId`. One record is one encrypted entry, addressed by `(feature, hashedKey)`. The server stores each field of the encrypted entry as its own typed column and the ciphertext as bytes. Nothing is stored as a JSON string.

| Column | Type | Value | Set by |
|---|---|---|---|
| `feature` | text | `accounts`, `contacts` or `preferences` | client |
| `hashedKey` | bytes, 32 | decoded from the hex in the path | client |
| `version` | integer | encrypted entry format version | client |
| `kdf` | text | `scrypt` | client |
| `N`, `r`, `p`, `dkLen`, `saltLen` | integer | scrypt parameters and salt length | client |
| `blob` | bytes | salt, nonce and ciphertext, decoded from base64 | client |
| `updatedAt` | integer | Unix ms of the last write | server |

Example record:

| feature | hashedKey | version | kdf | N | r | p | dkLen | saltLen | blob | updatedAt |
|---|---|---|---|---|---|---|---|---|---|---|
| `accounts` | `3f9a…c21e` | 1 | `scrypt` | 131072 | 8 | 1 | 32 | 16 | 156 bytes | 1757400000000 |

The server validates on write:

1. `feature` is on the allowlist.
2. `version` is a known version.
3. `kdf` is on the allowlist.
4. `N` is 2^14 to 2^20, `r` is 1 to 16, `p` is 1 to 4, `dkLen` is 16 or 32, `saltLen` is 16 to 32.
5. `blob` decodes from base64, its length is at least `saltLen + 12 + 16`, and under the cap in 2.7.

The server never looks inside `blob`. `updatedAt` is server time and exists for ETags and retention, not for merge. Merge uses the timestamps inside the plaintext, which the server cannot read. A write to an existing `(feature, hashedKey)` replaces it. There is no per-entry concurrency check, the timestamps in the plaintext resolve a race on the client.

On read, the server re-encodes `blob` as base64 and returns the same flat object the client sent.

Alongside the entries, a profile store holds the profile's sync public key, its creation time, its last-seen time, and the open login nonces.

### 2.7 Limits

| Limit | Value |
|---|---|
| Max `blob` size, decoded | 4 KiB |
| Max entries per feature per profile | 1000 |
| Max batch size | 100 entries |
| Max request body | 512 KiB |

The server rejects a request that exceeds a limit with `413`.

## 3. Authentication API

All requests use `https://api..miden.wallet` as the base URL. All bodies are JSON.

### 3.1 `POST /v1/auth/nonce`

Request:

```json
{ "publicKey": "" }
```

Response `200`:

```json
{ "nonce": "<32 random bytes, hex>", "expiresAt": 1757400300000 }
```

The nonce is valid for 5 minutes. The nonce is single use.

### 3.2 `POST /v1/auth/login`

Request:

```json
{
"publicKey": "",
"message": "miden-sync:login::",
"signature": ""
}
```

The server does these checks in order:

1. The nonce exists and is not expired and is not used.
2. The message has the exact format above with that nonce and that public key.
3. The signature verifies for the public key.

Response `200`:

```json
{
"accessToken": "",
"expiresIn": 3600,
"profileId": ""
}
```

The JWT is signed with HS256 with the `JWT_SIGNING_KEY` secret. Claims: `sub` = `profileId`, `pk` = public key, `iat`, `exp`. The client refreshes when 90% of `expiresIn` has passed.

### 3.3 Authorization

Every other endpoint requires:

```
Authorization: Bearer
```

The server reads `profileId` from the token. The client cannot address another profile.

## 4. Storage API

`{feature}` is one of the allowlisted names in 2.3. `{hashedKey}` is a 64-character lowercase hex string. In every body below, `` stands for the flat encrypted entry object from 2.4.

### 4.1 `GET /v1/storage/{feature}`

Returns all entries of the feature for the profile.

Request headers, optional:

```
If-None-Match:
```

Response `200`:

```json
{
"entries": [
{ "hashedKey": "", "entry": , "updatedAt": 1757400000000 }
]
}
```

Response headers:

```
ETag: ""
```

The `ETag` is a hash over every `(hashedKey, updatedAt)` pair in the feature. Response `304` with no body when it equals `If-None-Match`.

### 4.2 `GET /v1/storage/{feature}/{hashedKey}`

Response `200`:

```json
{ "hashedKey": "", "entry": , "updatedAt": 1757400000000 }
```

Response `404` when the entry does not exist.

### 4.3 `PUT /v1/storage/{feature}/{hashedKey}`

Upsert one entry.

Request:

```json
{ "entry": }
```

Response `200`:

```json
{ "hashedKey": "", "updatedAt": 1757400000000 }
```

### 4.4 `PUT /v1/storage/{feature}`

Batch upsert. All entries are written in one transaction.

Request:

```json
{ "entries": { "": , "": } }
```

Response `200`:

```json
{ "written": 2, "updatedAt": 1757400000000 }
```

### 4.5 `POST /v1/storage/{feature}/delete`

Batch delete. All entries are deleted in one transaction.

Request:

```json
{ "hashedKeys": ["", ""] }
```

Response `200`:

```json
{ "deleted": 2 }
```

### 4.6 `DELETE /v1/storage/{feature}/{hashedKey}`

Delete one entry. Response `204`.

### 4.7 `DELETE /v1/storage/{feature}`

Delete all entries of the feature. Response `204`.

### 4.8 `DELETE /v1/profile`

Delete the profile and all its features. The wallet exposes this as "Delete my backup" in settings. Response `204`. A later login creates a new empty profile with the same `profileId`.

## 5. On-ramp API

### 5.1 Provider model

Fiat providers differ in how the integrator binds a wallet address to a widget session. The common shapes are:

- The client builds a widget URL and the integrator returns an HMAC over it with a merchant secret.
- The integrator creates a session with the provider's API using a merchant secret and returns a session id or token that the widget consumes.
- The integrator signs a JSON payload with a merchant secret and the widget receives the signed payload.

All three reduce to: the client sends provider-specific input, the server validates it, stamps the profile's addresses with a merchant secret, and returns provider-specific output. The server treats the input and output as opaque to the shared layer.

Each provider is one module that implements this interface:

| Function | Responsibility |
|---|---|
| `validate(input)` | Reject input that names a host, merchant key, or parameter the provider module does not expect. Extract the wallet addresses the session will pay out to. |
| `stamp(input, secret)` | Produce the provider-specific output, for example a signature, a session token, or a signed payload. |

The shared layer owns authentication, the address attestation in 5.3, rate limiting, and secret lookup. Each provider has one secret, `ONRAMP__SECRET`, and a module never reads a secret that is not its own.

Provider ids are lowercase slugs. The list of enabled providers per environment is a plain variable, `ONRAMP_PROVIDERS`.

### 5.2 `POST /v1/onramp/{provider}/session`

Requires a bearer token. `{provider}` must be in `ONRAMP_PROVIDERS`, otherwise `404`.

Request:

```json
{
"flow": "buy",
"input": { "...": "provider-specific" },
"attestations": [
{ "address": "", "signature": "" }
]
}
```

| Field | Meaning |
|---|---|
| `flow` | `buy` for on-ramp, `sell` for off-ramp |
| `input` | Provider-specific input. The shared layer passes it to the provider module unchanged. |
| `attestations` | One entry per wallet address the session pays out to or from. See 5.3. |

The shared layer does these checks in order:

1. `flow` is `buy` or `sell`.
2. The provider module's `validate(input)` accepts the input and returns the set of addresses in it.
3. Every address is a valid Miden bech32 address.
4. Every address has a valid attestation, see 5.3. Every attestation names an address that is in the input.
5. The provider module's `stamp(input, secret)` succeeds.

Response `200`:

```json
{ "output": { "...": "provider-specific" } }
```

Response `403` when a check fails. The body says which check failed. Response `502` when the provider's API is unreachable or returns an error, for providers whose `stamp` calls out.

### 5.3 Address attestation

The server cannot read the encrypted entries, so it cannot know which addresses belong to a profile. The client proves ownership by signing each address with the sync key:

```
message = "miden-sync:onramp-address:" + profileId + ":" + address
attestation = secp256k1_sign(sync_private_key, sha256(message))
```

The server verifies each attestation against the `pk` claim of the token. Every address the provider module extracted from the input must have a valid attestation. This prevents a caller from creating a session that pays out to an address the caller does not control under our merchant credentials. The check is the same for every provider.

## 6. Estimated sizes

**Per profile.** About 100 bytes plaintext per account or contact and 70 for preferences, plus 44 bytes of encryption overhead per entry.

| Profile | Contents | Stored |
|---|---|---|
| New | 1 account | ~0.2 KiB |
| Typical | 3 accounts, 10 contacts | ~2 KiB |
| Heavy | 10 accounts, 50 contacts | ~9 KiB |

**Per fleet.** 100k users is under 1 GiB. 1M users is under 10 GiB.

**Requests.** The estimate assumes 10 unlocks per day, one `GET` per feature per unlock, a batch `PUT` on one unlock in ten, and one on-ramp session per user per month. Most `GET` calls answer `304` with no body because of `If-None-Match`.

| Users | Requests per month | Average requests per second |
|---|---|---|
| 10k | ~12M | ~5 |
| 100k | ~120M | ~46 |
| 1M | ~1.2B | ~460 |

## 7. Cloudflare Workers vs AWS

Two deployment shapes were compared: Cloudflare Workers with Durable Objects, and a conventional AWS deployment with containers on ECS or EC2, an application load balancer, and RDS Postgres. AWS Lambda is not in the comparison. Prices are public list prices at the time of writing and are estimates. Verify before budgeting.

### 7.1 Monthly cost

| Users | Cloudflare Workers | AWS, minimal | AWS, production |
|---|---|---|---|
| 10k | ~$7 | ~$60 | ~$200 |
| 100k | ~$55 | ~$80 | ~$250 |
| 1M | ~$540 | ~$250 | ~$500 |

How the numbers are built:

- **Cloudflare.** $5 plan. Workers requests at $0.30 per million past 10M. Durable Object requests at $0.15 per million past 1M. Storage and rows are inside the included tiers at every row of the table. No egress charge.
- **AWS, minimal.** One small ARM instance, one single-AZ RDS instance, one load balancer, NAT gateway, secrets manager. This shape has no redundancy and is only for staging.
- **AWS, production.** Two instances across two AZs, multi-AZ RDS, load balancer with LCUs, NAT gateway, egress at $0.09 per GB, backups. At 1M users the egress line alone is about $100 since every `GET` that is not a `304` returns data.

While picking the provider we need to keep in mind that it way easier to manager workers vs aws where you have to scale manually create replicas etc.