> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.
# SocketFi Transactions: How Blockchain Actions Work
> Learn how SocketFi transactions work — from asset transfers and contract calls to the five core principles that govern every on-chain action.
Transactions are the mechanism through which users interact with the blockchain. Every asset transfer, smart contract invocation, token approval, staking operation, or governance vote ultimately produces a transaction. SocketFi simplifies this process end-to-end — your application defines what should happen, and SocketFi handles how it happens: constructing the transaction, routing it through user approval, authorizing it through the smart wallet, and submitting it to the Soroban network.
## What is a transaction?
A transaction is a request to perform a state-changing action on the blockchain. SocketFi supports a wide range of transaction types, all executed through the same unified SDK interface.
Move tokens between wallets — USDC, USDT, XLM, or any supported Soroban token contract.
Invoke any method on a deployed Soroban contract, passing typed arguments directly from your application.
Interact with DeFi protocols — stake tokens, provide liquidity, deposit into lending pools, claim rewards, or participate in swaps.
Perform wallet management operations such as policy updates, credential rotation, and account recovery actions.
## Transaction principles
Every transaction in SocketFi is designed around five core principles. These aren't optional guidelines — they're enforced guarantees that apply to every on-chain action.
No transaction can execute without explicit user approval. SocketFi never initiates state-changing operations on behalf of a user without their direct, in-session consent. Authorization is cryptographic and verifiable.
Users should understand what a transaction does before they approve it. Your application is responsible for communicating intent in plain language — "Deposit 100 USDC into Lending Pool" rather than "Invoke `deposit(100)`." SocketFi's approval flow surfaces the action, assets, destination, and estimated fees so users are never approving blind.
All transactions are executed through the user's smart wallet. Wallet policies — spending limits, contract allowlists, authorization requirements — remain active and are evaluated before every execution. You cannot bypass wallet enforcement at the application layer.
Transactions require cryptographic authorization backed by the user's passkey credential. Nonce validation prevents replay attacks. Time-bound authorizations prevent stale requests from executing. Unauthorized actions are rejected at the wallet level.
Users should always know what is happening, which assets are moving, which contracts are involved, and what fees may apply. SocketFi surfaces this information during the approval flow. Your application should reinforce this by providing clear UI context around every transaction request.
## Transaction architecture
Every SocketFi transaction passes through a layered execution stack. Each layer has a distinct responsibility, and all layers must succeed before a transaction reaches the network.
```text theme={null}
┌─────────────────────────────┐
│ Application │ Defines intent — what should happen
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ SocketFi SDK │ Validates, constructs, and routes the request
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ Transaction Approval │ User reviews and approves the action
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ Smart Wallet │ Authorizes, enforces policies, validates nonces
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ Soroban Network │ Executes the contract call on-chain
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ Execution Result │ Success with hash, or failure with reason
└─────────────────────────────┘
```
### Application layer
Your application defines the desired action by calling `requestTransaction()` with a contract ID, method name, and arguments. The application describes *intent* — SocketFi handles everything else.
### SDK layer
The SDK validates the request, encodes arguments, constructs the Soroban transaction, and initializes the approval flow. You don't need to build or sign transactions manually.
### Approval layer
Before any state-changing operation executes, the user is presented with an approval screen. The screen surfaces the action, assets involved, destination address, and estimated fees. The transaction pauses here until the user responds.
### Smart wallet layer
After approval, the user's smart wallet evaluates the request. This includes ownership verification, policy enforcement, nonce validation, and fee processing. The wallet is the final security boundary — only authorized, policy-compliant transactions proceed.
### Network layer
The fully authorized transaction is submitted to the Soroban network for execution. The contract method runs on-chain, state changes are applied, and the result is returned.
## Execution results
Every call to `requestTransaction()` resolves to a `TransactionResult`:
```ts theme={null}
// Successful execution
{
success: true,
transactionHash: "abc123..."
}
// Failed execution
{
success: false
}
```
A `success: true` result means the transaction was executed and confirmed on-chain. The `transactionHash` can be used to look up the transaction in a Stellar explorer or store it for auditing. A `success: false` result means execution did not complete — this covers user rejections, policy violations, contract errors, and network failures.
Read-only contract queries don't require user approval and don't produce a transaction hash. Use `readContract({ contractId, method, args })` for operations that only read state without modifying it.
## How applications initiate transactions
Your application always starts a transaction through the SDK using `requestTransaction()`. The SDK manages the entire lifecycle from there.
```ts theme={null}
const result = await socketfi.requestTransaction({
contractId: "CBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
method: "transfer",
args: [recipientAddress, amount],
});
if (result.success) {
console.log("Transfer complete:", result.transactionHash);
} else {
console.warn("Transfer was not completed");
}
```
Always check `result.success` before updating your application state. A resolved promise does not guarantee successful execution — the user may have rejected the transaction, or a policy or contract error may have occurred.