User Interaction Scenarios

Instant Withdrawal Flow

Below are typical user flows. Each scenario assumes the user has a Web3 wallet connected and has retrieved a valid JWT via the SIWE login flow.

Scenario 1: Normal Flow and Successful Instant Withdrawal

1. Login via wallet (SIWE flow)

   1. UI calls POST /v1/auth/nonce with { address }.

   2. UI immediately calls GET /v1/auth/sign-in-message with the same address, domain, and URI; displays the returned message for signing.

   3. User signs; UI sends POST /v1/auth/login with { message, signature }.

   4. UI receives access_token and sets Authorization: Bearer <token> on subsequent requests.

2. Fetch Fee Options

   1. User enters their wallet account address and desired amount in UI.

   2. UI calls POST /v1/fee-options?account=<account>&amount=<amount>.

   3. Backend validates, computes instant and fallback options, and locks them for POLICY_VALID_TIME (e.g., 30 s).

   4. UI displays the returned array of one or more FeeOption items.

3. Bridge Funds

   1. UI invokes on-chain call symmio_contract.bridge(amount) (or _call(deallocate, bridge) if bridging from a multi-account).

   2. Once on-chain transaction is mined, UI displays the bridgeId and instructs user to select a fee policy.

4. Select Fee Policy

   1. UI calls POST /v1/bridges/{account}/{start}/{size} to fetch the user’s bridges in no_policy state, e.g.:

      {
        "bridge_state": "pending",
        "bridge_type": "no_policy"
      }

   2. For each bridge:

      1. UI calls GET /v1/pending-fee-policy/{account} and displays locked fee policies.

      2. User chooses one of the displayed FeeOption.

      3. (Optional) To specify a different receiver:

         1. UI calls

            GET /v1/get-select-receiver-message?receiver=<newReceiver>&bridgeId=<bridgeId>

         2. UI has user sign the returned EIP-712 payload and includes:

            "receiver": {
              "address": "<newReceiver>",
              "signature": "<sig>"
            }

      4. UI calls POST /v1/select-fee-policy with:

         {
           "symmioBridgeId": <bridgeId>,
           "cooldown": <chosenCooldown>,
           "feeAmount": <chosenFee>,
           "receiver": { … }      // optional
         }

      5. Backend validates, records in DB, calls selectFeePolicyForBridge on-chain, and schedules withdrawal at execution_time = now + cooldown.

      6. Backend returns:

         {
           "bridge_id": <bridgeId>,
           "fee": <feeAmount>,
           "execution_time": <timestamp>
         }

5. Automated Withdrawal After cooldown seconds, the backend bot automatically calls processWithdrawal(bridgeId) on-chain.

---

Scenario 2: Fee Options Expire and Retry

1. Login via wallet (as in Scenario 1).

2. Initial Fee Options UI calls POST /v1/fee-options but user waits beyond POLICY_VALID_TIME (e.g., 30 s).

3. Bridge funds and obtain bridgeId.

4. Lock expires (options TTL passed).

5. UI retrieves no-policy bridges via POST /v1/bridges/{account}/{start}/{size}.

6. Retry Fee Options UI calls POST /v1/fee-options?account=<account>&amount=<amount> again; backend regenerates options and locks for another 30 s.

7. Select & Withdraw User picks a new option, signs payload, calls POST /v1/select-fee-policy, and flow continues as in Scenario 1.

---

Scenario 3: No Policy Selected (Withdrawal Pending)

1. Login & Bridge Funds

• The user logs in and initiates a bridge transaction through the frontend.

• The backend captures the bridge event and records it with bridge_type = no_policy and status = RECEIVED.

• The funds are deducted from the user’s Symmio balance and reserved in the bridge contract — no payout occurs yet.

2. User Does Not Select a Policy

• If the user leaves or closes the UI before selecting a fee policy:

  • No withdrawal is scheduled.

  • The bridge transaction remains pending indefinitely.

  • The user’s reserved funds cannot be used elsewhere, but can still be withdrawn later once a policy is chosen.

3. User Returns Later to Complete the Withdrawal

• When the user logs back in, the UI must:

• Retrieve all pending bridges with POST /v1/bridges/{account}/{start}/{size} and look for entries where bridge_type = no_policy.

• For each pending bridge, request a new set of fee options using POST /v1/fee-options?account=<account>&amount=<amount>.

Previously shown fee options may have expired past their POLICY_VALID_TIME,in which case a new set of fee options must be fetched.

4. Selecting a Policy and Processing the Withdrawal

• Once the user selects a fee option:

  1. The frontend calls POST /v1/select-fee-policy with the chosen policy .

  2. The backend calls selectFeePolicyForBridge on-chain.

  3. After the configured cooldown period (usually 0), the backend or bot executes processWithdrawal(bridgeId) to finalize the payout to the user.

• The transaction is then marked as completed, and the user receives the bridged funds.

---

Scenario 4a: Bot Inactive, Then Reactivated

1. Bot Down During Bridge – User bridges on-chain while event poller is offline → no record created.

2. Bot Reactivation & Catch-Up – Bot scans missed events, creates BridgeTransactions with no_policy.

3. User Resumes Normal Flow – UI requests fee options and follows Scenario 1 steps to select and execute withdrawal.

---

Scenario 4b: Bot Inactive after Policy Selected, Manual Withdrawal

1. Follow Scenario 1 through fee-policy selection.

2. Bot goes down before scheduled withdrawal executes.

3. Manual Withdrawal

   1. UI displays “Withdraw After Cooldown” button next to bridges where execution_time has passed but state is still pending.

   2. When clicked, UI calls processWithdrawal(bridgeId) on-chain.

   3. Tokens arrive in user’s wallet.

---

Scenario 5: Reset Locked Fee Options

1. Login via wallet.

2. UI calls POST /v1/fee-options?account=<account>&amount=<amount>, receives options.

3. UI calls POST /v1/unlock/{account} to clear locks.

4. UI calls POST /v1/fee-options?account=<account>&amount=<amount> again to fetch fresh options.

---

4. Additional UI Actions and Buttons

1. Get Max Instant Value Button

   • Endpoint: GET /v1/max-instant-value/{account}

   • Purpose: Show the maximum amount the user can withdraw instantly; guide the user to not bridge more than this.

2. Refresh Fee Options Button

   • Combined Actions:

     1. POST /v1/unlock/{account}

     2. POST /v1/fee-options?account=<account>&amount=<amount>

   • Purpose: Clear existing lock and fetch fresh fee/cooldown options in one click.

3. Manual Process Withdrawal Button

   • Action: Calls the contract’s processWithdrawal(bridgeId) method directly.

   • Purpose: Allow users to trigger on-chain withdrawal if scheduled withdrawal failed or bot is down.

   • When to Show: After fetching user’s bridge list, display “Withdraw Now” next to any entry where execution_time has passed but state is still pending.

---

5. Error Codes

All endpoints return structured error codes via the shared ErrorInfoContainer:

Code	Identifier	Message
1	unhandled_error	Internal server error
2	could_not_get_excepted_response	Could not get expected response
3	model_validation_error	Model validation error
4	not_found_error	Not found
5	already_has_pending	Already has pending withdrawal options—try again in ? seconds
6	not_enough_balance	Not enough user balance
7	invalid_bridge_transaction	Invalid bridge transaction
8	invalid_bridge_policy_option	Invalid Bridge Policy Option—please check and select options again
9	already_has_withdrawal_option_or_executed	You already selected an option for this bridge or it has executed
10	low_amount_to_bridge	Requested amount for bridge is very low
11	unauthorized_access	Unauthorized
12	invalid_signature	Invalid Signature
13	signature_mismatch	Signature mismatch
14	expired_nonce	Nonce expired or not found
15	not_authenticated	Not authenticated
16	contract_validation_failed	Contract validation failed
17	rpc_connection_failed	RPC endpoint connection failed
18	nonce_mismatch	Nonce mismatch
19	user_creation_in_progress	User creation in progress for this address. Please retry in a moment.