> For the complete documentation index, see [llms.txt](https://wally-3.gitbook.io/wally-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wally-3.gitbook.io/wally-docs/technical/blockchain.md).

# Blockchain & Escrow

> The heart of Wally: transparency and control via Stellar blockchain and TrustlessWork smart contracts.

***

## Stellar Integration

Wally leverages Stellar's speed and low fees for all on-chain operations:

* **Payments**: Direct USDC transfers for QuickSend
* **Trustlines**: USDC asset trust establishment for new wallets
* **Account Creation**: Automated wallet creation on registration
* **Soroban**: Smart contract execution for escrows and DeFi operations

### Network Configuration

| Environment | Horizon                       | Soroban RPC                       |
| ----------- | ----------------------------- | --------------------------------- |
| Testnet     | `horizon-testnet.stellar.org` | `soroban-testnet.stellar.org`     |
| Mainnet     | `horizon.stellar.org`         | `soroban-rpc.mainnet.stellar.org` |

***

## TrustlessWork Integration

Wally integrates with **TrustlessWork** to provide non-custodial smart contract escrows on Soroban.

### Escrow Flow

```
Sender → [Create Escrow] → Smart Contract (Soroban)
                                  │
                        [Fund with USDC]
                                  │
                        [Provider completes service]
                                  │
                        [Release Signer approves]
                                  │
                        Provider ← [Receives USDC]
```

### Escrow Roles

| Role             | Function                      | Who in Wally      |
| ---------------- | ----------------------------- | ----------------- |
| Service Provider | Provides the service          | Verified provider |
| Approver         | Approves the release          | Sender (default)  |
| Release Signer   | Signs the release transaction | Sender            |
| Receiver         | Receives the funds            | Verified provider |
| Dispute Resolver | Resolves disputes             | Wally (mediator)  |
| Platform Address | Collects platform fee         | Wally             |

### Status Mapping

| Status                   | Description                                       |
| ------------------------ | ------------------------------------------------- |
| `PENDING`                | Transaction initiated but not yet on-chain        |
| `ESCROW_FUNDED`          | Assets locked in the TrustlessWork smart contract |
| `RELEASE_REQUESTED`      | Provider has requested release of funds           |
| `RELEASED` / `COMPLETED` | Funds successfully claimed by the provider        |
| `FAILED`                 | Transaction could not be processed on-chain       |

***

## Blend Capital Integration

**Blend Capital** is a lending protocol on Stellar/Soroban. Wally integrates the USDC pool to generate yield in savings vaults.

### Deposit Flow

```
User → [PIN] → Decrypt secret → Build Supply XDR
    → [Sign] → Submit to Soroban RPC → Blend Pool
    → [Record] → Update SavingsVault in DB
```

### Withdrawal Flow

```
User → [PIN] → Decrypt secret → Build Withdraw XDR
    → [Sign] → Submit to Soroban RPC → USDC returns to wallet
    → [Record] → Update SavingsVault in DB
```

### SDK Details

* Package: `@blend-capital/blend-sdk` v3.2.2
* `PoolContractV2.submit()` → returns base64 `xdr.Operation`
* `PoolV2.load()` → pool state (reserves, APY)
* Amounts scaled by 1e7 (Stellar 7-decimal precision)

***

## Non-Custodial Wallet Security

### Encryption

* **AES-256-GCM**: Authenticated encryption for secret keys
* **PBKDF2**: Key derivation from user PIN (100,000 iterations, SHA-256)
* **Salt + IV**: Unique per vault, stored in database
* **Web Crypto API**: All cryptography runs client-side in the browser

### Transaction Signing

1. User enters PIN
2. PBKDF2 derives encryption key from PIN + salt
3. AES-256-GCM decrypts the secret key
4. Transaction XDR is signed with the secret key
5. Signed transaction is broadcast to Stellar/Soroban
6. Secret key is zeroed from memory

### Key Principle

> The server never sees the user's secret key in plaintext. Wally cannot move user funds.

***

## On-Chain Verification

Every escrow and transaction is verifiable on the Stellar blockchain:

* **Stellar Expert**: Direct links to every transaction and escrow address
* **Soroban Explorer**: Smart contract state verification
* **Audit Trail**: Complete on-chain history of all operations
