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

# How It Works

> Understanding the technical flow behind Spice Flow API

## Naming Convention

The API uses the following naming convention:

* **Intent**: The parent action which contains ChainBatch(es)
* **ChainBatch**: For a specific chain, and has many Call(s)
* **Call**: Has `to`, `data`, and `value` parameters

<img src="https://mintlify.s3.us-west-1.amazonaws.com/ter-e1ca54a7/assets/types.png" alt="Types" />

## Process Flow

<img src="https://mintcdn.com/ter-e1ca54a7/T-BZIBFN376rp_1N/assets/how-it-works.png?fit=max&auto=format&n=T-BZIBFN376rp_1N&q=85&s=508688a15f70fa640eac06caa7acd860" alt="How It Works Flow Diagram" width="1483" height="4676" data-path="assets/how-it-works.png" />

For a detailed technical explanation of the underlying technologies, including EIP-7702 and the `Delegate` contract, see our deep dive on [EIP-7702](/deep-dive/eip7702) and [Delegate Contract](/deep-dive/delegate).

## What Actually Happens

### 1. Transaction Submission

When you call `POST /transaction/submit`:

1. **Transaction Validation**: API validates the transaction structure and authorization array
2. **Database Storage**: Intent and authorization data is saved to the database
3. **Chain Broadcast**: Transaction is broadcast to the appropriate blockchain
4. **Response**: Returns transaction hash and intent ID for tracking

### 2. Intent Execution

When you call `POST /intent/{intentId}/execute/{stepId}`:

1. **Step Lookup**: Retrieves the specific step from the database using intent ID and step index
2. **Execution Trigger**: Performs the actual work for that step (checks, transactions, etc.)
3. **Result Capture**: Records execution results and any transaction hashes
4. **Response**: Returns execution status and results

## Technical Implementation

### Intent Structure

```typescript theme={null}
interface Intent {
  intentId: string; // Signature of chainBatches
  chainBatches: ChainBatch[];
  status: "created" | "executing" | "success" | "error" | "reverted";
  steps: IntentStep[];
}
```

### Step Execution Model

```typescript theme={null}
interface IntentStep {
  stepId: number; // Index [0, n) in chainBatches array
  chainId: number; // Target chain for this step
  status: "created" | "executing" | "success" | "error" | "reverted";
  transactionHash?: string; // Hash if transaction was sent
  executionResult?: object; // Results of step execution
}
```

### Transaction Submit Request Structure

```typescript theme={null}
interface TransactionSubmitRequest {
  authorization: [
    {
      chainId: number;
      address: string;
      nonce: number;
      r: string; // ECDSA signature R value
      s: string; // ECDSA signature S value
      yParity: number; // ECDSA signature Y parity
    },
  ];
  intentAuthorization: {
    signature: string; // This becomes the intent ID
    chainBatches: ChainBatch[];
  };
}
```

## Key Concepts

### Intent ID Generation

* The intent ID is the **signature of the chainBatches**
* This approach is similar to Solana's transaction ID system
* Provides a unique, deterministic identifier for each intent

### Step Index System

* Steps are indexed as integers: `[0, n)` where n = chainBatches.length
* Step 0 = first chain authorization, Step 1 = second, etc.
* Steps must be executed sequentially in order

### Authorization Array

* **Multiple Authorizations**: Can submit multiple EIP-7702 authorizations in a single transaction
* **Cross-Chain Support**: Each authorization can be for different chains or addresses
* **Flexible Delegation**: Supports complex multi-chain execution patterns

### Execution Model

* **Active Execution**: Calling the POST endpoint triggers actual work
* **Unit of Work**: Each step call performs one discrete operation
* **Stateful**: Execution state is persisted in the database
* **Resumable**: Failed or interrupted intents can be resumed

## Error Handling

The API implements comprehensive error handling:

* **400 Bad Request**: Invalid transaction format, malformed parameters, or out-of-range step IDs
* **404 Not Found**: Intent not found or step index exceeds available steps
* **500 Internal Server Error**: Database errors, chain communication failures, or execution errors

```typescript theme={null}
// Example error response
{
  "success": false,
  "error": {
    "message": "Step execution failed: insufficient gas"
  }
}
```

## Data Persistence

Unlike the current in-memory implementation:

* **Database Storage**: All intent data is persisted to database
* **Reliable Execution**: Steps can be retried if they fail
* **Audit Trail**: Complete execution history is maintained
* **Recovery**: System can recover from restarts without losing state

## Monitoring

Comprehensive monitoring capabilities:

* **Database Logging**: All operations are logged to database
* **Execution Tracking**: Detailed step-by-step execution results
* **Transaction Hashes**: All on-chain transactions are tracked
* **Status Endpoints**: Real-time status via API calls

## Use Cases

### Perp DEXes

Power bridge-free native deposits from every network into margin accounts on Perp DEXes.

### Money Markets

Enable users to natively deposit assets directly into lending markets from every major network.

### AMMs

Facilitate bridge-free provision of liquidity from every network by enabling users to deposit assets into liquidity pools from any chain.