Vulcan Forge
  1. Core Concepts
Vulcan Forge
  • Introduction
  • Getting Started
  • Authentication & Authorization
  • Core Concepts
    • Terminology
    • Regulated Assets
    • Tenants
    • Mapping & Labelling
    • Solana Networks
    • Transaction Processing
    • Key Management
    • Read Layer
  • API Reference
    • Blockchain Accounts
      • Create Account
      • Fetch Account Details
      • Fetch Account Balance
      • Fetch Account Private Key
      • Fetch Accounts
      • Update Account
      • Inactivate Account
    • Financial Instruments
      • Create Financial Instrument
      • Update Financial Instrument
      • Fetch Financial Instrument Details
      • Fetch Financial Instruments
      • Token Extensions Calculator
    • Positions
      • State
        • Initialize Position
        • Close Position
        • Freeze Position
        • Unfreeze Position
      • Movements
        • Mint
        • Burn
        • Transfer Financial Instrument
        • Transfer SOL
      • Trades
        • Trade
      • History
        • Fetch Positions
        • Fetch Position Details
        • Fetch Position Balance
    • Loans
      • Create Loan
      • Fetch Loan Details
      • Fetch Loans
      • Swap Collateral
      • Repay Loan
      • Close Loan
      • Refinance Loan
    • Blockchain Transactions
      • Processing
        • Fetch Transaction Status
        • Sign Transaction
        • Submit Transaction
      • Durable Nonces
        • Create Durable Nonce Accounts
        • Fetch Durable Nonce Account Details
        • Fetch Durable Nonce Accounts
      • Address Lookup Tables
        • Create Address Lookup Table
        • Fetch Address Lookup Table Details
        • Fetch Address Lookup Tables
        • Extend Address Lookup Table
        • Update Address Lookup Table
      • History
        • Fetch Transactions
        • Fetch Transaction Details
    • Market Data
      • Update Feed
  • Schemas
    • Accounts
      • DKG
        • DKG Key Setup
      • Offchain References
      • Account Lookup
      • New Account
      • Tenancy Config
      • Account Balance
      • Offchain File
    • Transactions
      • Solana Transaction Config
      • Commitment Config
      • Transaction Lookup
    • Query
      • Query Components
        • Sort Model
        • Field Value Filter
        • Filter Model
      • Items Query
    • Reponses
      • Errors
        • Individual Error
        • Error Response
      • Accounts
        • Private Keys
          • Private Key Details
          • Database Private Key Details
          • Cloud Provider Resource Location
          • DKG Private Key Details
        • Account Response Detailed
        • Account Onchain Detailed
        • Account Offchain Detailed
        • Account Response Identifiers
        • Account Offchain Compact
        • Account Response Compact
        • Account Onchain Compact
      • Transactions
        • Solana Transaction Result
        • Solana Entity Result
      • Positions
        • Position Offchain Result
    • Positions
      • Position Lookup
      • Transfer Financial Instrument Definition
      • Burn Definition
      • Mint Definition
      • Transfer SOL Definition
      • Position Balance
    • Loans
      • Loan Duration
  1. Core Concepts

Transaction Processing

TLDR#

Configuring how a Solana Transaction should be processed is a complex endeavor and many things can go wrong after submitting it. Vulcan Forge does the upfront validation work and brings all the configuration knobs together.

Validations#

Most frequent / basic validations that are useful to be done before submitting a Solana transaction to an RPC node for processing on the network:
1.
Were all signatures needed across all instructions in the transaction provided and are they in the correct order?
2.
Does the transaction exceed the transaction size limit?
3.
Are there sufficient token/SOL balances to support instructions that would process debit operations against them?
4.
Will one of the positions involved in the transaction have its token balance changed and it is in a frozen state and there is no instruction to unfreeze it?
5.
Was the transaction simulated succesfully?
Yes, a transaction can be submitted with only doing some or none of these validations upfront - the network will reject it anyway if any of these validations fail. But why spend processing time in external systems and be charged RPC provider fees (and possibly network txn fees for consumed compute units), when a transaction fails for reasons that can validated upfront?
Vulcan Forge by default executes all these upfront validations, in the order mentioned above. If either fail, the transaction is not submitted to the RPC provider. Optionally, the 3rd validation can be turned off with the offchainBalanceAvailabilityPrecheck flag present in the Positions Movements/Trades API endpoints, where this field is applicable. Reasons for turning of the offchain balances precheck:
If the Solana transaction includes an instruction that will credit a quantity that it is debited from the same balance in a subsequent instruction in the same transaction.
Transactions that impact the balances of the same accounts are submitted within a very short time of each other and there is a chance that the offchain balances don't get updated on time to support these checks.

Configuration Settings#

The subset of the API endpoints which can create a Solana transaction will have the Creates Solana Transaction endpoint attribute populated either with:
Always -> As long as the upfront validations succeed, a solana transaction will always be created
If Requested -> The creation of a Solana transaction will not be triggered if the alreadyOnchain field on the request payload is set to true or if the submitTransaction flag is set to false
All endpoints that support the creation of a Solana transaction include an optional field at the root of the request JSON payload: solanaTransactionConfig.
Configurations available for it are discussed below.

1. Fee Payer#

An account lookup can be provided to find the fee payer wallet that should be used for paying the fees for the transaction. The wallet needs to be setup with the canPayFees setting turned on.
If the feePayer is not provided, the system will use the global fee payer if one is setup, otherwise a validation error will be returned.
Rules for determining the global fee payer:
1.
Get the Tenant Org associated with the API Key
2.
Lookup for an account within the context of the Tenant which has in its globalFeePayerForOrgs list an org included that matches the Org from step 1.
Note that one and only one Wallet can be setup as a Global Fee Payer per each Tenant Organization. The reason globalFeePayerForOrgs is a list is to support Multi-Org Tenants configurations, where one Wallet could pay for more than 1 Org within the same Tenant.

2. Compute Unit Config#

Solana Client SDKs provide the capability to set priority fees (on top of the base transaction fee) to increase the chances of a transaction to be included for processing in a block.
The system adds by default the Compute Unit Limit and Compute Unit Price instructions at the beginning of the transaction.

Compute Unit Limit#

Needs to be set to avoid overpaying for the transaction.
Calculation Rules:
1.
Use the client provided value in computeUnitConfig.limit
2.
If a value is not provided, and all required signatures for the transactions are available: limit = cpu units from the transaction simulation * 1.2
3.
If not all required signatures are present at the time the txn message is created, use the max value of 1.4M

Compute Unit Price#

Price the client is willing to pay for prioritization fees.
Available options:
1.
Provide the price in micro-lamports with the computeUnitConfig.price
2.
Let the system get a real-time price estimate:
for now we use a single RPC provider to get the price estimate: Helius; more providers could be added in the future
the calculation strategy for the estimate can be set with the computeUnitConfig.estimatePrice.calculationStrategy field which allows for these 2 strategies
If the computeUnitConfig is not provided, the system will default to a constant value for the price. Check the schema doc for the most current default value.
The addition of these compute unit instructions can be turned off with the computeUnitConfig.enable flag.

3. Message Lifetime Strategy#

Once a Solana transaction message is created (i.e. all instructions needed for it + the txn hash are put together), it has a limited shelf life within which it can be submitted as a transaction for processing to the network, for reasons explained here.

Recent Blockhash#

The most widely used strategy for determining the max allowed shelf life of the message is the Recent Blockhash strategy - it relies on getting the most recent blockhash from the network and stamping that into the transaction message.
More convenient and easier to use than the next alternative, but also limiting in the sense that the max shelf life is short: about 1 minute.
A few things have to happen within this one minute, most important ones being:
pre-submit validations and processing
gathering of all necessary signatures
Sometimes, that 1 minute is not enough. To address the above limitations Vulcan Forge supports the use of Durable Nonces as an alternate message lifetime strategy.

Durable Nonces#

Probably the most frequent situation when the 1 minute shelf life is too short, is when not all the signers can come together at the same time to provide signatures. The condition when a larger time gap exists between the moments in which signers can provide their signatures is often referred to as offline signing.
For these situations Durable nonces is the only other available option - more details on Durable Nonces can be found here and here.
As reflected in the docs above, the setup is rather involved as it requires a special advance nonce instruction to be added to the transaction and the availability of a Nonce Account which can be used by no more than 1 inflight transaction at a time.
Vulcan Forge simplifies the process of using Durable Nonces by:
1.
Providing endpoints to manage the setup of a pool of Nonce Accounts
2.
Doing the behind-the-scences coordination work to assign to each inflight transaction a nonce account from this pool and locking its use until the transaction reaches a success or failure state - thus providing the option for an almost indeterminate amount of time between transaction message creation and transaction submission.
As such, for a client application the choice of what to use when processing a transaction is as simple as supplying one of these 2 options:
solanaTransactionConfig.messageLifetimeStrategy=RECENT_BLOCKHASH
solanaTransactionConfig.messageLifetimeStrategy=DURABLE_NONCE
One more good use case for choosing a DURABLE_NONCE - Resubmit a Transaction.

4. Committment Level#

After a transaction is submitted to the network, the system keeps checking on the background (/w a timeout) until the transaction reaches its Finalized state. Under normal conditions it can take 10-20 seconds to get to this state.
The solanaTransactionConfig.commitmentConfig.commitmentLevel setting allows a client to control how soon the API endpoint should reply back with a response, i.e. as soon as one of these states is reached:
Processed
Committed
Finalized
If not supplied, the default is Committed and after 2 cofirmations have been received.
If for e.g. the default is used, the client receives a faster reply back than if waiting for Finalized. The system continues though in this case to check in the background (after responding to the client), until the Finalized state is reached - to update appropriately the transaction status in the offline database.

5. Transaction Version#

A less frequently used setting, the transaction version allows for controlling what version should a transaction be constructed as:
LEGACY
V0
Some transactions (e.g. those including Address Lookup Tables) cannot be setup as LEGACY.
Default value: V0.

Resubmit a Transaction#

As explained in the introduction, when Vulcan Forge is in charge of putting together a transaction and submitting it to the network, it always persists/commits it to its offline database before submitting it.
This helps with:
as long as validations pass, the resulting transaction ensuing from the client's request is not lost, even if the network rejects it; there is an audit of what happened
in case of a failure that is recoverable, as long the transaction was submitted with a durable nonce txn message lifetime strategy, the transaction can be resubmitted to the network without needing to recreate the transaction message and gathering the signatures again
Modified at 2025-12-02 11:48:43
Previous
Solana Networks
Next
Key Management
Built with