# trident-sdk
End-user SDK for depositing into Trident and executing cross-chain spends through the Trident delivery service.
`TridentClient` covers the common user flow. The crate also exposes lower-level EVM bindings and protobuf types for applications that need direct contract reads, revert decoding, custom signing, or raw gRPC access.
## Scope
- Build a `TridentClient` by registering per-domain chains
- Prepare and submit deposits
- Submit spend intents through the delivery service and execute returned attestations
- Access curated spender/depositor EVM bindings under `evm::abi`
- Access EIP-712 spend-intent signing helpers under `evm::signing`
- Access generated protobuf messages and gRPC client types under `proto`
## Current support
- EVM chain handlers today
- `ChainAddress` is the SDK's chain-agnostic address trait and is implemented for `alloy_primitives::Address` today
- `Domain` values are Trident domain identifiers, not raw chain IDs
## Typical flow
1. Build a `TridentClient` with `TridentClientBuilder` and register the domains you want to use.
2. Call `deposit` to prepare a source-chain deposit, then `Deposit::send` to submit it.
3. Build a `SpendRequestBuilder` and call `spend`.
4. Submit the returned `SpendAttestation` on the destination chain with `SpendAttestation::send`.
`deposit` prepares a source-chain deposit into the domain's Trident deposit contract. `Deposit::send` submits the on-chain transaction and automatically approves the deposit contract first if the current ERC-20 allowance is too low.
`spend` builds a spend intent, fills in the source spender, Trident contract addresses, random salt, and, unless explicitly set on the builder, the max fee and expiry height. It signs the intent, submits it to the delivery service, and returns a `SpendAttestation`.
## Examples
Keep runnable examples in `examples/` rather than turning this README into a tutorial.
Current examples:
- `deposit_evm.rs`: build a client for one EVM domain, prepare a deposit, and submit it
- `spend_evm.rs`: build a client across two EVM domains, submit a spend, and relay the returned attestation
- `balance_semantics.rs`: compare `TridentClient::get_balance` with on-chain `TridentDeposits::depositedAmount`
## Balance semantics
`TridentClient::get_balance` returns the delivery-service balance tracked by Trident for an account, domain, and token.
That is not the same value as `evm::abi::TridentDeposits::depositedAmount`, which reads the source-side on-chain bookkeeping balance in the `TridentDeposits` contract. Applications often need both views, but they should not be treated as interchangeable.
## Lower-level modules
Use `evm::abi` for curated spender/depositor contract bindings, events, errors, and direct reads such as `TridentDeposits::depositedAmount` or attestation validation helpers.
Use `evm::signing` for Trident's EIP-712 spend-intent signing logic outside `TridentClient`.
Use `proto` for the raw generated protobuf messages and gRPC client types.
## Notes
- Token amounts are expressed in the token's atomic units.
- `SpendRequestBuilder` lets callers override the auto-resolved max fee, expiry height, and destination caller.