​

Transaction Lifecycle

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

​

DEVELOPER_SPONSORS Flow

​

USER_PAYS Flow

​

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.