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

# Transaction lifecycle

# Transaction Lifecycle

A technical breakdown of the end-to-end flow for a VelumX-sponsored transaction.

## DEVELOPER\_SPONSORS Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User Wallet
    participant SDK as @velumx/sdk
    participant P as Secure Proxy
    participant R as VelumX Relayer
    participant S as Stacks Network

    U->>SDK: buildSponsoredContractCall(params)
    SDK-->>U: unsignedTx (Uint8Array)
    U->>U: stx_signTransaction (no broadcast)
    U->>SDK: sponsor(signedTxHex)
    SDK->>P: POST /api/velumx/proxy/sponsor
    P->>R: forward + inject API key
    Note over R: Validate API key
    Note over R: Co-sign as fee-payer
    Note over R: Broadcast to Stacks
    R-->>SDK: { txid }
    SDK-->>U: txid
```

## USER\_PAYS Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User Wallet
    participant SDK as @velumx/sdk
    participant P as Secure Proxy
    participant R as VelumX Relayer
    participant PM as Paymaster Contract
    participant Proto as Protocol Contract

    U->>SDK: buildSponsoredContractCall(paymasterParams)
    SDK-->>U: unsignedTx
    U->>U: stx_signTransaction (no broadcast)
    U->>SDK: sponsor(signedTxHex, { feeToken, feeAmount })
    SDK->>P: POST /api/velumx/proxy/sponsor
    P->>R: forward + inject API key
    Note over R: Validate API key + fee params
    Note over R: Co-sign as fee-payer
    R->>PM: broadcast tx
    Note over PM: collect-fee (SIP-010 transfer)
    PM->>Proto: protocol action (swap/bridge/etc.)
    Proto-->>PM: result
    PM-->>R: (ok result)
    R-->>SDK: { txid }
    SDK-->>U: txid
```

## Phase Details

### 1. Transaction Construction

The SDK builds an unsigned Stacks transaction with `sponsored: true`. The user is `tx-sender` — they authorize the action and (for USER\_PAYS) the fee transfer. The relayer will be the `fee-payer`.

### 2. User Signing

The user signs via `stx_signTransaction` with `broadcast: false`. This produces a partially-signed transaction — the user's signature is present but the sponsor signature is missing. The transaction cannot be broadcast yet.

### 3. Secure Proxy

The signed transaction hex is sent to the developer's backend proxy. The proxy injects the `VELUMX_API_KEY` header and forwards to the VelumX Relayer API. The API key never touches the browser.

### 4. Relayer Validation

The VelumX Relayer:

* Validates the API key and project status
* Checks rate limits and spending caps for this API key
* For USER\_PAYS: verifies the fee token and amount match the project's policy
* Verifies the transaction has `AuthType.Sponsored` (0x05)

### 5. Co-signing and Broadcast

The relayer appends its sponsorship signature (paying the STX network fee) and broadcasts the unified transaction to the Stacks network.

### 6. On-Chain Execution

For DEVELOPER\_SPONSORS: the contract call executes directly.

For USER\_PAYS: the paymaster contract runs atomically — fee transfer then protocol action. If either fails, both revert.

### 7. Finality

The relayer returns the `txid`. The developer can monitor finality via the Stacks API or the VelumX Dashboard.