> For the complete documentation index, see [llms.txt](https://docs.alignedlayer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alignedlayer.com/wallet-as-a-service/integration-notes.md).

# Integration notes

Details that are easy to get wrong when integrating Aligned, and expensive to change once users have wallets.

## Passkeys belong to your domain

A passkey is bound to the relying-party id (rpId) it was created under. By default `webPasskeyAdapter()` uses the page's hostname. A passkey created on `app.example.com` cannot sign on `example.org`, or on another hostname under the same domain unless you set `rpId` to the shared parent:

```ts
webPasskeyAdapter({ rpId: 'example.com' }); // works on app.example.com and example.com
```

Choose the rpId before launch. If it changes later, every existing user has to add the new origin as a device or go through recovery. See [Keys and recovery](https://docs.alignedlayer.com/wallet-as-a-service/keys-and-recovery.md).

## Passkeys are ES256 only

Registration asks the authenticator for ES256 (P-256) keys only, because the account verifies P-256 signatures on chain. Chrome logs a warning that RS256 is missing; that is expected. Adding RS256 would let an authenticator create a key the wallet can never use.

## The confirmation screen runs in your page

`<AlignedModal />` shows users what they approve before the passkey prompt: the recipient, the amount, decoded token approvals. It catches honest mistakes, such as an unexpected unlimited approval. It cannot protect users from the page it runs in: a compromised page can skip it or call the SDK directly. Keep your page's script supply chain as tight as for any wallet integration.

## One chain per wallet

A wallet is set up on one chain, the one it was created on. The address is the same on every EVM chain, but on any other chain no key can move funds out of it: the key that created the account is discarded at creation. Tokens sent to the address on another chain are lost. Show the chain wherever your app shows the address for deposits.

## Failed transactions

`sendTransaction` returns once the transaction is mined and succeeded. When it does not, the error says whether anything reached the chain:

| HTTP | Code                  | Sent on chain? | Meaning                                                                                                                                                |
| ---- | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 422  | `simulation_reverted` | No             | The call reverts in the gas estimate. `error.details.revert_data` holds the revert data. Nothing was paid.                                             |
| 502  | `gas_estimate_failed` | No             | The estimate failed for another reason, such as an RPC outage. Safe to retry.                                                                          |
| 502  | `tx_reverted`         | Yes            | Mined and reverted, for example because state changed after the estimate. `error.details.tx_hash` names it.                                            |
| 504  | `receipt_timeout`     | Yes            | Not mined within the wait. `error.details.tx_hash` names it, and it may still land. Check it before retrying: an immediate retry can conflict with it. |

A transaction rejected before sending is fully signed, not cancelled: it stays valid until the wallet's next transaction.

## Gas

Aligned submits every transaction and pays its gas. For scale, measured on an Ethereum mainnet fork with passkey keys:

* creating a wallet: about 295,000 gas;
* the app's beacon, once per app and chain, on its first wallet: about 240,000 gas;
* each transaction: about 72,000 to 88,000 gas on top of the call itself, for the account's `execute` and its signature checks.

## Automated testing

* **Email codes.** A local backend serves sent mail at `/dev/mailbox`, and `test@aligned.com` always gets the code `000000`. A self-hosted backend can give fixed codes to an allowlist with `EMAIL_OTP_FIXED_CODE` and `EMAIL_OTP_FIXED_CODE_EMAILS`.
* **Passkeys.** Chromium's virtual authenticator (`WebAuthn.addVirtualAuthenticator` over the DevTools Protocol, or Playwright's CDP session) completes passkey prompts without user interaction.
