wALN Bridge Contract (Solana)

Overview

The wALN Bridge is a Solana program that enables two-way token conversion between ALN on the Alien Network and wALN (wrapped ALN) on Solana. The bridge operates via a TEE Frame — an off-chain component running on the Alien Network side — and this on-chain contract, which holds exclusive mint/burn authority over the wALN token (Token-2022). When a user locks ALN on the Alien Network, the frame calls the contract to mint an equivalent amount of wALN to the user's Solana wallet. When a user wants to bridge back, they submit a bridge order on Solana that locks their wALN in a vault; the frame then picks up the order, releases ALN on the Alien side, and calls the contract to burn the locked wALN.

The contract exists as a safety layer: it enforces configurable rate limits on minting, a 2-of-3 admin multisig for privileged operations (unpausing, config changes, program upgrades), single-admin emergency pause capability, minimum bridge amount enforcement, and automatic supply integrity checks that pause minting if on-chain supply diverges from internal counters. This ensures the bridge remains protected even if the Alien Network or the frame is compromised.

Architecture

Token

• Standard: Token-2022 (SPL Token Extensions) with transfer hook support
• Mint/Burn authority: Contract PDA (mint_authority seed) — no external authority
• Program ID: 9KpiMGcHaRMhCZFHBKxEor6KY8b7P2bwdHgbjfy2Xcsh

Admin Model

• 3 admins, set at initialization
• Quorum: 2 of 3 for privileged operations (unpause, config changes, program upgrade)
• Pause: any single admin can pause mint or burn immediately (safety measure)
• Config changes use a hash-based voting mechanism — the first admin proposes parameters, subsequent admins must submit identical parameters to confirm

Frame Account

A dedicated Solana keypair (bridge_authority) registered via the admin multisig. Only this account can call mint_waln, execute_order, and cancel_order.

Instructions

Instruction	Caller	Description
initialize	Deployer	Sets up config, admins, mint, frame account; transfers mint authority to PDA
mint_waln	Frame	Mints wALN to a recipient; enforces rate limits and supply integrity check
bridge	Any user	Locks wALN in vault, creates an order PDA for bridge-back to Alien Network
execute_order	Frame	Burns locked wALN from vault, closes order PDA (rent refunded to sender)
cancel_order	Frame	Returns locked wALN to sender, closes order PDA
disable	Any admin	Pauses mint or burn (single signature)
vote_enable	Admin	Votes to unpause mint or burn (requires 2/3 threshold)
vote_update_config	Admin	Votes on config changes (rate limits, admins, frame account, thresholds, min bridge amount)
revoke_config_vote	Admin	Revokes a previously cast config vote

Bridging Flows

ALN → wALN (Mint)

1. User locks ALN on Alien Network
2. TEE Frame detects the lock event
3. Frame calls mint_waln(recipient, amount) on Solana
4. Contract checks: not paused, supply integrity, rate limits
5. wALN is minted to the recipient's token account

wALN → ALN (Burn)

1. User calls bridge(amount, alien_address) on Solana
2. Contract validates amount ≥ min_bridge_amount, transfers wALN to vault
3. Order PDA is created (seed: ["order", order_id_bytes])
4. Frame picks up the order, releases ALN on Alien Network
5. Frame calls execute_order(order_id) — burns locked wALN, closes order PDA
6. If the order cannot be fulfilled, frame calls cancel_order(order_id) — returns wALN to user

Rate Limiter

Both directions have a per-transaction cap (per_tx_cap_mint / per_tx_cap_burn) and a slot-based daily token bucket (mint_rate / burn_rate, each a RateLimit). A bucket refills linearly per slot (slot count is the canonical Solana time source; 216_000 slots ≈ 24h at 400ms slots).

Parameter	Description
per_tx_cap_mint / per_tx_cap_burn	Max wALN per single mint / burn (0 = instruction blocked)
mint_rate.limit / burn_rate.limit	Token-bucket capacity per window (must be > 0)
mint_rate.period_slots / burn_rate.period_slots	Refill window length, in slots
*.remaining	Tokens currently available
*.last_slot	Slot of the last refill/consume

Config Timelock

vote_update_config collects a 2-of-3 admin vote. Once quorum is reached, the change is either applied immediately or queued behind a timelock, depending on what it does:

• Applied immediately: lowering a cap (per_tx_cap_* down, mint_rate.limit / burn_rate.limit down, *_rate.period_slots up) and min_bridge_amount — tightening is a safety move.
• Queued for config_timelock_secs: raising a cap, shortening the rate window, rotating bridge_authority, replacing an admin, or changing enable_threshold / supply_check_enabled / config_timelock_secs itself.

A queued change is recorded as pending_config_eta (unix seconds). After it elapses, any admin calls execute_config (re-supplying the same params, matched by hash) to apply it; any single admin may cancel_config to veto it during the window. Only one change may be queued at a time. config_timelock_secs is operator-set (0 = no delay), capped at MAX_TIMELOCK_SECS (30 days); changing it waits the current timelock, so the delay can't be weakened faster than the active value allows.

Supply Integrity

The contract tracks total_minted_waln and total_burned internally. Before each mint or execute_order, it compares total_minted - total_burned against the on-chain token supply. A mismatch triggers automatic mint pause and emits a SupplyMismatchPaused event.

Pause Behavior

State	Mint	Burn (bridge)	Execute/Cancel orders
Mint paused	Rejected	Allowed	Execute requires burn not paused
Burn paused	Allowed	Rejected	Cancel allowed, Execute rejected
Both paused	Rejected	Rejected	Cancel allowed, Execute rejected

Events

Event	Emitted when
BridgeOrderCreated	New bridge-back order created
OrderExecuted	Order fulfilled and wALN burned
OrderCancelled	Order cancelled and wALN returned
MintPaused / MintUnpaused	Mint pause state changes
BurnPaused / BurnUnpaused	Burn pause state changes
SupplyMismatchPaused	Supply integrity check failed
BridgeAuthorityRotated	bridge_authority rotated (on apply)
ConfigQueued	A timelocked config change was queued
ConfigCancelled	A queued config change was vetoed

State Accounts

BridgeConfig (PDA: ["bridge_config"])

Singleton config holding admin list, pause states, rate limiter parameters, supply counters, voting state, and frame account reference.

BridgeOrder (PDA: ["order", order_id_bytes])

Per-order account storing: id, sender, amount, alien_address. Created by user (pays rent), closed on execute/cancel (rent refunded to sender).

Build & Test

anchor build
anchor test

Upgradeability

The program is upgradeable. Before production, upgrade authority must be transferred to the multisig PDA via solana program set-upgrade-authority. After transfer, only a 2/3 admin multisig vote can upgrade the program.