Documentation

Everything you need to know about IntentRail.

What is IntentRail?

IntentRail is a portable manifest format for expressing transaction intents on Solana. Instead of building a transaction immediately, dApps create an intent manifest that describes:

What the user wants to accomplish (swap, transfer, mint)
Constraints on the execution (max spend, min receive, allowed programs)
Preconditions that must be met (required accounts, token accounts)
Metadata for display (human-readable summary, dApp info)

Wallets can display this information to users in a clear, understandable format. Transaction builders can verify constraints are satisfied before execution. The entire manifest is signed, creating a cryptographic audit trail.

Manifest Specification

An intent manifest is a JSON object with the following structure:

intent.jsonjson

{
  {{STRING:"intent_version"}}: {{STRING:"1.0"}},
  {{STRING:"intent_id"}}: {{STRING:"550e8400-e29b-41d4-a716-446655440000"}},
  {{STRING:"created_at"}}: {{STRING:"2024-01-15T10:30:00.000Z"}},
  {{STRING:"expires_at"}}: {{STRING:"2024-01-15T10:45:00.000Z"}},
  {{STRING:"chain"}}: {{STRING:"solana"}},
  {{STRING:"network"}}: {{STRING:"mainnet-beta"}},
  {{STRING:"action"}}: {{STRING:"swap"}},
  {{STRING:"actor"}}: {
    {{STRING:"wallet_pubkey"}}: {{STRING:"7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"}}
  },
  {{STRING:"constraints"}}: {
    {{STRING:"max_spend"}}: [{ {{STRING:"mint"}}: {{STRING:"So111..."}}, {{STRING:"amount"}}: {{STRING:"1000000000"}} }],
    {{STRING:"min_receive"}}: [{ {{STRING:"mint"}}: {{STRING:"EPjFW..."}}, {{STRING:"amount"}}: {{STRING:"95000000"}} }],
    {{STRING:"allowed_programs"}}: [{{STRING:"JUP6Lk..."}}],
    {{STRING:"forbidden_accounts"}}: []
  },
  {{STRING:"preconditions"}}: {
    {{STRING:"required_accounts"}}: [],
    {{STRING:"token_accounts"}}: [],
    {{STRING:"blockhash_ttl_seconds"}}: 60
  },
  {{STRING:"execution_hints"}}: {
    {{STRING:"compute_unit_limit"}}: 300000,
    {{STRING:"priority_fee_micro_lamports"}}: 10000
  },
  {{STRING:"metadata"}}: {
    {{STRING:"dapp"}}: { {{STRING:"name"}}: {{STRING:"Jupiter"}}, {{STRING:"url"}}: {{STRING:"https:{{COMMENT://jup.ag"}} },}}
    {{STRING:"human_summary"}}: {{STRING:"Swap 1 SOL {{KEYWORD:for}} at least 95 USDC"}}
  },
  {{STRING:"signatures"}}: []
}

intent_versionstring

Manifest version. Currently "1.0".

intent_idstring

UUIDv4 identifier for this intent. Used for tracking and deduplication.

created_at / expires_atstring

ISO 8601 timestamps. Intent is valid only within this window.

chain / networkstring

Target chain ("solana") and network ("mainnet-beta" or "devnet").

actionstring

Action type: "swap", "transfer", "mint", or "custom".

actorobject

Contains wallet_pubkey - the base58-encoded public key of the acting wallet.

constraintsobject

max_spend, min_receive, allowed_programs, and forbidden_accounts. Defines execution boundaries.

preconditionsobject

required_accounts, token_accounts, blockhash_ttl_seconds, and optional slot_range. Must be satisfied before execution.

execution_hintsobject

Optional compute_unit_limit, priority_fee_micro_lamports, and recommended_rpc.

metadataobject

dapp info (name, url), human_summary for display, and optional labels.

signaturesarray

Array of {signer, signature} entries. Ed25519 signatures over the canonical manifest hash.

SDKs

IntentRail provides SDKs for TypeScript, Rust, and Python. All implementations produce identical canonical hashes for the same manifest.

TypeScript

Full-featured SDK for Node.js and browsers.

npm install @intentrail/sdk

Rust

Native Rust crate for high-performance validation.

cargo add intentrail

Python

Python SDK with CLI tools.

pip install intentrail

View SDK documentation

Security

Signatures

Intent manifests are signed using Ed25519, the same algorithm as Solana transactions. The signature is computed over the SHA-256 hash of the canonical JSON representation (with the signatures field removed).

Canonical Hashing

JSON is canonicalized by sorting object keys lexicographically and removing whitespace. This ensures the same manifest always produces the same hash, regardless of key ordering or formatting differences.

Replay Protection

Each intent has a unique ID, explicit network field, and expiration timestamp. Transaction builders should track executed intent IDs to prevent double-spend. Network isolation prevents cross-network replay attacks.

Constraint Enforcement

The allowed_programs and forbidden_accounts fields let users specify exactly which programs may be invoked and which accounts must not be touched. Transaction builders must verify these constraints before execution.