> For the complete documentation index, see [llms.txt](https://gothamcash.gitbook.io/bindowscash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gothamcash.gitbook.io/bindowscash/protocol/contracts-explained.md).

# Contracts explained

BindowsCash is powered by a minimal and transparent smart contract, divided into several sub-contracts called pools. Each pool corresponds to a specific denomination, and is deployed separately for each token/denomination combination, keeping logic isolated, auditable and secure.

This document breaks down the contract's logic, variables, and security design. Below is a breakdown of how the `BindowsMixer` contract works (with the 0.1 BNB pool for example) and what each part is responsible for.

***

### 📌 **Constants and Globals**

```solidity
uint256 public constant MIX_AMOUNT = 0.1 ether;
uint256 public constant FEE_BPS = 100; // 1% fee
address public constant DEV_ADDRESS = 0xD3d47348442cD6e1b3ca1481F26743A93c5ca537;
address public constant STAKING_ADDRESS = 0x0000000000000000000000000000000000000000;
```

* **MIX\_AMOUNT**: Fixed deposit amount for this pool.
* **FEE\_BPS**: Fee in **basis points** (100 = 1%). Applies only once during the mixing process.
* **DEV\_ADDRESS**: Address that receives fees (relayer costs and dev funding).
* **STAKING\_ADDRESS**: Address of the staking pool contract.

***

### 🧾 State Variables

```solidity
mapping(bytes32 => bool) public commitments;
mapping(bytes32 => bool) public nullifiers;
DepositInfo[] public deposits;

struct DepositInfo {
  bytes32 commitment;
  uint256 timestamp;
}
```

* **commitments**: Tracks all deposited commitment hashes (to prevent reuse).
* **nullifiers**: Prevents duplicate withdrawals via hashed commitments.
* **deposits**: Stores all deposits with timestamps to count them in the dApp stats.

***

### 📥 Deposit function

```solidity
function deposit(bytes32 commitment) external payable
```

* Verifies the **exact deposit amount** (`0.1 BNB`).
* Ensures the **commitment** hasn't already been used or withdrawn.
* Stores the commitment in state and logs the timestamp.
* Sends the **1% fee** split to `DEV_ADDRESS` (50%, can fund relayers) and `STAKING_ADDRESS`.
* Emits a `Deposited` event.

💡 *The commitment is a hash of a secret (nullifier + secret), generated off-chain.*

#### 💡 Off-chain logic:

* The `commitment` is derived from a random `secret` (nullifier + randomness).
* What happens on the front-end:

```
const secret = randomBytes(32);
const commitment = sha256(keccak256(secret));
```

***

### 💸 Withdraw function

```solidity
function withdraw(bytes32 secret, bytes calldata signature) external
```

#### Flow:

1. Recomputes:

   ```
   keccak = keccak256(secret);
   commitment = sha256(keccak);
   ```

2. Validates:

   * The commitment exists.
   * It has not already been used.
   * The signature is valid for the given commitment.

3. Extracts signer from:

   ```
   recoverSigner(commitment, signature)
   ```

4. Sends `0.099 BNB` (after 1% fee) to the **signer** (in our example using the `0.1 BNB` pool).

5. Emits a `Withdrawal` event.

#### 🛡️ Why the signature?

* Prevents **front-running** (i.e., someone else using the same secret before you).
* Ensures only the **true owner** of the note (with secret + signature) can withdraw.

***

### 🧾 Signature Handling

```solidity
function recoverSigner(bytes32 commitment, bytes memory signature) public pure returns (address)
```

The contract uses **ECDSA signature recovery**:

```
address = ecrecover(ethSignedMessageHash(commitment), v, r, s);
```

Signing is done off-chain, e.g. via MetaMask:

```
const commitment = ethers.sha256(keccak256(secret));
const signature = await signer.signMessage(ethers.getBytes(commitment));
```

***

### 📊 View Functions

```solidity
function getDepositsCount() external view returns (uint256)
function getDeposit(uint256 index) external view returns (bytes32, uint256)
```

* Lets users/explorers read all deposits (e.g., for relayers or stats).
* Enables **future reclaimability** or UI display.

***

### 📤 Fee Mechanism

* The contract takes a **1% fee** between deposit and withdrawal stages:
  * On **deposit**, 1% is taken, and divided in 2 parts:
    * 50% goes to to `DEV_ADDRESS`.
    * 50% goes to to `STAKING_ADDRESS`.
  * On **withdrawal**, the user receives 99% of the funds.
* This fee helps:
  * Cover relayer gas costs (gasless withdrawals).
  * Fund ongoing maintenance.
  * Keep the protocol decentralized.

***

### 📡 Events

```solidity
event Deposit(bytes32 indexed commitment, uint256 timestamp);
event Withdrawal(address indexed to, bytes32 indexed nullifier);
```

* Emitted on every successful deposit or withdrawal.
* Allows off-chain indexing, relayer monitoring, and analytics.

***

### ⛔ Safety limitation

* ⚠️ If you lose your secret or your signature is leaked, **your funds are unrecoverable**.

***

### 🧠 Privacy Architecture Summary

| Feature                | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| Client-side generation | Secrets and notes are generated in the browser — the contract sees only hashes. |
| Gasless withdrawals    | Signature-based withdrawals avoid linking your wallet to the on-chain tx.       |
| Stateless identity     | No account linkage, no KYC, no metadata stored.                                 |
| One-time notes         | Once a note is spent, it cannot be reused.                                      |

***

### Summary

These pools prioritizes **simplicity**, **auditability**, and **privacy-by-design**. All note logic (nullifier and secret generation) happens client-side, meaning **the smart contract itself never holds user metadata**.