> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usmewe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Timelock

> Withdrawal delays that protect against coercion

# Timelock System

The timelock creates a mandatory waiting period between initiating and completing a withdrawal.

## How It Works

<Steps>
  <Step title="Initiate Withdrawal">
    User requests withdrawal from Social Vault
  </Step>

  <Step title="Timelock Starts">
    Request enters pending state with countdown
  </Step>

  <Step title="Guardian Notification">
    All 5 Guardians receive push notification
  </Step>

  <Step title="Approval Period">
    3/5 Guardians must approve before timelock expires
  </Step>

  <Step title="Release">
    After timelock + approvals, funds are released
  </Step>
</Steps>

## Timelock Durations

| Withdrawal Amount | Timelock Period |
| ----------------- | --------------- |
| \< \$100          | 24 hours        |
| $100 - $500       | 36 hours        |
| $500 - $1,000     | 48 hours        |
| $1,000 - $5,000   | 60 hours        |
| > \$5,000         | 72 hours        |

## Cancellation

Withdrawals can be cancelled during the timelock:

* **By user**: Cancel anytime before release
* **By Guardian**: Any Guardian can cancel
* **Automatic**: If 2+ Guardians flag as suspicious

```typescript theme={null}
// Cancellation scenarios
const withdrawal = {
  amount: 500,
  timelock: 48, // hours
  status: 'PENDING',
  approvals: 1,
  flags: 0
};

// User cancels
withdrawal.status = 'CANCELLED_BY_USER';

// Guardian cancels
withdrawal.status = 'CANCELLED_BY_GUARDIAN';

// Automatic cancellation (2+ flags)
if (withdrawal.flags >= 2) {
  withdrawal.status = 'CANCELLED_SUSPICIOUS';
}
```

## Emergency Bypass

<Warning>
  There is intentionally **NO** emergency bypass. This is by design to prevent coerced "emergency" transfers.
</Warning>

If you need immediate access to funds:

1. Keep everyday spending in your regular wallet
2. Only store long-term holdings in Social Vault
3. Plan withdrawals in advance

## Smart Contract Implementation

```solidity theme={null}
// SocialVault.sol (simplified)
struct Withdrawal {
    address recipient;
    uint256 amount;
    uint256 initiatedAt;
    uint256 timelockEnd;
    uint8 approvals;
    bool executed;
}

function initiateWithdrawal(uint256 amount) external {
    uint256 timelock = calculateTimelock(amount);

    withdrawals[withdrawalCount++] = Withdrawal({
        recipient: msg.sender,
        amount: amount,
        initiatedAt: block.timestamp,
        timelockEnd: block.timestamp + timelock,
        approvals: 0,
        executed: false
    });

    emit WithdrawalInitiated(msg.sender, amount, timelock);
}

function calculateTimelock(uint256 amount) internal pure returns (uint256) {
    if (amount < 100e6) return 24 hours;
    if (amount < 1000e6) return 48 hours;
    return 72 hours;
}
```

<Card title="View Contract" icon="file-contract" href="/smart-contracts/social-vault">
  Full Social Vault contract documentation
</Card>