Skip to main content

OnboardingBridgeClient

onboarding_bridge

Struct OnboardingBridgeClient 

Source 
pub struct OnboardingBridgeClient<'a> {
    pub env: Env,
    pub address: Address,
    /* private fields */
}
Expand description

OnboardingBridgeClient is a client for calling the contract defined in “OnboardingBridge”.

Fields§

§env: Env§address: Address

Implementations§

Source§

impl<'a> OnboardingBridgeClient<'a>

Source

pub fn new(env: &Env, address: &Address) -> Self

Source§

impl<'a> OnboardingBridgeClient<'a>

Source

pub fn initialize( &self, admin: &Address, fee_collector: &Address, fee_bps: &u32, nonce: &Option<u64>, )

Initialises the bridge contract. Must be called exactly once before any other function.

Sets the admin, fee collector, and initial fee rate, then marks the contract as initialised and extends the instance TTL.

§Arguments
  • admin (Address) — Address that will hold administrative privileges. Must authorise this call.
  • fee_collector (Address) — Address entitled to call withdraw_fees.
  • fee_bps (u32) — Initial fee in basis points. Must be ≤ 1 000 (10 %).
  • nonce (Option<u64>) — Optional sequential nonce for the admin. Pass None to skip nonce enforcement.
§Authorization

Requires admin.require_auth().

§Errors
§Events
  • ("Initialized", admin, fee_collector) — data: (fee_bps,)
§Security Considerations

This function is the single gate that prevents double-initialisation. The check is performed before require_auth so that the initialised flag is always respected regardless of authorisation state. Deploy and call initialize atomically (e.g. in the same transaction) to prevent front-running by a third party who could set themselves as admin.

§Examples
// bridge.initialize(&admin, &fee_collector, &50u32, &None);
// assert_eq!(bridge.query_fee_bps(), 50u32);
Source

pub fn try_initialize( &self, admin: &Address, fee_collector: &Address, fee_bps: &u32, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Initialises the bridge contract. Must be called exactly once before any other function.

Sets the admin, fee collector, and initial fee rate, then marks the contract as initialised and extends the instance TTL.

§Arguments
  • admin (Address) — Address that will hold administrative privileges. Must authorise this call.
  • fee_collector (Address) — Address entitled to call withdraw_fees.
  • fee_bps (u32) — Initial fee in basis points. Must be ≤ 1 000 (10 %).
  • nonce (Option<u64>) — Optional sequential nonce for the admin. Pass None to skip nonce enforcement.
§Authorization

Requires admin.require_auth().

§Errors
§Events
  • ("Initialized", admin, fee_collector) — data: (fee_bps,)
§Security Considerations

This function is the single gate that prevents double-initialisation. The check is performed before require_auth so that the initialised flag is always respected regardless of authorisation state. Deploy and call initialize atomically (e.g. in the same transaction) to prevent front-running by a third party who could set themselves as admin.

§Examples
// bridge.initialize(&admin, &fee_collector, &50u32, &None);
// assert_eq!(bridge.query_fee_bps(), 50u32);
Source

pub fn fund_c_address( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, nonce: &Option<u64>, deadline: &Option<u64>, )

Funds a C-address with tokens from a source account.

Transfers amount from source into the contract, deducts the effective fee, then forwards the net amount to target. The effective fee is the minimum of the global fee rate, the per-asset cap, and any volume-based tier that applies to source.

If a loyalty token has been configured, the contract mints a loyalty reward to source after the transfer.

§Arguments
  • source (Address) — The account providing the tokens. Must authorise.
  • target (Address) — The C-address receiving the net amount.
  • asset (Address) — The whitelisted token contract address.
  • amount (i128) — Gross amount to transfer. Must be > 0.
  • nonce (Option<u64>) — Optional sequential nonce for source.
  • deadline (Option<u64>) — Optional Unix timestamp (seconds) after which the call is rejected. Pass None for no expiry.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CAddressFunded", asset, source, target) — data: (amount, fee)
§Security Considerations

Access checks (check_access) are evaluated before require_auth so that blocked/non-allowlisted targets are rejected without consuming the caller’s authorization budget. The fee is floored (integer division), so for very small amounts the effective fee may be 0.

§Examples
// Fund 500 stroops to `target` with no deadline or nonce:
// bridge.fund_c_address(&source, &target, &usdc, &500i128, &None, &None);
Source

pub fn try_fund_c_address( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, nonce: &Option<u64>, deadline: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Funds a C-address with tokens from a source account.

Transfers amount from source into the contract, deducts the effective fee, then forwards the net amount to target. The effective fee is the minimum of the global fee rate, the per-asset cap, and any volume-based tier that applies to source.

If a loyalty token has been configured, the contract mints a loyalty reward to source after the transfer.

§Arguments
  • source (Address) — The account providing the tokens. Must authorise.
  • target (Address) — The C-address receiving the net amount.
  • asset (Address) — The whitelisted token contract address.
  • amount (i128) — Gross amount to transfer. Must be > 0.
  • nonce (Option<u64>) — Optional sequential nonce for source.
  • deadline (Option<u64>) — Optional Unix timestamp (seconds) after which the call is rejected. Pass None for no expiry.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CAddressFunded", asset, source, target) — data: (amount, fee)
§Security Considerations

Access checks (check_access) are evaluated before require_auth so that blocked/non-allowlisted targets are rejected without consuming the caller’s authorization budget. The fee is floored (integer division), so for very small amounts the effective fee may be 0.

§Examples
// Fund 500 stroops to `target` with no deadline or nonce:
// bridge.fund_c_address(&source, &target, &usdc, &500i128, &None, &None);
Source

pub fn batch_fund_c_address( &self, source: &Address, targets: &Vec<Address>, amounts: &Vec<i128>, asset: &Address, nonce: &Option<u64>, deadline: &Option<u64>, )

Funds multiple C-addresses in a single transaction from one source account.

Pulls sum(amounts) from source in one token transfer, then iterates over each (target, amount) pair. Blocked or non-allowlisted targets are skipped (their amount is refunded to source) rather than aborting the entire batch. A single BatchCompleted event summarises successes and failures at the end.

Transfers to the same target address are aggregated into a single token transfer to reduce fee consumption.

§Arguments
  • source (Address) — The account providing all tokens. Must authorise.
  • targets (Vec<Address>) — Ordered list of recipient C-addresses.
  • amounts (Vec<i128>) — Gross amount for each recipient. Must be the same length as targets. Every element must be > 0.
  • asset (Address) — The whitelisted token contract address.
  • nonce (Option<u64>) — Optional sequential nonce for source.
  • deadline (Option<u64>) — Optional Unix timestamp cutoff.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CAddressFunded", asset, source, target) — Emitted per successful entry; data: (amount, fee).
  • ("BatchTransferFailed", source, target) — Emitted per skipped entry; data: (amount, "access_denied").
  • ("BatchCompleted", source) — Emitted once at the end; data: (num_success, num_failures).
§Security Considerations

The full batch total is pulled from source upfront. If any entries are blocked, those amounts are returned to source at the end of execution. The validation loop that checks for zero/negative amounts runs before the initial token pull, so no tokens are moved on validation failures.

§Examples
// let targets = Vec::from_array(&env, [addr1, addr2]);
// let amounts = Vec::from_array(&env, [1000i128, 500i128]);
// bridge.batch_fund_c_address(&source, &targets, &amounts, &usdc, &None, &None);
Source

pub fn try_batch_fund_c_address( &self, source: &Address, targets: &Vec<Address>, amounts: &Vec<i128>, asset: &Address, nonce: &Option<u64>, deadline: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Funds multiple C-addresses in a single transaction from one source account.

Pulls sum(amounts) from source in one token transfer, then iterates over each (target, amount) pair. Blocked or non-allowlisted targets are skipped (their amount is refunded to source) rather than aborting the entire batch. A single BatchCompleted event summarises successes and failures at the end.

Transfers to the same target address are aggregated into a single token transfer to reduce fee consumption.

§Arguments
  • source (Address) — The account providing all tokens. Must authorise.
  • targets (Vec<Address>) — Ordered list of recipient C-addresses.
  • amounts (Vec<i128>) — Gross amount for each recipient. Must be the same length as targets. Every element must be > 0.
  • asset (Address) — The whitelisted token contract address.
  • nonce (Option<u64>) — Optional sequential nonce for source.
  • deadline (Option<u64>) — Optional Unix timestamp cutoff.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CAddressFunded", asset, source, target) — Emitted per successful entry; data: (amount, fee).
  • ("BatchTransferFailed", source, target) — Emitted per skipped entry; data: (amount, "access_denied").
  • ("BatchCompleted", source) — Emitted once at the end; data: (num_success, num_failures).
§Security Considerations

The full batch total is pulled from source upfront. If any entries are blocked, those amounts are returned to source at the end of execution. The validation loop that checks for zero/negative amounts runs before the initial token pull, so no tokens are moved on validation failures.

§Examples
// let targets = Vec::from_array(&env, [addr1, addr2]);
// let amounts = Vec::from_array(&env, [1000i128, 500i128]);
// bridge.batch_fund_c_address(&source, &targets, &amounts, &usdc, &None, &None);
Source

pub fn set_fee_bps(&self, new_fee_bps: &u32, nonce: &Option<u64>)

Updates the global fee rate in basis points.

The new rate applies to all subsequent fund_c_address and batch_fund_c_address calls. Per-asset caps and volume tiers further constrain the effective rate downward.

§Arguments
  • new_fee_bps (u32) — New fee rate. Must be ≤ 1 000 (10 %).
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeBpsChanged", old_fee_bps, new_fee_bps) — data: (admin,)
§Examples
// bridge.set_fee_bps(&200u32, &None); // set to 2 %
// assert_eq!(bridge.query_fee_bps(), 200u32);
Source

pub fn try_set_fee_bps( &self, new_fee_bps: &u32, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Updates the global fee rate in basis points.

The new rate applies to all subsequent fund_c_address and batch_fund_c_address calls. Per-asset caps and volume tiers further constrain the effective rate downward.

§Arguments
  • new_fee_bps (u32) — New fee rate. Must be ≤ 1 000 (10 %).
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeBpsChanged", old_fee_bps, new_fee_bps) — data: (admin,)
§Examples
// bridge.set_fee_bps(&200u32, &None); // set to 2 %
// assert_eq!(bridge.query_fee_bps(), 200u32);
Source

pub fn set_source_daily_limit( &self, source: &Address, asset: &Address, limit_amount: &i128, nonce: &Option<u64>, )

Sets a maximum daily transfer limit for a specific (source, asset) pair.

Once set, any fund_c_address call from source using asset that would push the day’s cumulative volume past limit_amount is rejected. Set limit_amount to 0 to disable the limit entirely.

§Arguments
  • source (Address) — The address whose daily throughput is being capped.
  • asset (Address) — The asset the limit applies to.
  • limit_amount (i128) — Maximum gross tokens allowed per calendar day (UTC, measured in ledger timestamp / 86 400). Use 0 to disable.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Examples
// Allow user to move at most 10 000 USDC per day:
// bridge.set_source_daily_limit(&user, &usdc, &10_000i128, &None);
Source

pub fn try_set_source_daily_limit( &self, source: &Address, asset: &Address, limit_amount: &i128, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Sets a maximum daily transfer limit for a specific (source, asset) pair.

Once set, any fund_c_address call from source using asset that would push the day’s cumulative volume past limit_amount is rejected. Set limit_amount to 0 to disable the limit entirely.

§Arguments
  • source (Address) — The address whose daily throughput is being capped.
  • asset (Address) — The asset the limit applies to.
  • limit_amount (i128) — Maximum gross tokens allowed per calendar day (UTC, measured in ledger timestamp / 86 400). Use 0 to disable.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Examples
// Allow user to move at most 10 000 USDC per day:
// bridge.set_source_daily_limit(&user, &usdc, &10_000i128, &None);
Source

pub fn query_source_daily_limit( &self, source: &Address, asset: &Address, ) -> i128

Returns the daily transfer limit for a (source, asset) pair.

Returns 0 if no limit has been configured, meaning transfers are unrestricted for that pair.

§Arguments
  • source (Address) — The address to query.
  • asset (Address) — The asset to query.
§Errors
Source

pub fn try_query_source_daily_limit( &self, source: &Address, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the daily transfer limit for a (source, asset) pair.

Returns 0 if no limit has been configured, meaning transfers are unrestricted for that pair.

§Arguments
  • source (Address) — The address to query.
  • asset (Address) — The asset to query.
§Errors
Source

pub fn set_asset_fee_cap( &self, asset: &Address, max_fee_bps: &u32, nonce: &Option<u64>, )

Sets a per-asset maximum fee cap in basis points.

The effective fee for asset is min(global_fee_bps, cap). Useful for stablecoins or high-value assets where the global rate would otherwise be too aggressive.

§Arguments
  • asset (Address) — The token contract whose fee is being capped.
  • max_fee_bps (u32) — Cap in basis points. Must be ≤ 1 000.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Examples
// Cap USDC fees at 0.5 % regardless of global rate:
// bridge.set_asset_fee_cap(&usdc, &50u32, &None);
Source

pub fn try_set_asset_fee_cap( &self, asset: &Address, max_fee_bps: &u32, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Sets a per-asset maximum fee cap in basis points.

The effective fee for asset is min(global_fee_bps, cap). Useful for stablecoins or high-value assets where the global rate would otherwise be too aggressive.

§Arguments
  • asset (Address) — The token contract whose fee is being capped.
  • max_fee_bps (u32) — Cap in basis points. Must be ≤ 1 000.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Examples
// Cap USDC fees at 0.5 % regardless of global rate:
// bridge.set_asset_fee_cap(&usdc, &50u32, &None);
Source

pub fn query_asset_fee_cap(&self, asset: &Address) -> u32

Returns the fee cap configured for asset.

Returns the contract-wide MAX_FEE_BPS (1 000) if no cap has been set, meaning the global rate applies uncapped.

§Arguments
  • asset (Address) — The token contract to query.
§Errors
Source

pub fn try_query_asset_fee_cap( &self, asset: &Address, ) -> Result<Result<u32, <u32 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the fee cap configured for asset.

Returns the contract-wide MAX_FEE_BPS (1 000) if no cap has been set, meaning the global rate applies uncapped.

§Arguments
  • asset (Address) — The token contract to query.
§Errors
Source

pub fn set_fee_collector( &self, new_fee_collector: &Address, nonce: &Option<u64>, )

Changes the address that is entitled to call withdraw_fees.

§Arguments
  • new_fee_collector (Address) — Replacement fee collector.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeCollectorChanged", old_collector, new_fee_collector) — data: (admin,)
§Examples
// bridge.set_fee_collector(&new_collector, &None);
// assert_eq!(bridge.query_fee_collector(), new_collector);
Source

pub fn try_set_fee_collector( &self, new_fee_collector: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Changes the address that is entitled to call withdraw_fees.

§Arguments
  • new_fee_collector (Address) — Replacement fee collector.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeCollectorChanged", old_collector, new_fee_collector) — data: (admin,)
§Examples
// bridge.set_fee_collector(&new_collector, &None);
// assert_eq!(bridge.query_fee_collector(), new_collector);
Source

pub fn propose_new_fee_collector( &self, new_collector: &Address, nonce: &Option<u64>, )

Source

pub fn try_propose_new_fee_collector( &self, new_collector: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn accept_fee_collector(&self)

Source

pub fn try_accept_fee_collector( &self, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn query_pending_fee_collector(&self) -> Option<Address>

Source

pub fn try_query_pending_fee_collector( &self, ) -> Result<Result<Option<Address>, <Option<Address> as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Source

pub fn set_admin(&self, new_admin: &Address, nonce: &Option<u64>)

Source

pub fn try_set_admin( &self, new_admin: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn propose_new_admin(&self, new_admin: &Address, nonce: &Option<u64>)

Source

pub fn try_propose_new_admin( &self, new_admin: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn accept_admin(&self)

Source

pub fn try_accept_admin( &self, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn query_pending_admin(&self) -> Option<Address>

Source

pub fn try_query_pending_admin( &self, ) -> Result<Result<Option<Address>, <Option<Address> as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Source

pub fn set_minimum_amount(&self, amount: &i128, nonce: &Option<u64>)

Source

pub fn try_set_minimum_amount( &self, amount: &i128, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn query_minimum_amount(&self) -> i128

Returns the configured minimum transfer amount.

Note: Currently always returns 0 because the persistence layer is a stub. See set_minimum_amount for details.

§Errors
Source

pub fn try_query_minimum_amount( &self, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the configured minimum transfer amount.

Note: Currently always returns 0 because the persistence layer is a stub. See set_minimum_amount for details.

§Errors
Source

pub fn withdraw_fees(&self, asset: &Address, amount: &i128, nonce: &Option<u64>)

Withdraws accrued protocol fees to the fee collector.

Transfers amount of asset from the contract to the fee collector and decrements the on-chain accrued-fees counter.

§Arguments
  • asset (Address) — The token contract whose accrued fees are being withdrawn.
  • amount (i128) — Amount to withdraw. Must be > 0 and ≤ accrued balance.
  • nonce (Option<u64>) — Optional sequential nonce for the fee collector.
§Authorization

Requires the current fee collector’s require_auth().

§Errors
§Events
  • ("FeesWithdrawn", fee_collector) — data: (amount, asset)
§Security Considerations

Only the fee collector may call this function. Accrued fees are tracked separately from the contract’s token balance, so this function can never withdraw tokens that were sent to the contract for other purposes (use reclaim_tokens for that).

§Examples
// Withdraw all 5 accrued fee tokens:
// bridge.withdraw_fees(&usdc, &5i128, &None);
Source

pub fn try_withdraw_fees( &self, asset: &Address, amount: &i128, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Withdraws accrued protocol fees to the fee collector.

Transfers amount of asset from the contract to the fee collector and decrements the on-chain accrued-fees counter.

§Arguments
  • asset (Address) — The token contract whose accrued fees are being withdrawn.
  • amount (i128) — Amount to withdraw. Must be > 0 and ≤ accrued balance.
  • nonce (Option<u64>) — Optional sequential nonce for the fee collector.
§Authorization

Requires the current fee collector’s require_auth().

§Errors
§Events
  • ("FeesWithdrawn", fee_collector) — data: (amount, asset)
§Security Considerations

Only the fee collector may call this function. Accrued fees are tracked separately from the contract’s token balance, so this function can never withdraw tokens that were sent to the contract for other purposes (use reclaim_tokens for that).

§Examples
// Withdraw all 5 accrued fee tokens:
// bridge.withdraw_fees(&usdc, &5i128, &None);
Source

pub fn set_max_withdraw_per_tx(&self, amount: &i128, nonce: &Option<u64>)

Source

pub fn try_set_max_withdraw_per_tx( &self, amount: &i128, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn query_max_withdraw_per_tx(&self) -> i128

Source

pub fn try_query_max_withdraw_per_tx( &self, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn query_fee_bps(&self) -> u32

Source

pub fn try_query_fee_bps( &self, ) -> Result<Result<u32, <u32 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Source

pub fn set_referral_rate(&self, bps: &u32, nonce: &Option<u64>)

Sets the referral fee rate as a share of the protocol fee.

When fund_c_address_with_referral is called with a referrer, the referrer receives fee × referral_rate / 10_000 of the protocol fee, and the remainder accrues to the contract.

§Arguments
  • bps (u32) — Referral share in basis points relative to the fee (0–10 000). E.g. 2000 means the referrer gets 20 % of the fee.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ReferralRateChanged", bps) — no additional data.
Source

pub fn try_set_referral_rate( &self, bps: &u32, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Sets the referral fee rate as a share of the protocol fee.

When fund_c_address_with_referral is called with a referrer, the referrer receives fee × referral_rate / 10_000 of the protocol fee, and the remainder accrues to the contract.

§Arguments
  • bps (u32) — Referral share in basis points relative to the fee (0–10 000). E.g. 2000 means the referrer gets 20 % of the fee.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ReferralRateChanged", bps) — no additional data.
Source

pub fn query_referral_rate(&self) -> u32

Returns the current referral rate in basis points.

Returns 0 (no referral split) if set_referral_rate has never been called.

§Errors
Source

pub fn try_query_referral_rate( &self, ) -> Result<Result<u32, <u32 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the current referral rate in basis points.

Returns 0 (no referral split) if set_referral_rate has never been called.

§Errors
Source

pub fn fund_c_address_with_referral( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, referrer: &Option<Address>, )

Funds a C-address with an optional referrer that receives a share of the fee.

Behaves identically to fund_c_address except that when referrer is Some(addr), the referral portion of the protocol fee is transferred directly to that address immediately. The remainder accrues in the contract as usual.

fee          = floor(amount × effective_fee_bps / 10_000)
referral_fee = floor(fee × referral_rate / 10_000)   (0 if referrer is None)
protocol_fee = fee − referral_fee
net          = amount − fee
§Arguments
  • source (Address) — The account providing the tokens. Must authorise.
  • target (Address) — The C-address receiving net tokens.
  • asset (Address) — The whitelisted token contract.
  • amount (i128) — Gross amount. Must be > 0.
  • referrer (Option<Address>) — Address to receive the referral cut, or None for no referral.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("ReferralPaid", source, referrer) — Emitted only when referrer is Some and referral_fee > 0; data: (rf, asset).
  • ("CAddressFunded", asset, source, target) — data: (amount, fee).
§Security Considerations

Unlike fund_c_address, this function does not accept a nonce or deadline parameter. Callers relying on replay protection should use verify_auth_entry in conjunction with this call, or use the standard Stellar transaction sequence-number mechanism.

§Examples
// bridge.fund_c_address_with_referral(
//     &source, &target, &usdc, &1000i128, &Some(referrer),
// );
Source

pub fn try_fund_c_address_with_referral( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, referrer: &Option<Address>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Funds a C-address with an optional referrer that receives a share of the fee.

Behaves identically to fund_c_address except that when referrer is Some(addr), the referral portion of the protocol fee is transferred directly to that address immediately. The remainder accrues in the contract as usual.

fee          = floor(amount × effective_fee_bps / 10_000)
referral_fee = floor(fee × referral_rate / 10_000)   (0 if referrer is None)
protocol_fee = fee − referral_fee
net          = amount − fee
§Arguments
  • source (Address) — The account providing the tokens. Must authorise.
  • target (Address) — The C-address receiving net tokens.
  • asset (Address) — The whitelisted token contract.
  • amount (i128) — Gross amount. Must be > 0.
  • referrer (Option<Address>) — Address to receive the referral cut, or None for no referral.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("ReferralPaid", source, referrer) — Emitted only when referrer is Some and referral_fee > 0; data: (rf, asset).
  • ("CAddressFunded", asset, source, target) — data: (amount, fee).
§Security Considerations

Unlike fund_c_address, this function does not accept a nonce or deadline parameter. Callers relying on replay protection should use verify_auth_entry in conjunction with this call, or use the standard Stellar transaction sequence-number mechanism.

§Examples
// bridge.fund_c_address_with_referral(
//     &source, &target, &usdc, &1000i128, &Some(referrer),
// );
Source

pub fn query_fee_collector(&self) -> Address

Returns the current fee collector address.

§Errors
Source

pub fn try_query_fee_collector( &self, ) -> Result<Result<Address, <Address as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the current fee collector address.

§Errors
Source

pub fn query_admin(&self) -> Address

Returns the current admin address.

§Errors
Source

pub fn try_query_admin( &self, ) -> Result<Result<Address, <Address as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the current admin address.

§Errors
Source

pub fn query_balance(&self, c_address: &Address, asset: &Address) -> i128

Returns the token balance of c_address for asset.

This is a pure read-through to the token contract; it does not require the contract to be initialised and has no access-control checks.

§Arguments
  • c_address (Address) — The address whose balance is queried.
  • asset (Address) — The token contract address.
Source

pub fn try_query_balance( &self, c_address: &Address, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the token balance of c_address for asset.

This is a pure read-through to the token contract; it does not require the contract to be initialised and has no access-control checks.

§Arguments
  • c_address (Address) — The address whose balance is queried.
  • asset (Address) — The token contract address.
Source

pub fn query_all_balances(&self, assets: &Vec<Address>) -> Map<Address, i128>

Returns the bridge contract’s own balance for each asset in assets.

Useful for monitoring the contract’s total holdings across multiple tokens in a single call.

§Arguments
  • assets (Vec<Address>) — List of token contract addresses to query.
§Returns

A Map<Address, i128> mapping each asset address to the contract’s balance. Assets with a zero balance are included.

§Examples
// let assets = Vec::from_array(&env, [usdc, xlm]);
// let balances = bridge.query_all_balances(&assets);
Source

pub fn try_query_all_balances( &self, assets: &Vec<Address>, ) -> Result<Result<Map<Address, i128>, <Map<Address, i128> as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the bridge contract’s own balance for each asset in assets.

Useful for monitoring the contract’s total holdings across multiple tokens in a single call.

§Arguments
  • assets (Vec<Address>) — List of token contract addresses to query.
§Returns

A Map<Address, i128> mapping each asset address to the contract’s balance. Assets with a zero balance are included.

§Examples
// let assets = Vec::from_array(&env, [usdc, xlm]);
// let balances = bridge.query_all_balances(&assets);
Source

pub fn query_fee_balance(&self, asset: &Address) -> i128

Returns the contract’s total token balance for asset.

This includes both accrued fees and any tokens held for other purposes (e.g. timelocked funds). Use query_accrued_fees to isolate just the fee portion.

§Errors
Source

pub fn try_query_fee_balance( &self, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the contract’s total token balance for asset.

This includes both accrued fees and any tokens held for other purposes (e.g. timelocked funds). Use query_accrued_fees to isolate just the fee portion.

§Errors
Source

pub fn query_is_initialized(&self) -> bool

Returns true if the contract has been initialised.

Source

pub fn try_query_is_initialized( &self, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if the contract has been initialised.

Source

pub fn query_nonce(&self, caller: &Address) -> u64

Returns the current sequential nonce value for caller.

The returned value is the next nonce that must be passed to succeed if the caller chooses to enforce nonce checking. Returns 0 for addresses that have never used a nonce.

§Arguments
  • caller (Address) — The address whose nonce is queried.
Source

pub fn try_query_nonce( &self, caller: &Address, ) -> Result<Result<u64, <u64 as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the current sequential nonce value for caller.

The returned value is the next nonce that must be passed to succeed if the caller chooses to enforce nonce checking. Returns 0 for addresses that have never used a nonce.

§Arguments
  • caller (Address) — The address whose nonce is queried.
Source

pub fn query_calculate_fee(&self, gross_amount: &i128) -> (i128, i128)

Simulates the fee and net amount for a given gross amount at the current global fee rate.

Does not account for per-asset caps or volume tiers; use this for a quick estimate only.

§Arguments
  • gross_amount (i128) — The hypothetical gross transfer amount.
§Returns

(fee, net) where fee = floor(gross × fee_bps / 10_000) and net = gross − fee.

§Examples
// At fee_bps = 100 (1 %):
// let (fee, net) = bridge.query_calculate_fee(&1000i128);
// assert_eq!(fee, 10i128);
// assert_eq!(net, 990i128);
Source

pub fn try_query_calculate_fee( &self, gross_amount: &i128, ) -> Result<Result<(i128, i128), <(i128, i128) as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Simulates the fee and net amount for a given gross amount at the current global fee rate.

Does not account for per-asset caps or volume tiers; use this for a quick estimate only.

§Arguments
  • gross_amount (i128) — The hypothetical gross transfer amount.
§Returns

(fee, net) where fee = floor(gross × fee_bps / 10_000) and net = gross − fee.

§Examples
// At fee_bps = 100 (1 %):
// let (fee, net) = bridge.query_calculate_fee(&1000i128);
// assert_eq!(fee, 10i128);
// assert_eq!(net, 990i128);
Source

pub fn query_total_bridged(&self, asset: &Address) -> i128

Returns the cumulative net amount of asset that has been delivered to recipients since deployment.

“Total bridged” counts only the net portion (gross minus fee), not the gross transferred by sources.

§Errors
Source

pub fn try_query_total_bridged( &self, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the cumulative net amount of asset that has been delivered to recipients since deployment.

“Total bridged” counts only the net portion (gross minus fee), not the gross transferred by sources.

§Errors
Source

pub fn query_total_fees_collected(&self, asset: &Address) -> i128

Returns the cumulative gross fees collected for asset since deployment.

This counter only increases and is not decremented when fees are withdrawn. To see the currently pending (not yet withdrawn) fee balance, use query_accrued_fees.

§Errors
Source

pub fn try_query_total_fees_collected( &self, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the cumulative gross fees collected for asset since deployment.

This counter only increases and is not decremented when fees are withdrawn. To see the currently pending (not yet withdrawn) fee balance, use query_accrued_fees.

§Errors
Source

pub fn pause(&self, nonce: &Option<u64>)

Pauses the contract, disabling all mutating operations.

While paused, calls to fund_c_address, batch_fund_c_address, withdraw_fees, set_fee_bps, set_fee_collector, set_admin, and several other state-modifying functions return BridgeError::ContractPaused. Read-only query_* functions are unaffected.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractPaused",) — data: (admin,)
§Security Considerations

Pausing is an emergency mechanism. It does not prevent the admin from scheduling or executing upgrades, which are intentionally not pause-gated so that an upgrade can fix whatever condition required the pause.

Source

pub fn try_pause( &self, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Pauses the contract, disabling all mutating operations.

While paused, calls to fund_c_address, batch_fund_c_address, withdraw_fees, set_fee_bps, set_fee_collector, set_admin, and several other state-modifying functions return BridgeError::ContractPaused. Read-only query_* functions are unaffected.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractPaused",) — data: (admin,)
§Security Considerations

Pausing is an emergency mechanism. It does not prevent the admin from scheduling or executing upgrades, which are intentionally not pause-gated so that an upgrade can fix whatever condition required the pause.

Source

pub fn unpause(&self, nonce: &Option<u64>)

Resumes normal contract operation after a pause.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUnpaused",) — data: (admin,)
Source

pub fn try_unpause( &self, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Resumes normal contract operation after a pause.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUnpaused",) — data: (admin,)
Source

pub fn query_is_paused(&self) -> bool

Returns true if the contract is currently paused.

Source

pub fn try_query_is_paused( &self, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if the contract is currently paused.

Source

pub fn upgrade(&self, new_wasm_hash: &BytesN<32>, nonce: &Option<u64>)

Immediately upgrades the contract WASM to new_wasm_hash.

This is the untimelocked upgrade path. For production deployments, prefer schedule_upgrade + execute_upgrade which enforces a ~24-hour delay, giving users time to react.

§Arguments
  • new_wasm_hash (BytesN<32>) — The hash of the new WASM blob, which must already have been uploaded to the network via Deployer::upload_contract_wasm.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUpgraded",) — data: (old_hash, new_wasm_hash, admin)
§Security Considerations

After this call the contract executes new code in the same transaction. The old_hash in the event lets off-chain monitors detect unexpected upgrades. Consider using the timelocked path for mainnet deployments.

Source

pub fn try_upgrade( &self, new_wasm_hash: &BytesN<32>, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Immediately upgrades the contract WASM to new_wasm_hash.

This is the untimelocked upgrade path. For production deployments, prefer schedule_upgrade + execute_upgrade which enforces a ~24-hour delay, giving users time to react.

§Arguments
  • new_wasm_hash (BytesN<32>) — The hash of the new WASM blob, which must already have been uploaded to the network via Deployer::upload_contract_wasm.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUpgraded",) — data: (old_hash, new_wasm_hash, admin)
§Security Considerations

After this call the contract executes new code in the same transaction. The old_hash in the event lets off-chain monitors detect unexpected upgrades. Consider using the timelocked path for mainnet deployments.

Source

pub fn schedule_upgrade( &self, new_wasm_hash: &BytesN<32>, nonce: &Option<u64>, ) -> u32

Schedules a WASM upgrade that becomes executable after a ~24-hour timelock.

The upgrade is executable once env.ledger().sequence() ≥ current_sequence + UPGRADE_TIMELOCK_LEDGERS (17 280 ledgers at 5 s/ledger ≈ 24 hours).

Only one pending upgrade may exist at a time. Call cancel_upgrade first if you need to replace a pending upgrade.

§Arguments
  • new_wasm_hash (BytesN<32>) — Hash of the new WASM blob to apply after the timelock elapses.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Returns

The ledger sequence number at or after which execute_upgrade may be called (executable_after_ledger).

§Errors
§Events
  • ("UpgradeScheduled",) — data: (new_wasm_hash, executable_after_ledger, admin)
§Security Considerations

Off-chain monitoring tools should watch for UpgradeScheduled events and alert stakeholders so they can review the proposed WASM before the timelock expires. Use cancel_upgrade to abort if the scheduled hash turns out to be malicious.

§Examples
// let unlock_ledger = bridge.schedule_upgrade(&new_wasm_hash, &None);
// // wait until env.ledger().sequence() >= unlock_ledger, then:
// bridge.execute_upgrade(&new_wasm_hash, &None);
Source

pub fn try_schedule_upgrade( &self, new_wasm_hash: &BytesN<32>, nonce: &Option<u64>, ) -> Result<Result<u32, <u32 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Schedules a WASM upgrade that becomes executable after a ~24-hour timelock.

The upgrade is executable once env.ledger().sequence() ≥ current_sequence + UPGRADE_TIMELOCK_LEDGERS (17 280 ledgers at 5 s/ledger ≈ 24 hours).

Only one pending upgrade may exist at a time. Call cancel_upgrade first if you need to replace a pending upgrade.

§Arguments
  • new_wasm_hash (BytesN<32>) — Hash of the new WASM blob to apply after the timelock elapses.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Returns

The ledger sequence number at or after which execute_upgrade may be called (executable_after_ledger).

§Errors
§Events
  • ("UpgradeScheduled",) — data: (new_wasm_hash, executable_after_ledger, admin)
§Security Considerations

Off-chain monitoring tools should watch for UpgradeScheduled events and alert stakeholders so they can review the proposed WASM before the timelock expires. Use cancel_upgrade to abort if the scheduled hash turns out to be malicious.

§Examples
// let unlock_ledger = bridge.schedule_upgrade(&new_wasm_hash, &None);
// // wait until env.ledger().sequence() >= unlock_ledger, then:
// bridge.execute_upgrade(&new_wasm_hash, &None);
Source

pub fn execute_upgrade(&self, expected_hash: &BytesN<32>, nonce: &Option<u64>)

Executes a previously scheduled upgrade once its timelock has elapsed.

expected_hash must match the hash that was passed to schedule_upgrade. This prevents a race condition where the admin could change the pending hash between scheduling and execution by requiring the caller to commit to the exact hash they are applying.

The pending upgrade record is cleared before calling update_current_contract_wasm to prevent re-entrant replay.

§Arguments
  • expected_hash (BytesN<32>) — Must match PendingUpgrade::new_wasm_hash.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUpgraded",) — data: (old_hash, new_wasm_hash, admin)
Source

pub fn try_execute_upgrade( &self, expected_hash: &BytesN<32>, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Executes a previously scheduled upgrade once its timelock has elapsed.

expected_hash must match the hash that was passed to schedule_upgrade. This prevents a race condition where the admin could change the pending hash between scheduling and execution by requiring the caller to commit to the exact hash they are applying.

The pending upgrade record is cleared before calling update_current_contract_wasm to prevent re-entrant replay.

§Arguments
  • expected_hash (BytesN<32>) — Must match PendingUpgrade::new_wasm_hash.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("ContractUpgraded",) — data: (old_hash, new_wasm_hash, admin)
Source

pub fn cancel_upgrade(&self, nonce: &Option<u64>)

Cancels a pending scheduled upgrade.

After cancellation, execute_upgrade will return BridgeError::UpgradeNotScheduled until a new upgrade is scheduled.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("UpgradeCancelled",) — data: (cancelled_wasm_hash, admin)
Source

pub fn try_cancel_upgrade( &self, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Cancels a pending scheduled upgrade.

After cancellation, execute_upgrade will return BridgeError::UpgradeNotScheduled until a new upgrade is scheduled.

§Arguments
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("UpgradeCancelled",) — data: (cancelled_wasm_hash, admin)
Source

pub fn query_pending_upgrade(&self) -> Option<PendingUpgrade>

Returns the pending scheduled upgrade, if any.

Returns None if no upgrade has been scheduled or if a previous upgrade has already been executed or cancelled.

Source

pub fn try_query_pending_upgrade( &self, ) -> Result<Result<Option<PendingUpgrade>, <Option<PendingUpgrade> as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the pending scheduled upgrade, if any.

Returns None if no upgrade has been scheduled or if a previous upgrade has already been executed or cancelled.

Source

pub fn emergency_migrate(&self, new_contract: &Address, migrate_data: &bool)

Migrates the contract state to a new contract address in case of emergency.

§Arguments
  • new_contract (Address) — The address of the new contract.
  • migrate_data (bool) — If true, emits all contract state as events.
§Authorization

Requires the current admin’s require_auth().

Source

pub fn try_emergency_migrate( &self, new_contract: &Address, migrate_data: &bool, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Migrates the contract state to a new contract address in case of emergency.

§Arguments
  • new_contract (Address) — The address of the new contract.
  • migrate_data (bool) — If true, emits all contract state as events.
§Authorization

Requires the current admin’s require_auth().

Source

pub fn add_to_blocklist(&self, address: &Address, nonce: &Option<u64>)

Adds address to the blocklist.

Blocked addresses cannot be used as target in any funding call. Existing timelocked entries for a blocked address are not affected retroactively; however, claim_timelocked itself is not blocked (the recipient calls it directly). Blocking takes effect immediately for all new funding calls.

§Arguments
  • address (Address) — The address to block.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_add_to_blocklist( &self, address: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Adds address to the blocklist.

Blocked addresses cannot be used as target in any funding call. Existing timelocked entries for a blocked address are not affected retroactively; however, claim_timelocked itself is not blocked (the recipient calls it directly). Blocking takes effect immediately for all new funding calls.

§Arguments
  • address (Address) — The address to block.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn remove_from_blocklist(&self, address: &Address, nonce: &Option<u64>)

Removes address from the blocklist, restoring its ability to receive funds.

§Arguments
  • address (Address) — The address to unblock.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_remove_from_blocklist( &self, address: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Removes address from the blocklist, restoring its ability to receive funds.

§Arguments
  • address (Address) — The address to unblock.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn add_to_allowlist(&self, address: &Address, nonce: &Option<u64>)

Adds address to the allowlist.

Only relevant when the contract is in allowlist mode (set_allowlist_mode(true)). In that mode, only allowlisted addresses may be used as target in funding calls.

§Arguments
  • address (Address) — The address to allowlist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_add_to_allowlist( &self, address: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Adds address to the allowlist.

Only relevant when the contract is in allowlist mode (set_allowlist_mode(true)). In that mode, only allowlisted addresses may be used as target in funding calls.

§Arguments
  • address (Address) — The address to allowlist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn remove_from_allowlist(&self, address: &Address, nonce: &Option<u64>)

Removes address from the allowlist.

If the contract is in allowlist mode, the address will no longer be able to receive funds until re-added.

§Arguments
  • address (Address) — The address to remove from the allowlist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_remove_from_allowlist( &self, address: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Removes address from the allowlist.

If the contract is in allowlist mode, the address will no longer be able to receive funds until re-added.

§Arguments
  • address (Address) — The address to remove from the allowlist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn set_allowlist_mode(&self, enabled: &bool, nonce: &Option<u64>)

Enables or disables allowlist mode.

When enabled is true, only addresses that have been explicitly added via add_to_allowlist may receive tokens. When false (the default), any non-blocked address may receive tokens.

The blocklist is always enforced regardless of this setting.

§Arguments
  • enabled (bool) — true to enable allowlist mode, false to disable.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_set_allowlist_mode( &self, enabled: &bool, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Enables or disables allowlist mode.

When enabled is true, only addresses that have been explicitly added via add_to_allowlist may receive tokens. When false (the default), any non-blocked address may receive tokens.

The blocklist is always enforced regardless of this setting.

§Arguments
  • enabled (bool) — true to enable allowlist mode, false to disable.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn query_is_blocked(&self, address: &Address) -> bool

Returns true if address is on the blocklist.

Source

pub fn try_query_is_blocked( &self, address: &Address, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if address is on the blocklist.

Source

pub fn query_is_allowlisted(&self, address: &Address) -> bool

Returns true if address is on the allowlist.

Source

pub fn try_query_is_allowlisted( &self, address: &Address, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if address is on the allowlist.

Source

pub fn query_allowlist_mode(&self) -> bool

Returns true if allowlist mode is currently enabled.

Source

pub fn try_query_allowlist_mode( &self, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if allowlist mode is currently enabled.

Source

pub fn reclaim_tokens( &self, asset: &Address, amount: &i128, destination: &Address, nonce: &Option<u64>, )

Allows the admin to recover tokens that were accidentally sent to the contract and are not owed as fees.

The reclaimable amount is contract_token_balance − accrued_fees. This ensures the admin cannot drain fee reserves that belong to the fee collector.

§Arguments
  • asset (Address) — The token to reclaim.
  • amount (i128) — Amount to recover. Must be > 0 and ≤ reclaimable.
  • destination (Address) — Address to send the recovered tokens to.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("TokensReclaimed", admin, asset) — data: (amount, destination)
§Security Considerations

The check reclaimable = balance − accrued_fees − locked_timelock ensures that both fee reserves and unclaimed TimelockEntry deposits are ring-fenced: locked_timelock is a running per-asset total incremented in fund_c_address_timelocked and decremented in claim_timelocked, so admins cannot drain tokens that are owed to a pending timelock claim. Unrevealed CommitmentEntry records created by commit_fund never hold contract balance in the first place — reveal_fund pulls the tokens from source and forwards them to target atomically within a single call — so no separate accounting is required for them.

Source

pub fn try_reclaim_tokens( &self, asset: &Address, amount: &i128, destination: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Allows the admin to recover tokens that were accidentally sent to the contract and are not owed as fees.

The reclaimable amount is contract_token_balance − accrued_fees. This ensures the admin cannot drain fee reserves that belong to the fee collector.

§Arguments
  • asset (Address) — The token to reclaim.
  • amount (i128) — Amount to recover. Must be > 0 and ≤ reclaimable.
  • destination (Address) — Address to send the recovered tokens to.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("TokensReclaimed", admin, asset) — data: (amount, destination)
§Security Considerations

The check reclaimable = balance − accrued_fees − locked_timelock ensures that both fee reserves and unclaimed TimelockEntry deposits are ring-fenced: locked_timelock is a running per-asset total incremented in fund_c_address_timelocked and decremented in claim_timelocked, so admins cannot drain tokens that are owed to a pending timelock claim. Unrevealed CommitmentEntry records created by commit_fund never hold contract balance in the first place — reveal_fund pulls the tokens from source and forwards them to target atomically within a single call — so no separate accounting is required for them.

Source

pub fn add_asset(&self, asset: &Address, nonce: &Option<u64>)

Adds asset to the token whitelist.

Only whitelisted assets may be used in fund_c_address, batch_fund_c_address, and related funding functions. Adding an asset that is already whitelisted is idempotent.

§Arguments
  • asset (Address) — The token contract address to whitelist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_add_asset( &self, asset: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Adds asset to the token whitelist.

Only whitelisted assets may be used in fund_c_address, batch_fund_c_address, and related funding functions. Adding an asset that is already whitelisted is idempotent.

§Arguments
  • asset (Address) — The token contract address to whitelist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn remove_asset(&self, asset: &Address, nonce: &Option<u64>)

Removes asset from the token whitelist.

After removal, any funding call that references this asset returns BridgeError::AssetNotWhitelisted. Existing accrued fee counters and historical stats for the asset are retained in storage.

§Arguments
  • asset (Address) — The token contract address to remove.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_remove_asset( &self, asset: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Removes asset from the token whitelist.

After removal, any funding call that references this asset returns BridgeError::AssetNotWhitelisted. Existing accrued fee counters and historical stats for the asset are retained in storage.

§Arguments
  • asset (Address) — The token contract address to remove.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn query_is_asset_whitelisted(&self, asset: &Address) -> bool

Returns true if asset is currently on the whitelist.

§Errors
Source

pub fn try_query_is_asset_whitelisted( &self, asset: &Address, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns true if asset is currently on the whitelist.

§Errors
Source

pub fn query_whitelisted_assets(&self) -> Vec<Address>

Returns the list of all currently whitelisted asset addresses.

§Errors
Source

pub fn try_query_whitelisted_assets( &self, ) -> Result<Result<Vec<Address>, <Vec<Address> as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the list of all currently whitelisted asset addresses.

§Errors
Source

pub fn add_swap_pool(&self, pool: &Address, nonce: &Option<u64>)

Adds pool to the DEX swap-pool whitelist.

Only whitelisted pool addresses may appear in the swap_route passed to fund_c_address_with_swap. Adding a pool that is already whitelisted is idempotent.

§Arguments
  • pool (Address) — The DEX pool contract address to whitelist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_add_swap_pool( &self, pool: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Adds pool to the DEX swap-pool whitelist.

Only whitelisted pool addresses may appear in the swap_route passed to fund_c_address_with_swap. Adding a pool that is already whitelisted is idempotent.

§Arguments
  • pool (Address) — The DEX pool contract address to whitelist.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn remove_swap_pool(&self, pool: &Address, nonce: &Option<u64>)

Removes pool from the DEX swap-pool whitelist.

After removal, any fund_c_address_with_swap call whose swap_route references this pool returns BridgeError::PoolNotWhitelisted.

§Arguments
  • pool (Address) — The DEX pool contract address to remove.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_remove_swap_pool( &self, pool: &Address, nonce: &Option<u64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Removes pool from the DEX swap-pool whitelist.

After removal, any fund_c_address_with_swap call whose swap_route references this pool returns BridgeError::PoolNotWhitelisted.

§Arguments
  • pool (Address) — The DEX pool contract address to remove.
  • nonce (Option<u64>) — Optional sequential nonce for the admin.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn query_is_pool_whitelisted(&self, pool: &Address) -> bool

Returns true if pool is currently on the swap-pool whitelist.

§Errors
Source

pub fn try_query_is_pool_whitelisted( &self, pool: &Address, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns true if pool is currently on the swap-pool whitelist.

§Errors
Source

pub fn set_loyalty_token(&self, token: &Address, amount_per_fund: &i128)

Configures the loyalty token and the fixed reward minted to the source on every successful fund_c_address call.

The contract must already hold a balance of token equal to or greater than the rewards it intends to distribute. There is no automatic minting; the contract transfers from its own balance.

§Arguments
  • token (Address) — The loyalty token contract address.
  • amount_per_fund (i128) — Fixed amount transferred to source on each fund_c_address call. Use 0 to effectively disable rewards. Must be ≥ 0.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("LoyaltyTokenSet", admin) — data: (token, amount_per_fund)
Source

pub fn try_set_loyalty_token( &self, token: &Address, amount_per_fund: &i128, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Configures the loyalty token and the fixed reward minted to the source on every successful fund_c_address call.

The contract must already hold a balance of token equal to or greater than the rewards it intends to distribute. There is no automatic minting; the contract transfers from its own balance.

§Arguments
  • token (Address) — The loyalty token contract address.
  • amount_per_fund (i128) — Fixed amount transferred to source on each fund_c_address call. Use 0 to effectively disable rewards. Must be ≥ 0.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("LoyaltyTokenSet", admin) — data: (token, amount_per_fund)
Source

pub fn query_loyalty_token(&self) -> (Address, i128)

Returns the loyalty token address and reward amount per fund.

§Returns

(token_address, amount_per_fund).

§Errors
Source

pub fn try_query_loyalty_token( &self, ) -> Result<Result<(Address, i128), <(Address, i128) as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the loyalty token address and reward amount per fund.

§Returns

(token_address, amount_per_fund).

§Errors
Source

pub fn set_fee_tiers(&self, tiers: &Vec<FeeTier>)

Configures volume-based fee tiers for the bridge.

Once tiers are set, the fee applied to a fund_c_address call is determined by the source address’s cumulative bridged volume:

for each tier in tiers:
    if source_volume ∈ [tier.min_volume, tier.max_volume]:
        effective_fee_bps = tier.fee_bps
        break
else:
    effective_fee_bps = global_fee_bps  (fallback)

The per-asset cap still applies on top of the tiered rate.

§Arguments
  • tiers (Vec<FeeTier>) — Ordered list of fee tiers. Each tier’s fee_bps must be ≤ 1 000.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeTiersSet", admin) — data: (tiers.len(),)
Source

pub fn try_set_fee_tiers( &self, tiers: &Vec<FeeTier>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Configures volume-based fee tiers for the bridge.

Once tiers are set, the fee applied to a fund_c_address call is determined by the source address’s cumulative bridged volume:

for each tier in tiers:
    if source_volume ∈ [tier.min_volume, tier.max_volume]:
        effective_fee_bps = tier.fee_bps
        break
else:
    effective_fee_bps = global_fee_bps  (fallback)

The per-asset cap still applies on top of the tiered rate.

§Arguments
  • tiers (Vec<FeeTier>) — Ordered list of fee tiers. Each tier’s fee_bps must be ≤ 1 000.
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("FeeTiersSet", admin) — data: (tiers.len(),)
Source

pub fn query_fee_tiers(&self) -> Vec<FeeTier>

Returns the configured fee tiers.

If no tiers have been set, returns a single synthetic tier covering the full volume range [0, i128::MAX] at the current global fee rate.

§Errors
Source

pub fn try_query_fee_tiers( &self, ) -> Result<Result<Vec<FeeTier>, <Vec<FeeTier> as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the configured fee tiers.

If no tiers have been set, returns a single synthetic tier covering the full volume range [0, i128::MAX] at the current global fee rate.

§Errors
Source

pub fn query_current_tier(&self, source: &Address) -> FeeTier

Returns the fee tier that currently applies to source, based on their cumulative bridged volume.

If no tier matches, returns a synthetic default tier using the global fee rate, covering the full volume range.

§Arguments
  • source (Address) — The address to look up.
§Errors
Source

pub fn try_query_current_tier( &self, source: &Address, ) -> Result<Result<FeeTier, <FeeTier as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the fee tier that currently applies to source, based on their cumulative bridged volume.

If no tier matches, returns a synthetic default tier using the global fee rate, covering the full volume range.

§Arguments
  • source (Address) — The address to look up.
§Errors
Source

pub fn fund_c_address_crosschain( &self, chain_id: &u32, tx_hash: &BytesN<32>, target: &Address, asset: &Address, amount: &i128, sigs: &Vec<RelayerSig>, )

Credits a C-address from a cross-chain event, verified by M-of-N relayer signatures.

This function allows off-chain relayers to bridge tokens that arrived on another chain (e.g. Ethereum, Solana) to a Soroban C-address. The contract must already hold a sufficient balance of asset to pay out net_amount to the target.

§Payload Construction

Relayers must sign sha256(payload) where:

nonce   = sha256(chain_id_be4 || tx_hash)
payload = chain_id_be4
       || tx_hash
       || sha256(target_strkey_bytes)
       || sha256(asset_strkey_bytes)
       || amount_be16
       || nonce
§Parameters
  • chain_id (u32) — Numeric source-chain ID (e.g. 1 = Ethereum mainnet, 101 = Solana mainnet).
  • tx_hash (BytesN<32>) — The 32-byte hash of the source-chain transaction.
  • target (Address) — The Soroban C-address to credit.
  • asset (Address) — Whitelisted token contract address.
  • amount (i128) — Gross amount (fee is deducted before crediting target).
  • sigs (Vec<RelayerSig>) — At least threshold distinct relayer Ed25519 signatures over the payload hash (see above).
§Authorization

No Soroban require_auth — authentication is via Ed25519 signatures from registered relayers. The caller may be any account.

§Errors
§Events
  • ("CrossChainFunded", target) — data: (chain_id, tx_hash, amount, fee, asset)
§Security Considerations

The nonce is derived deterministically from (chain_id, tx_hash) and marked used before the token transfer, preventing replay attacks. An invalid Ed25519 signature causes a host-level trap (panic) rather than returning an error code, so callers should pre-validate signatures off-chain. The contract verifies that sigs contains distinct pubkeys — a relayer submitting the same signature twice only counts once toward the threshold; duplicates are rejected with BridgeError::DuplicateRelayerSignature.

Source

pub fn try_fund_c_address_crosschain( &self, chain_id: &u32, tx_hash: &BytesN<32>, target: &Address, asset: &Address, amount: &i128, sigs: &Vec<RelayerSig>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Credits a C-address from a cross-chain event, verified by M-of-N relayer signatures.

This function allows off-chain relayers to bridge tokens that arrived on another chain (e.g. Ethereum, Solana) to a Soroban C-address. The contract must already hold a sufficient balance of asset to pay out net_amount to the target.

§Payload Construction

Relayers must sign sha256(payload) where:

nonce   = sha256(chain_id_be4 || tx_hash)
payload = chain_id_be4
       || tx_hash
       || sha256(target_strkey_bytes)
       || sha256(asset_strkey_bytes)
       || amount_be16
       || nonce
§Parameters
  • chain_id (u32) — Numeric source-chain ID (e.g. 1 = Ethereum mainnet, 101 = Solana mainnet).
  • tx_hash (BytesN<32>) — The 32-byte hash of the source-chain transaction.
  • target (Address) — The Soroban C-address to credit.
  • asset (Address) — Whitelisted token contract address.
  • amount (i128) — Gross amount (fee is deducted before crediting target).
  • sigs (Vec<RelayerSig>) — At least threshold distinct relayer Ed25519 signatures over the payload hash (see above).
§Authorization

No Soroban require_auth — authentication is via Ed25519 signatures from registered relayers. The caller may be any account.

§Errors
§Events
  • ("CrossChainFunded", target) — data: (chain_id, tx_hash, amount, fee, asset)
§Security Considerations

The nonce is derived deterministically from (chain_id, tx_hash) and marked used before the token transfer, preventing replay attacks. An invalid Ed25519 signature causes a host-level trap (panic) rather than returning an error code, so callers should pre-validate signatures off-chain. The contract verifies that sigs contains distinct pubkeys — a relayer submitting the same signature twice only counts once toward the threshold; duplicates are rejected with BridgeError::DuplicateRelayerSignature.

Source

pub fn add_relayer(&self, pubkey: &BytesN<32>)

Registers an Ed25519 public key as a trusted relayer.

Registered relayers may contribute signatures to fund_c_address_crosschain. Adding the same public key twice is idempotent.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key of the relayer.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_add_relayer( &self, pubkey: &BytesN<32>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Registers an Ed25519 public key as a trusted relayer.

Registered relayers may contribute signatures to fund_c_address_crosschain. Adding the same public key twice is idempotent.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key of the relayer.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn remove_relayer(&self, pubkey: &BytesN<32>)

Removes a relayer from the trusted set.

The removal is rejected if it would reduce the active relayer count below the current threshold, which would make cross-chain funding impossible.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key of the relayer to remove.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_remove_relayer( &self, pubkey: &BytesN<32>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Removes a relayer from the trusted set.

The removal is rejected if it would reduce the active relayer count below the current threshold, which would make cross-chain funding impossible.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key of the relayer to remove.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn set_relayer_threshold(&self, threshold: &u32)

Sets the minimum number of relayer signatures required to process a cross-chain funding event.

§Arguments
  • threshold (u32) — Must be ≤ the current number of registered relayers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_set_relayer_threshold( &self, threshold: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Sets the minimum number of relayer signatures required to process a cross-chain funding event.

§Arguments
  • threshold (u32) — Must be ≤ the current number of registered relayers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn query_relayer_threshold(&self) -> u32

Returns the current M-of-N relayer signature threshold.

§Errors
Source

pub fn try_query_relayer_threshold( &self, ) -> Result<Result<u32, <u32 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the current M-of-N relayer signature threshold.

§Errors
Source

pub fn query_is_relayer(&self, pubkey: &BytesN<32>) -> bool

Returns true if pubkey is a registered relayer.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key to check.
§Errors
Source

pub fn try_query_is_relayer( &self, pubkey: &BytesN<32>, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns true if pubkey is a registered relayer.

§Arguments
  • pubkey (BytesN<32>) — Ed25519 public key to check.
§Errors
Source

pub fn fund_c_address_timelocked( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, release_time: &u64, cliff_time: &u64, ) -> u64

Creates a time-gated funding record.

Transfers amount from source into the contract immediately. The tokens remain locked until release_time, at which point target may call claim_timelocked to receive the net amount (after fee deduction).

§Arguments
  • source (Address) — The address depositing the tokens. Must authorise.
  • target (Address) — The address that may claim the tokens after release_time.
  • asset (Address) — The whitelisted token contract.
  • amount (i128) — Gross amount to lock. Must be > 0.
  • release_time (u64) — Unix timestamp (seconds) after which the tokens may be claimed. Must be strictly in the future.
  • cliff_time (u64) — Optional cliff timestamp. If > 0 it must be ≤ release_time. Currently informational only; not enforced by claim_timelocked.
§Authorization

Requires source.require_auth().

§Returns

The numeric ID of the newly created timelock entry. Use this ID with claim_timelocked and query_timelocked.

§Errors
§Events
  • ("TimelockCreated", source, target) — data: (id, amount, asset, release_time, cliff_time)
§Security Considerations

The fee rate applied is the rate at claim time, not deposit time. If the global fee rate changes between deposit and claim, the net amount received by target may differ from the amount at deposit time.

Source

pub fn try_fund_c_address_timelocked( &self, source: &Address, target: &Address, asset: &Address, amount: &i128, release_time: &u64, cliff_time: &u64, ) -> Result<Result<u64, <u64 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Creates a time-gated funding record.

Transfers amount from source into the contract immediately. The tokens remain locked until release_time, at which point target may call claim_timelocked to receive the net amount (after fee deduction).

§Arguments
  • source (Address) — The address depositing the tokens. Must authorise.
  • target (Address) — The address that may claim the tokens after release_time.
  • asset (Address) — The whitelisted token contract.
  • amount (i128) — Gross amount to lock. Must be > 0.
  • release_time (u64) — Unix timestamp (seconds) after which the tokens may be claimed. Must be strictly in the future.
  • cliff_time (u64) — Optional cliff timestamp. If > 0 it must be ≤ release_time. Currently informational only; not enforced by claim_timelocked.
§Authorization

Requires source.require_auth().

§Returns

The numeric ID of the newly created timelock entry. Use this ID with claim_timelocked and query_timelocked.

§Errors
§Events
  • ("TimelockCreated", source, target) — data: (id, amount, asset, release_time, cliff_time)
§Security Considerations

The fee rate applied is the rate at claim time, not deposit time. If the global fee rate changes between deposit and claim, the net amount received by target may differ from the amount at deposit time.

Source

pub fn claim_timelocked(&self, id: &u64)

Claims a matured timelock entry, releasing the net tokens to target.

The effective fee at the time of claiming is deducted from amount and the net is transferred to target. The timelock entry is marked claimed = true to prevent double-claims.

§Arguments
  • id (u64) — The timelock entry ID returned by fund_c_address_timelocked.
§Authorization

Requires target.require_auth() (the recipient of the timelock entry).

§Errors
§Events
  • ("TimelockClaimed", target) — data: (id, net_amount, fee, asset)
§Security Considerations

The claimed flag is persisted before the token transfer. Because Soroban execution is single-threaded within a ledger, this effectively prevents re-entrancy. The fee rate is the current global rate at claim time, which may differ from the rate at deposit time.

Source

pub fn try_claim_timelocked( &self, id: &u64, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Claims a matured timelock entry, releasing the net tokens to target.

The effective fee at the time of claiming is deducted from amount and the net is transferred to target. The timelock entry is marked claimed = true to prevent double-claims.

§Arguments
  • id (u64) — The timelock entry ID returned by fund_c_address_timelocked.
§Authorization

Requires target.require_auth() (the recipient of the timelock entry).

§Errors
§Events
  • ("TimelockClaimed", target) — data: (id, net_amount, fee, asset)
§Security Considerations

The claimed flag is persisted before the token transfer. Because Soroban execution is single-threaded within a ledger, this effectively prevents re-entrancy. The fee rate is the current global rate at claim time, which may differ from the rate at deposit time.

Source

pub fn query_timelocked(&self, id: &u64) -> TimelockEntry

Returns the timelock entry for id.

§Arguments
  • id (u64) — The timelock entry ID.
§Errors
Source

pub fn try_query_timelocked( &self, id: &u64, ) -> Result<Result<TimelockEntry, <TimelockEntry as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the timelock entry for id.

§Arguments
  • id (u64) — The timelock entry ID.
§Errors
Source

pub fn extend_instance_ttl(&self, ttl: &u32)

Extends the instance-storage TTL to ensure contract state does not expire.

ttl is capped at MAX_ALLOWED_TTL (3 110 400 ledgers, ~1 year). The threshold used to trigger extension is ttl / 4.

§Arguments
  • ttl (u32) — Desired TTL in ledgers (capped at MAX_ALLOWED_TTL).
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("InstanceTtlExtended",) — data: (admin, actual_ttl)
Source

pub fn try_extend_instance_ttl( &self, ttl: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Extends the instance-storage TTL to ensure contract state does not expire.

ttl is capped at MAX_ALLOWED_TTL (3 110 400 ledgers, ~1 year). The threshold used to trigger extension is ttl / 4.

§Arguments
  • ttl (u32) — Desired TTL in ledgers (capped at MAX_ALLOWED_TTL).
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("InstanceTtlExtended",) — data: (admin, actual_ttl)
Source

pub fn extend_persistent_ttl(&self, key_asset: &Address, ttl: &u32)

Extends the persistent-storage TTL for the three per-asset counter keys (AccruedFees, TotalBridged, TotalFeesCollected) of key_asset.

Only keys that already exist in storage are extended; missing keys are silently skipped.

§Arguments
  • key_asset (Address) — The asset whose persistent counters should have their TTL extended.
  • ttl (u32) — Desired TTL in ledgers (capped at MAX_ALLOWED_TTL).
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("PersistentTtlExtended",) — data: (admin, key_asset, actual_ttl)
Source

pub fn try_extend_persistent_ttl( &self, key_asset: &Address, ttl: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Extends the persistent-storage TTL for the three per-asset counter keys (AccruedFees, TotalBridged, TotalFeesCollected) of key_asset.

Only keys that already exist in storage are extended; missing keys are silently skipped.

§Arguments
  • key_asset (Address) — The asset whose persistent counters should have their TTL extended.
  • ttl (u32) — Desired TTL in ledgers (capped at MAX_ALLOWED_TTL).
§Authorization

Requires the current admin’s require_auth().

§Errors
§Events
  • ("PersistentTtlExtended",) — data: (admin, key_asset, actual_ttl)
Source

pub fn set_max_instance_ttl(&self, ttl: &u32)

Overrides the maximum instance-storage TTL used by the internal extend_instance_ttl helper called on every mutating operation.

Values above MAX_ALLOWED_TTL are silently capped.

§Arguments
  • ttl (u32) — New maximum in ledgers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_set_max_instance_ttl( &self, ttl: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Overrides the maximum instance-storage TTL used by the internal extend_instance_ttl helper called on every mutating operation.

Values above MAX_ALLOWED_TTL are silently capped.

§Arguments
  • ttl (u32) — New maximum in ledgers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn set_max_persistent_ttl(&self, ttl: &u32)

Overrides the maximum persistent-storage TTL used by extend_persistent_ttl.

Values above MAX_ALLOWED_TTL are silently capped.

§Arguments
  • ttl (u32) — New maximum in ledgers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn try_set_max_persistent_ttl( &self, ttl: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Overrides the maximum persistent-storage TTL used by extend_persistent_ttl.

Values above MAX_ALLOWED_TTL are silently capped.

§Arguments
  • ttl (u32) — New maximum in ledgers.
§Authorization

Requires the current admin’s require_auth().

§Errors
Source

pub fn query_ttl_config(&self) -> (u32, u32, u32, u32)

Returns the four TTL configuration values.

§Returns

(max_instance_ttl, max_persistent_ttl, hard_ceiling, critical_threshold) where:

  • max_instance_ttl — current configurable max for instance storage
  • max_persistent_ttl — current configurable max for persistent storage
  • hard_ceiling — MAX_ALLOWED_TTL constant (3 110 400 ledgers)
  • critical_threshold — CRITICAL_ENTRY_TTL_THRESHOLD (100 000 ledgers)
§Errors
Source

pub fn try_query_ttl_config( &self, ) -> Result<Result<(u32, u32, u32, u32), <(u32, u32, u32, u32) as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the four TTL configuration values.

§Returns

(max_instance_ttl, max_persistent_ttl, hard_ceiling, critical_threshold) where:

  • max_instance_ttl — current configurable max for instance storage
  • max_persistent_ttl — current configurable max for persistent storage
  • hard_ceiling — MAX_ALLOWED_TTL constant (3 110 400 ledgers)
  • critical_threshold — CRITICAL_ENTRY_TTL_THRESHOLD (100 000 ledgers)
§Errors
Source

pub fn verify_auth_entry( &self, source: &Address, nonce: &u64, valid_after_ledger: &u32, valid_before_ledger: &u32, )

Validates and permanently consumes a Soroban authorization-entry nonce.

This prevents Soroban authorization-entry reuse attacks by:

  1. Requiring the current ledger sequence to be within [valid_after_ledger, valid_before_ledger).
  2. Checking that (source, nonce) has not been used before.
  3. Permanently marking the pair as used in persistent storage.
  4. Emitting AuthUsed(source, nonce) for off-chain tracking.

The nonce is scoped to this contract’s own persistent storage, so the same numeric nonce may be used with a different contract without conflict.

§Arguments
  • source (Address) — The address whose authorization entry is consumed.
  • nonce (u64) — The nonce to burn. Must not have been used before.
  • valid_after_ledger (u32) — Inclusive lower bound on the current ledger sequence number.
  • valid_before_ledger (u32) — Exclusive upper bound on the current ledger sequence number.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("AuthUsed", source) — data: (nonce,)
§Security Considerations

The window [valid_after_ledger, valid_before_ledger) should be kept narrow (e.g. current ledger ± a few hundred blocks) to minimise the replay window. Once consumed, a (source, nonce) pair can never be re-used regardless of how much time passes.

§Examples
// let nonce = bridge.query_auth_nonce(&source);
// let seq = env.ledger().sequence();
// bridge.verify_auth_entry(&source, &nonce, &seq, &(seq + 100));
Source

pub fn try_verify_auth_entry( &self, source: &Address, nonce: &u64, valid_after_ledger: &u32, valid_before_ledger: &u32, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Validates and permanently consumes a Soroban authorization-entry nonce.

This prevents Soroban authorization-entry reuse attacks by:

  1. Requiring the current ledger sequence to be within [valid_after_ledger, valid_before_ledger).
  2. Checking that (source, nonce) has not been used before.
  3. Permanently marking the pair as used in persistent storage.
  4. Emitting AuthUsed(source, nonce) for off-chain tracking.

The nonce is scoped to this contract’s own persistent storage, so the same numeric nonce may be used with a different contract without conflict.

§Arguments
  • source (Address) — The address whose authorization entry is consumed.
  • nonce (u64) — The nonce to burn. Must not have been used before.
  • valid_after_ledger (u32) — Inclusive lower bound on the current ledger sequence number.
  • valid_before_ledger (u32) — Exclusive upper bound on the current ledger sequence number.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("AuthUsed", source) — data: (nonce,)
§Security Considerations

The window [valid_after_ledger, valid_before_ledger) should be kept narrow (e.g. current ledger ± a few hundred blocks) to minimise the replay window. Once consumed, a (source, nonce) pair can never be re-used regardless of how much time passes.

§Examples
// let nonce = bridge.query_auth_nonce(&source);
// let seq = env.ledger().sequence();
// bridge.verify_auth_entry(&source, &nonce, &seq, &(seq + 100));
Source

pub fn query_auth_nonce(&self, source: &Address) -> u64

Returns the next unused auth nonce for source.

This is the lowest nonce value that has not yet been consumed for this address. Callers should use this value when constructing a new authorization entry to pass to verify_auth_entry.

§Arguments
  • source (Address) — The address to query.
Source

pub fn try_query_auth_nonce( &self, source: &Address, ) -> Result<Result<u64, <u64 as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the next unused auth nonce for source.

This is the lowest nonce value that has not yet been consumed for this address. Callers should use this value when constructing a new authorization entry to pass to verify_auth_entry.

§Arguments
  • source (Address) — The address to query.
Source

pub fn query_auth_nonce_used(&self, source: &Address, nonce: &u64) -> bool

Returns true if a specific auth nonce has already been consumed for source.

§Arguments
  • source (Address) — The address to query.
  • nonce (u64) — The nonce to check.
Source

pub fn try_query_auth_nonce_used( &self, source: &Address, nonce: &u64, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if a specific auth nonce has already been consumed for source.

§Arguments
  • source (Address) — The address to query.
  • nonce (u64) — The nonce to check.
Source

pub fn query_accrued_fees(&self, asset: &Address) -> i128

Returns the accrued (pending, not yet withdrawn) fee balance for asset.

Accrued fees accumulate on every fund_c_address call and are decremented when withdraw_fees is called. This value is always ≤ query_fee_balance (the contract’s actual token balance).

§Arguments
  • asset (Address) — The token to query.
§Errors
Source

pub fn try_query_accrued_fees( &self, asset: &Address, ) -> Result<Result<i128, <i128 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns the accrued (pending, not yet withdrawn) fee balance for asset.

Accrued fees accumulate on every fund_c_address call and are decremented when withdraw_fees is called. This value is always ≤ query_fee_balance (the contract’s actual token balance).

§Arguments
  • asset (Address) — The token to query.
§Errors
Source

pub fn commit_fund( &self, source: &Address, target: &Address, asset: &Address, amount_hash: &BytesN<32>, deadline: &u64, ) -> u64

Stores a blinded funding commitment without revealing the amount.

The caller commits to a specific (source, target, asset, amount) by providing amount_hash = sha256(amount_be16 || nonce_be8). The actual amount stays hidden until reveal_fund is called, preventing front-runners from observing the value before the commitment is settled.

§Arguments
  • source (Address) — The account that will supply the tokens.
  • target (Address) — The C-address that will receive the net amount.
  • asset (Address) — Whitelisted token contract address.
  • amount_hash (BytesN<32>) — sha256(amount_be16 || nonce_be8).
  • deadline (u64) — Unix timestamp; reveal_fund must be called before this time.
§Authorization

Requires source.require_auth().

§Returns

A numeric commitment ID used to reference this entry in reveal_fund and query_commitment.

§Errors
§Events
  • ("CommitFund", source, target) — data: (id, amount_hash, asset, deadline)
Source

pub fn try_commit_fund( &self, source: &Address, target: &Address, asset: &Address, amount_hash: &BytesN<32>, deadline: &u64, ) -> Result<Result<u64, <u64 as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Stores a blinded funding commitment without revealing the amount.

The caller commits to a specific (source, target, asset, amount) by providing amount_hash = sha256(amount_be16 || nonce_be8). The actual amount stays hidden until reveal_fund is called, preventing front-runners from observing the value before the commitment is settled.

§Arguments
  • source (Address) — The account that will supply the tokens.
  • target (Address) — The C-address that will receive the net amount.
  • asset (Address) — Whitelisted token contract address.
  • amount_hash (BytesN<32>) — sha256(amount_be16 || nonce_be8).
  • deadline (u64) — Unix timestamp; reveal_fund must be called before this time.
§Authorization

Requires source.require_auth().

§Returns

A numeric commitment ID used to reference this entry in reveal_fund and query_commitment.

§Errors
§Events
  • ("CommitFund", source, target) — data: (id, amount_hash, asset, deadline)
Source

pub fn reveal_fund( &self, commitment_id: &u64, source: &Address, target: &Address, asset: &Address, amount: &i128, nonce: &u64, )

Executes a previously committed fund transfer after the minimum delay.

Verifies sha256(amount_be16 || nonce_be8) == stored_amount_hash before transferring tokens, ensuring the caller cannot substitute a different amount from the one committed.

§Arguments
  • commitment_id (u64) — ID returned by commit_fund.
  • source (Address) — Must match the committed source.
  • target (Address) — Must match the committed target.
  • asset (Address) — Must match the committed asset.
  • amount (i128) — Actual gross amount; must satisfy the hash.
  • nonce (u64) — Blinding nonce used when computing amount_hash.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CommitRevealFunded", asset, source, target) — data: (commitment_id, amount, fee)
Source

pub fn try_reveal_fund( &self, commitment_id: &u64, source: &Address, target: &Address, asset: &Address, amount: &i128, nonce: &u64, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Executes a previously committed fund transfer after the minimum delay.

Verifies sha256(amount_be16 || nonce_be8) == stored_amount_hash before transferring tokens, ensuring the caller cannot substitute a different amount from the one committed.

§Arguments
  • commitment_id (u64) — ID returned by commit_fund.
  • source (Address) — Must match the committed source.
  • target (Address) — Must match the committed target.
  • asset (Address) — Must match the committed asset.
  • amount (i128) — Actual gross amount; must satisfy the hash.
  • nonce (u64) — Blinding nonce used when computing amount_hash.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("CommitRevealFunded", asset, source, target) — data: (commitment_id, amount, fee)
Source

pub fn query_commitment(&self, id: &u64) -> CommitmentEntry

Returns a commitment entry by ID.

§Errors
Source

pub fn try_query_commitment( &self, id: &u64, ) -> Result<Result<CommitmentEntry, <CommitmentEntry as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Returns a commitment entry by ID.

§Errors
Source

pub fn fund_c_address_with_swap( &self, source: &Address, target: &Address, source_asset: &Address, target_asset: &Address, source_amount: &i128, min_target_amount: &i128, swap_route: &Vec<Address>, )

Fund a C-address by swapping source_asset into target_asset first.

Flow:

  1. Pull source_amount of source_asset from source into the contract.
  2. Invoke the single whitelisted pool in swap_route using the standard two-token swap(min_amount_out, to) interface.
  3. Verify the final target_asset balance received ≥ min_target_amount.
  4. Deduct the fee (in target_asset) and transfer the net amount to target.
§Arguments
  • source — Account providing source_asset. Must authorise.
  • target — Destination C-address to receive target_asset.
  • source_asset — Token contract the source holds (e.g. USDC).
  • target_asset — Token contract the target should receive (e.g. XLM).
  • source_amount — Gross amount of source_asset to pull from source.
  • min_target_amount — Slippage guard: revert if the swap yields less.
  • swap_route — Must contain exactly one DEX pool contract address, and that address must be on the swap-pool whitelist (see add_swap_pool). The pool must implement: swap(min_amount_out: i128, to: Address) -> i128.
§Authorization

Requires source.require_auth().

§Errors
§Security Considerations

swap_route addresses are invoked with env.invoke_contract after the contract has already transferred tokens to them. Without a whitelist, a malicious or unvetted pool could keep the transferred tokens and return a fabricated amount_out, effectively stealing from the source. Every address in swap_route is therefore required to be present in the admin-managed pool whitelist (add_swap_pool / remove_swap_pool), which mirrors the existing asset whitelist pattern. Only the admin should whitelist pools, and only after auditing their swap implementation and token-return behavior.

Multi-hop routes are intentionally out of scope: the contract cannot generally know which token an intermediate pool actually returns, and assuming it equals target_asset mid-route can cause the contract to transfer the wrong token into the next pool. swap_route is therefore restricted to exactly one hop; longer routes return BridgeError::MultiHopNotSupported rather than silently miscomputing the swap.

Source

pub fn try_fund_c_address_with_swap( &self, source: &Address, target: &Address, source_asset: &Address, target_asset: &Address, source_amount: &i128, min_target_amount: &i128, swap_route: &Vec<Address>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Fund a C-address by swapping source_asset into target_asset first.

Flow:

  1. Pull source_amount of source_asset from source into the contract.
  2. Invoke the single whitelisted pool in swap_route using the standard two-token swap(min_amount_out, to) interface.
  3. Verify the final target_asset balance received ≥ min_target_amount.
  4. Deduct the fee (in target_asset) and transfer the net amount to target.
§Arguments
  • source — Account providing source_asset. Must authorise.
  • target — Destination C-address to receive target_asset.
  • source_asset — Token contract the source holds (e.g. USDC).
  • target_asset — Token contract the target should receive (e.g. XLM).
  • source_amount — Gross amount of source_asset to pull from source.
  • min_target_amount — Slippage guard: revert if the swap yields less.
  • swap_route — Must contain exactly one DEX pool contract address, and that address must be on the swap-pool whitelist (see add_swap_pool). The pool must implement: swap(min_amount_out: i128, to: Address) -> i128.
§Authorization

Requires source.require_auth().

§Errors
§Security Considerations

swap_route addresses are invoked with env.invoke_contract after the contract has already transferred tokens to them. Without a whitelist, a malicious or unvetted pool could keep the transferred tokens and return a fabricated amount_out, effectively stealing from the source. Every address in swap_route is therefore required to be present in the admin-managed pool whitelist (add_swap_pool / remove_swap_pool), which mirrors the existing asset whitelist pattern. Only the admin should whitelist pools, and only after auditing their swap implementation and token-return behavior.

Multi-hop routes are intentionally out of scope: the contract cannot generally know which token an intermediate pool actually returns, and assuming it equals target_asset mid-route can cause the contract to transfer the wrong token into the next pool. swap_route is therefore restricted to exactly one hop; longer routes return BridgeError::MultiHopNotSupported rather than silently miscomputing the swap.

Source

pub fn register_meta_signer(&self, source: &Address, pubkey: &BytesN<32>)

Binds an Ed25519 public key to source for use with execute_meta_fund.

execute_meta_fund authenticates purely via an Ed25519 signature check — it never calls require_auth. Without this registry, verifying that some keypair signed the payload proves nothing about whose funds are being moved: any keypair holder could submit a validly-signed meta-tx naming an arbitrary params.source. Calling this once (authorised by source itself) establishes the binding that execute_meta_fund then enforces on every subsequent call.

§Arguments
  • source (Address) — The account this pubkey is allowed to sign for.
  • pubkey (BytesN<32>) — The Ed25519 public key to bind to source.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("MetaSignerRegistered", source) — data: (pubkey,)
Source

pub fn try_register_meta_signer( &self, source: &Address, pubkey: &BytesN<32>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Binds an Ed25519 public key to source for use with execute_meta_fund.

execute_meta_fund authenticates purely via an Ed25519 signature check — it never calls require_auth. Without this registry, verifying that some keypair signed the payload proves nothing about whose funds are being moved: any keypair holder could submit a validly-signed meta-tx naming an arbitrary params.source. Calling this once (authorised by source itself) establishes the binding that execute_meta_fund then enforces on every subsequent call.

§Arguments
  • source (Address) — The account this pubkey is allowed to sign for.
  • pubkey (BytesN<32>) — The Ed25519 public key to bind to source.
§Authorization

Requires source.require_auth().

§Errors
§Events
  • ("MetaSignerRegistered", source) — data: (pubkey,)
Source

pub fn query_meta_signer(&self, source: &Address) -> Option<BytesN<32>>

Returns the Ed25519 public key currently bound to source via register_meta_signer, or None if no key has been registered.

§Arguments
  • source (Address) — The address to query.
Source

pub fn try_query_meta_signer( &self, source: &Address, ) -> Result<Result<Option<BytesN<32>>, <Option<BytesN<32>> as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns the Ed25519 public key currently bound to source via register_meta_signer, or None if no key has been registered.

§Arguments
  • source (Address) — The address to query.
Source

pub fn execute_meta_fund( &self, params: &MetaFundParams, pubkey: &BytesN<32>, signature: &BytesN<64>, )

Execute a fund_c_address on behalf of a user who signed the parameters off-chain.

Pattern (EIP-712-style adapted for Stellar / Soroban):

  1. The user constructs a MetaFundParams struct, serialises it as:
    payload = sha256(
    "meta_fund"           (8 bytes, ASCII)
    || source_strkey      (sha256 of strkey bytes, 32 bytes)
    || target_strkey      (sha256 of strkey bytes, 32 bytes)
    || asset_strkey       (sha256 of strkey bytes, 32 bytes)
    || amount_be16        (i128 big-endian, 16 bytes)
    || nonce_be8          (u64 big-endian,  8 bytes)
    || deadline_be8       (u64 big-endian,  8 bytes)
)
  2. The user signs payload with their Ed25519 key and gives (signature, pubkey, params) to a relayer.
  3. The relayer calls execute_meta_fund — it verifies the signature, checks the deadline and nonce, then performs the same token-transfer flow as fund_c_address.

This enables gas abstraction: the user never needs XLM for fees; the relayer covers the Stellar transaction fee.

§Arguments
  • params — Funding parameters signed by the user.
  • pubkey — The user’s Ed25519 public key (BytesN<32>). Must already be bound to params.source via register_meta_signer.
  • signature — Ed25519 signature over the canonical payload hash.
§Authorization

No require_auth() — authentication is entirely via Ed25519 signature. The relayer submits this transaction; the user’s identity is proven by pubkey and signature.

§Errors
§Events
  • ("MetaFundExecuted", asset, source, target) — data: (amount, fee, nonce)
Source

pub fn try_execute_meta_fund( &self, params: &MetaFundParams, pubkey: &BytesN<32>, signature: &BytesN<64>, ) -> Result<Result<(), <() as TryFromVal<Env, Val>>::Error>, Result<BridgeError, InvokeError>>

Execute a fund_c_address on behalf of a user who signed the parameters off-chain.

Pattern (EIP-712-style adapted for Stellar / Soroban):

  1. The user constructs a MetaFundParams struct, serialises it as:
    payload = sha256(
    "meta_fund"           (8 bytes, ASCII)
    || source_strkey      (sha256 of strkey bytes, 32 bytes)
    || target_strkey      (sha256 of strkey bytes, 32 bytes)
    || asset_strkey       (sha256 of strkey bytes, 32 bytes)
    || amount_be16        (i128 big-endian, 16 bytes)
    || nonce_be8          (u64 big-endian,  8 bytes)
    || deadline_be8       (u64 big-endian,  8 bytes)
)
  2. The user signs payload with their Ed25519 key and gives (signature, pubkey, params) to a relayer.
  3. The relayer calls execute_meta_fund — it verifies the signature, checks the deadline and nonce, then performs the same token-transfer flow as fund_c_address.

This enables gas abstraction: the user never needs XLM for fees; the relayer covers the Stellar transaction fee.

§Arguments
  • params — Funding parameters signed by the user.
  • pubkey — The user’s Ed25519 public key (BytesN<32>). Must already be bound to params.source via register_meta_signer.
  • signature — Ed25519 signature over the canonical payload hash.
§Authorization

No require_auth() — authentication is entirely via Ed25519 signature. The relayer submits this transaction; the user’s identity is proven by pubkey and signature.

§Errors
§Events
  • ("MetaFundExecuted", asset, source, target) — data: (amount, fee, nonce)
Source

pub fn query_meta_tx_nonce_used(&self, source: &Address, nonce: &u64) -> bool

Returns true if the given meta-transaction nonce has already been used for source.

Call this before constructing a MetaFundParams to get the next safe nonce, or to verify a pending meta-tx has not been replayed.

§Arguments
  • source — The user’s Stellar address.
  • nonce — The nonce to check.
Source

pub fn try_query_meta_tx_nonce_used( &self, source: &Address, nonce: &u64, ) -> Result<Result<bool, <bool as TryFromVal<Env, Val>>::Error>, Result<Error, InvokeError>>

Returns true if the given meta-transaction nonce has already been used for source.

Call this before constructing a MetaFundParams to get the next safe nonce, or to verify a pending meta-tx has not been replayed.

§Arguments
  • source — The user’s Stellar address.
  • nonce — The nonce to check.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T, C> Compare<&T> for C
where C: Compare<T>,

§

type Error = <C as Compare<T>>::Error

§

fn compare(&self, a: &&T, b: &&T) -> Result<Ordering, <C as Compare<&T>>::Error>

§

impl<T, U, E, C> Compare<(T, U)> for C
where C: Compare<T, Error = E, Error = E> + Compare<U>,

§

type Error = E

§

fn compare( &self, a: &(T, U), b: &(T, U), ) -> Result<Ordering, <C as Compare<(T, U)>>::Error>

§

impl<T, U, V, E, C> Compare<(T, U, V)> for C
where C: Compare<T, Error = E, Error = E, Error = E> + Compare<U> + Compare<V>,

§

type Error = E

§

fn compare( &self, a: &(T, U, V), b: &(T, U, V), ) -> Result<Ordering, <C as Compare<(T, U, V)>>::Error>

§

impl<T, U, V, W, E, C> Compare<(T, U, V, W)> for C
where C: Compare<T, Error = E, Error = E, Error = E, Error = E> + Compare<U> + Compare<V> + Compare<W>,

§

type Error = E

§

fn compare( &self, a: &(T, U, V, W), b: &(T, U, V, W), ) -> Result<Ordering, <C as Compare<(T, U, V, W)>>::Error>

§

impl<T, U, V, W, X, E, C> Compare<(T, U, V, W, X)> for C
where C: Compare<T, Error = E, Error = E, Error = E, Error = E, Error = E> + Compare<U> + Compare<V> + Compare<W> + Compare<X>,

§

type Error = E

§

fn compare( &self, a: &(T, U, V, W, X), b: &(T, U, V, W, X), ) -> Result<Ordering, <C as Compare<(T, U, V, W, X)>>::Error>

§

impl<T, C> Compare<Box<T>> for C
where C: Compare<T>,

§

type Error = <C as Compare<T>>::Error

§

fn compare( &self, a: &Box<T>, b: &Box<T>, ) -> Result<Ordering, <C as Compare<Box<T>>>::Error>

§

impl<T, C> Compare<Option<T>> for C
where C: Compare<T>,

§

type Error = <C as Compare<T>>::Error

§

fn compare( &self, a: &Option<T>, b: &Option<T>, ) -> Result<Ordering, <C as Compare<Option<T>>>::Error>

§

impl<T, C> Compare<Rc<T>> for C
where C: Compare<T>,

§

type Error = <C as Compare<T>>::Error

§

fn compare( &self, a: &Rc<T>, b: &Rc<T>, ) -> Result<Ordering, <C as Compare<Rc<T>>>::Error>

§

impl<T, C> Compare<Vec<T>> for C
where C: Compare<T>,

§

type Error = <C as Compare<T>>::Error

§

fn compare( &self, a: &Vec<T>, b: &Vec<T>, ) -> Result<Ordering, <C as Compare<Vec<T>>>::Error>

§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<E, T, U> IntoVal<E, T> for U
where E: Env, T: FromVal<E, U>,

§

fn into_val(&self, e: &E) -> T

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<E, T, U> TryIntoVal<E, T> for U
where E: Env, T: TryFromVal<E, U>,

§

type Error = <T as TryFromVal<E, U>>::Error

§

fn try_into_val(&self, env: &E) -> Result<T, <U as TryIntoVal<E, T>>::Error>

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,