Gas Credit Backend

What is Gas Credit Backend

Gas Credit Backend is an automatic gas pre-financing service for cross-chain transfers between TVM networks. Despite the name "credit", this is NOT a credit system in the traditional sense.

The service allows users to pay for gas in the source network, and the system automatically deploys the event contract in the destination network, converting gas cost at the current USD rate between native tokens of both networks.

Problem it Solves

For TVM↔TVM transfers, users need to:

1. Send a transaction in the source network
2. Manually deploy an event contract in the destination network (requires gas in the destination network's native token)

This creates a UX problem: users must have native tokens of both networks. Credit Backend solves this by accepting gas payment in the source network's native token and automatically deploying the event in the destination network.

When it Triggers

Condition	Description
useCredit=true	API request with Credit mode enabled
attached_gas_USD >= required_gas_USD	User attached sufficient gas
remaining_gas_to — valid EventDeployer	Gas return address is one of the EventDeployers
Configuration not expired	end_timestamp has not passed
Source chain ID in whitelist	allowed_source_chain_ids contains the source network

When it Does NOT Trigger (non-credit mode)

• useCredit=false in API request — user deploys event manually via proof
• attached_gas in USD is less than required_gas in USD — transfer is rejected
• remaining_gas_to is not an EventDeployer address — transfer is rejected
• Configuration expired or chain ID not in whitelist — ignored

When NOT needed:

• User has native tokens of both networks and wants to manage gas manually
• For debugging/testing with manual event deployment
• When using relay-based confirmations (EVM↔TVM)

How it Works

Step by Step

1. User sends transfer

   • Transaction goes to Proxy contract with attached_gas
   • Proxy emits TvmTvmNative or TvmTvmAlien event

2. Credit Backend receives event

   • process_event_emitter_event() parses the event
   • Calls process_tvm_tvm_message()

3. Message validation

   • validate_tvm_tvm_remaining_gas_to() — validates gas return address
   • validate_tvm_tvm_attached_gas() — validates gas sufficiency in USD

4. Calculate required_gas

   • event_initial_balance + expected_gas + deploy_token_value
   • Plus tx_block_proof_fwd_fee (proof forwarding through contracts)

5. Obtain proof

   • Request to Proof API for tx_block_proof
   • Proof caching for repeated requests

6. Send deployEvents

   • prepare_unsigned_tvm_tvm_message() builds the message
   • deliver_message() signs and sends

7. Event is deployed

   • EventDeployer.deployEvents() calls EventConfiguration.deployEvents()
   • Event contract verifies proof and mints/unlocks tokens

State Machine

Status	Description	Transitions
New	Event received, awaiting processing	→ Completed, → Rejected, → Skipped
Rejected	Validation failed (insufficient gas or invalid remaining_gas_to)	Final
Completed	Event successfully deployed	Final
Skipped	Already processed (duplicate message_hash)	Final

Risks and Edge Cases

Risk/Error	Cause	Protection/Solution
Insufficient gas	attached_gas_USD < required_gas_USD	Transaction rejected (Rejected), gas stays with user
Invalid remaining_gas_to	Address is not an EventDeployer	Transaction rejected
Price volatility	Rate changed between send and processing	Reserve in item_buffer and transfer_reserve
Duplicate events	Re-processing same message_hash	message_hashes set, skip if exists
Expired configuration	end_timestamp passed	Configuration removed from processing
Proof API unavailable	Network unavailable	Retry with maximum_failed_responses_time_sec
Alien token not deployed	Token bridged for first time	deploy_token_value added to required_gas

Formula for calculating required_gas

// Forward chain size constants
DEPLOYER_TO_VERIFIER_CHAIN_SIZE = 3   // deployer → configuration → event → verifier
CONFIGURATION_TO_VERIFIER_CHAIN_SIZE = 2   // configuration → event → verifier

// Proof forwarding fee calculation
tx_block_proof_fwd_fee = calculate_fwd_fee(tx_block_proof)  // depends on proof size
full_chain_tx_block_proof_fwd_fee = tx_block_proof_fwd_fee × 3
shorten_chain_tx_block_proof_fwd_fee = tx_block_proof_fwd_fee × 2

// Base gas
essential_gas = event_initial_balance + expected_gas + deploy_token_value

// Final values
event_required_gas = essential_gas + shorten_chain_tx_block_proof_fwd_fee
total_required_gas = essential_gas + full_chain_tx_block_proof_fwd_fee

Formula components

Component	Description
event_initial_balance	Initial balance of event contract (from EventConfiguration)
expected_gas	Gas for additional operations requested by user (from event)
deploy_token_value	Cost of token deployment in destination network (if Native and token not predeployed in AlienProxy)
tx_block_proof_fwd_fee	Fee for forwarding one proof cell (depends on BOC size)

Two required_gas values

Value	Forward path	Usage
total_required_gas	EventDeployer → Configuration → Event → Verifier (×3)	Validation: attached_gas_USD >= total_required_gas_USD
event_required_gas	Configuration → Event → Verifier (×2)	Sent to EventConfiguration during deployment

Why two values?

EventDeployer already pays for the first forwarding hop, so event_required_gas (with ×2 coefficient) is sent to EventConfiguration, while total_required_gas (with ×3 coefficient) is used for gas sufficiency validation.

Error Codes

Code	Constant	Description
101	-	Sender is not factory (EventDeployer)
2112	ZERO_ADDRESS	Zero address provided
2213	TOO_LOW_DEPLOY_VALUE	Insufficient value to deploy event
2215	EVENT_TIMESTAMP_HIGHER_THAN_END	Event timestamp exceeds configuration end time
2801	UNKNOWN_MEDIATOR_OPERATION	Unknown operation type in Mediator
2802	WRONG_GUARDIAN	Caller is not guardian
2803	NOT_NATIVE_PROXY	Address is not native proxy
2804	WRONG_GAS_RECIPIENT	Invalid gas recipient address

Important Notes

1. Credit mode is enabled by default — useCredit=true if not specified in API request
2. Gas validation uses USD conversion — attached gas amount is converted to USD for comparison
3. EventDeployers are pre-funded — system maintains balance on EventDeployer contracts
4. Batch deployment supported — multiple events can be deployed in single transaction