> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tayho.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Relayed actions

> Prepare, review, sign, submit, and track Tayho sessions, margin, vault, and staking actions.

# Relayed actions

Every Tayho write currently goes through the Tayho relayer. The SDK never asks a wallet provider to
broadcast a transaction and does not expose a direct-broadcast fallback.

## Write lifecycle

Each `prepare…` method performs the available execution-critical reads, creates an EIP-712 payload,
and returns a frozen prepared action. Review its `action`, human-readable `consequence`, optional
permit fields, and `typedData` before calling `submit()`.

```ts theme={null}
const prepared = await actionClient.positions.prepareAddMargin({
  positionId: 42n,
  marginTokens: 50_000_000n,
});

console.info(prepared.consequence);
const receipt = await prepared.submit();
const finalStatus = await receipt.wait({
  timeoutMs: 120_000,
  pollIntervalMs: 1_000,
});
```

Preparation chooses a random nonce and a deadline five minutes in the future unless you provide
them. Supplying explicit values is useful for deterministic orchestration, but the deadline must
still be in the future and the nonce must be unused.

<Warning>
  Prepared actions authorize real economic consequences. Render the consequence and relevant
  amounts to the user before requesting a signature.
</Warning>

## Supported actions

| Family   | Prepare                      | Prepare and submit    | Required input                                         |
| -------- | ---------------------------- | --------------------- | ------------------------------------------------------ |
| Session  | `sessions.prepareAuthorize`  | `sessions.authorize`  | Expiry, maximum spend, maximum order quantity, markets |
| Session  | `sessions.prepareRevoke`     | `sessions.revoke`     | Optional trader and session key                        |
| Position | `positions.prepareAddMargin` | `positions.addMargin` | Position ID and collateral amount                      |
| Vault    | `vault.prepareDeposit`       | `vault.deposit`       | Token amount and minimum shares                        |
| Vault    | `vault.prepareWithdraw`      | `vault.withdraw`      | Share amount and minimum tokens                        |
| Staking  | `staking.prepareStake`       | `staking.stake`       | TAYHO amount                                           |
| Staking  | `staking.prepareUnstake`     | `staking.unstake`     | TAYHO amount and optional receiver                     |
| Staking  | `staking.prepareClaim`       | `staking.claim`       | Optional account and receiver                          |

The connected signer supplies the account, trader, receiver, or session key when an optional value
is omitted. Methods reject inputs where the signer is not authorized for the signing role.

## Direct on-chain preparation

When a `chainReader` or `rpc` is configured, preparation reads the relevant contracts at one block.
Depending on the action, it verifies balances, allowances, previews, unused nonce bits, session
limits, position state, and deadlines. Without one, the SDK uses the API's bounded action-read
endpoint.

Session authorization can compose:

* an EIP-2612 collateral approval when the ERC-20 allowance to Permit2 is insufficient; and
* a Permit2 authorization bounded by the session spend and expiry.

Vault deposits and staking can compose EIP-2612 permits when advertised by the deployment. Existing
sufficient allowances need no permit. Add-margin preparation verifies the existing collateral
balance and Permit2 allowance; it does not create a new permit.

## Submission and receipts

`submit()` signs lazily. A prepared action keeps one signed envelope and one idempotency key, so
repeating `prepared.submit()` after a transport error does not create a different action.

An `ActionReceipt` exposes:

* `id`, the action hash;
* `receipt`, the capability required to read its status;
* the acceptance `state` and `idempotencyKey`;
* `get()` for one status read; and
* `wait()` for bounded authenticated polling.

Action states are `received`, `validating`, `queued`, `broadcast`, `confirmed`, `indexed`,
`cancelled`, `expired`, `rejected`, or `reverted`. `wait()` stops at `indexed`, `cancelled`,
`expired`, `rejected`, or `reverted`, defaults to a 120-second timeout and one-second poll interval,
and accepts an `AbortSignal`.

Immediate actions do not have a cancellation API. Session revocation is itself an immediate action;
order cancellation is documented separately in [Orders](/public/sdk/orders).

## Convenience methods

Methods without the `prepare` prefix prepare and submit in one call. They are useful after your
application has already established a review step:

```ts theme={null}
const receipt = await actionClient.staking.stake({
  amount: 10_000_000_000_000_000_000n,
});
```

Use the two-step API whenever you need to display the typed data, consequence, permit, or
idempotency key before submission.