Create documentation for Sandbox Mocked Withdrawals

Author: JoelGama

_sandboxmockedwithdrawals.md

@@ -0,0 +1,135 @@
+# Sandbox Mocked Withdrawals
+
+## Overview
+
+**Sandbox mocked withdrawals** allow teams to simulate the withdrawal flow without actually sending testnet funds. Instead, the system mocks provider calls and responses, enabling safe and comprehensive testing across environments.
+
+> **Note:** This behavior is **enabled by default** but can be customized for partners who require on-chain testnet transactions.
+
+
+## Why Use Mocked Withdrawals?
+
+Acquiring testnet tokens can be cumbersome and time-consuming, especially when testing at scale. Mocked withdrawals solve this by:
+
+- Removing dependencies on testnet faucets
+- Reducing flakiness and wait times
+- Simplifying QA and development workflows
+
+With this setup, partners can validate flows confidently without real token movement or blockchain interaction.
+
+## Supported Networks
+
+Mocked withdrawals can be enabled or disabled across the following networks:
+
+```
+Algorand, Arbitrum, Avalanche, Base, BNB Smart Chain, Cardano, Casper, Celo,
+Constellation, Cosmos, Dogecoin, Flare, Hedera, Kaspa, Lukso, Mythos, Near,
+Optimism, Polkadot, Polygon, Solana, Songbird, Stacks, Starknet, Stellar,
+Tezos, Ton, Tron, Xinfin, XRP Ledger
+```
+
+## Mock Types
+
+| Type            | Behavior                                                                 |
+|-----------------|--------------------------------------------------------------------------|
+| `mock_enabled`  | Withdrawal is simulated. No funds are sent. Provider calls are mocked.   |
+| `mock_disabled` | Withdrawal proceeds normally using testnet funds.                        |
+
+## How It Works
+
+The system uses a configuration-based approach to determine when a withdrawal should be mocked.
+
+### Matching Criteria
+
+Mocking behavior can be triggered based on:
+
+- `userId`
+- `organizationId`
+- `currency`
+- `network`
+
+Each property acts as an individual match condition. They can also be combined for more complex rules.
+
+### Example Configuration
+
+```js
+mocked: {
+  withdrawal: {
+    default: "mock-enabled",
+    rules: [
+      {
+        context: {
+          currency: "BTC",
+          network: "bitcoin",
+          whitelistedOrganizations: ["org-id-123"],
+          whitelistedUsers: ["user-id-456"]
+        },
+        id: "rule-1-id",
+        mockType: "mock-disabled"
+      },
+      {
+        context: {
+          currency: "ETH",
+          whitelistedUsers: ["user-id-456"]
+        },
+        id: "rule-2-id",
+        mockType: "mock-disabled"
+      }
+    ]
+  }
+}
+```
+
+## Rule Priority
+
+When multiple rules apply, the system selects the one with the **highest match score**, calculated as:
+
+- Each matching field (user, org, network, currency) = 1 point
+- Highest total wins
+- Ties are resolved by the rule's position (first one wins)
+
+> **Example:** Rule 2 will disable mocks for `user-id-456` when withdrawing ETH.
+
+
+## Mock Service
+
+The `mock-service` determines whether a function should be mocked based on:
+
+- The current environment (mocks are **never** used in production)
+- The `mockType` value
+
+### Core API
+
+```ts
+static async mockIfRequired(mockType = MOCK_ENABLED, {
+  executionCallback,
+  mockedCallback
+}) {
+  if (config.get('env') !== 'production') {
+    if (mockType === MOCK_ENABLED) {
+      return mockedCallback();
+    }
+  }
+  return await executionCallback();
+}
+```
+
+> It also includes logic to resolve priority between rules.
+
+## Example: Mocked Nonce Call
+
+```ts
+const nonce = await MockService.mockIfRequired(mockType, {
+  executionCallback: async () =>
+    await this.addressSequenceHelper.getAddressSequence(originAddress),
+  mockedCallback: () => 0
+});
+```
+
+In this example, the nonce value is mocked when the rule applies, allowing the rest of the flow to continue without relying on the blockchain.
+
+## References
+
+- [Mock Types](#mock-types)
+- [How It Works](#how-it-works)
+- [Supported Networks](#supported-networks)