@towns-protocol/contracts 0.0.302

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 River Association
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Towns Contracts
+
+## Overview
+
+This project is a blockchain-based space/channel management system with role-based access control and entitlements. It implements a complex permission system using smart contracts that allows for cross-chain rule validation and user management.
+
+The system also supports cross-chain delegation between Ethereum L1 and Base L2, allowing users to stake tokens on L1 and have delegation benefits on L2. Node operators can receive delegations directly or via spaces, with rewards distributed based on stake amounts and time.
+
+### The system allows for:
+
+- Creation and management of spaces and channels
+- Role-based access control with granular permissions
+- Cross-chain entitlement validation
+- User membership management
+- Rule-based entitlements with logical operations
+- Staking and rewards distribution for DAO participants and node operators
+- Cross-chain delegation and governance mechanisms
+
+## Tech Stack
+
+- Solidity ^0.8.23
+- OpenZeppelin Contracts
+- Solady Contracts
+- Diamond Pattern (EIP-2535) for upgradeable contracts
+- Foundry for development and testing
+- TypeScript for contract type generation
+
+## Project Structure
+
+- `src/airdrop/` - Token distribution mechanisms (drops, points, streaks, rules)
+- `src/base/registry/` - Core registry, delegation, rewards, entitlement checking
+  - `/facets/distribution/` - Staking and rewards distribution for DAO participants and node operators
+  - `/facets/mainnet/` - Cross-chain delegation handling and message relaying
+  - `/facets/delegation/` - Space-to-operator delegation management
+  - `/facets/operator/` - Node operator registration and management
+- `src/spaces/` - Space management, entitlements, permissions, cross-chain rules
+- `src/factory/` - Factory contracts for space creation, deployment, wallet linking
+- `src/utils/` - Utility libraries (currency, math, reverts, patterns)
+- `src/diamond/` - Diamond pattern implementation, facets, upgradeability
+- `src/tokens/` - Token management, membership NFTs, locks, bridging, inflation
+- `scripts/diamonds` - Diamond deployment scripts
+
+### Key Contracts
+
+- `RuleEntitlement.sol` - Rule-based entitlements, cross-chain permission validation
+- `EntitlementsManager.sol` - Entitlement validation and access control
+- `Architect.sol` - Factory for space creation/initialization
+- `CreateSpace.sol` - Space instance creation/initialization
+- `Roles.sol` - Role-based permissions and hierarchies
+- `Towns.sol` - Main ERC20 token (inflation, governance)
+- `DropFacet.sol` - Token airdrops, claiming conditions
+- `TownsPoints.sol` - Points-based rewards, check-ins, streaks
+- `RewardsDistribution.sol` - Manages token staking, delegation proxies, and reward calculations
+- `MainnetDelegation.sol` - Handles cross-chain delegation via cross-domain messengers
+- `SpaceDelegationFacet.sol` - Manages delegation of spaces to node operators
+- `EntitlementChecker.sol` - Cross-chain entitlement validation
+- `DiamondCutFacet.sol` - Diamond upgradeability
+
+## Requirements
+
+Install [yarn](https://yarnpkg.com/getting-started/install) via corepack:
+
+```shell
+npm install -g corepack
+corepack enable
+```
+
+Install [Foundry](https://github.com/foundry-rs/foundry):
+
+```shell
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+```
+
+## Project Setup
+
+Clone the repo, then:
+
+```shell
+yarn
+```
+
+**To compile the smart contracts:**
+
+```shell
+forge build
+```
+
+**To run the solidity unit tests:**
+
+```shell
+forge test
+```
+
+You can add verbosity to the tests by adding `-vvvv` (1-4 levels) to the command.
+
+## Local Development
+
+**To start a local Ethereum blockchain:**
+
+```shell
+anvil
+```
+
+It will generate a set of 10 public/private keys with 10k ether each. Save one of these private keys for deployment.
+It starts listening on `http://127.0.0.1:8545`.
+If you want to interact with anvil via a front end, you will need to add the local network to Metamask with `ChainID=1337`.
+
+**To start a local base blockchain and river blockchain:**
+
+```shell
+./scripts/bc-all-start.sh
+```
+
+## Deployment
+
+### Local Deployment
+
+**To deploy our contracts to your local base and river instances:**
+
+1. Duplicate `.env.localhost` file in the [contracts](.) folder of the project and rename it to `.env` (this is excluded from git via .gitignore)
+2. Run `export RIVER_ENV="local_multi"` from your terminal
+3. Execute `./scripts/deploy-contracts.sh` to deploy the entire suite of contracts to your local base-anvil and river-anvil chains
+
+### Diamond Contract Deployment
+
+**To deploy a single diamond base contract to your local anvil instance:**
+
+From within the `contracts/` folder you can run:
+
+```shell
+make deploy-base-anvil contract=Deploy[Contract] type=diamonds
+```
+
+Replace `[Contract]` with the contract you want to deploy. You can see all the contracts available for deployment in the [diamonds deployments directory](./scripts/deployments/diamonds).
+
+### Facet Deployment
+
+The project supports two methods for deploying facets:
+
+1. **Using custom deployment scripts:**
+
+   ```shell
+   make deploy-base-anvil contract=Deploy[Facet] type=facets
+   ```
+
+   - Replace `[Facet]` with the name of your facet deployment script found in [./scripts/deployments/facets](./scripts/deployments/facets)
+   - This approach uses scripts that inherit from `Deployer` and implement `versionName()` and `__deploy()` functions
+
+2. **Using the standardized `DeployFacet` script:**
+
+   ```shell
+   make deploy-facet-local rpc=base_anvil contract=[FacetName]
+   ```
+
+   - Replace `[FacetName]` with the actual facet contract name (without "Deploy" prefix)
+   - This approach uses the common `DeployFacet.s.sol` script with the `CONTRACT_NAME` environment variable
+   - It leverages deterministic CREATE2 addresses and supports batch deployments
+   - For more details, see the [DeployFacet documentation](https://github.com/towns-protocol/diamond/blob/main/scripts/README.md)
+
+### Live Network Deployment
+
+**To deploy facets to a live network:**
+
+From within the `contracts/` folder you can run:
+
+```shell
+# For custom deployment scripts:
+make deploy-base-sepolia contract=Deploy[Contract] type=facets context=[context]
+
+# For standardized DeployFacet script:
+make deploy-facet rpc=base_sepolia contract=[FacetName] context=[context]
+```
+
+For example, to deploy the WalletLink facet to Base Sepolia with a deployment context of "gamma":
+
+```shell
+# Using custom deployment script:
+make deploy-base-sepolia contract=DeployWalletLink type=facets context=gamma
+
+# Using standardized DeployFacet script:
+make deploy-facet rpc=base_sepolia contract=WalletLink context=gamma
+```
+
+### Hardware Wallet Deployments
+
+For hardware wallet deployments, use the corresponding ledger commands:
+
+```shell
+# Using custom deployment script:
+make deploy-ledger-base-sepolia contract=DeployWalletLink type=facets context=gamma
+
+# Using standardized DeployFacet script:
+make deploy-facet-ledger rpc=base_sepolia contract=WalletLink context=gamma
+```
+
+You can see all the contracts available for deployment in the [deployments](./scripts/deployments) directory.
+
+## Contributing
+
+For detailed information on contributing to this project, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file. It includes:
+
+- Guidelines for opening issues and pull requests
+- Coding standards and best practices
+- Diamond Pattern implementation details
+- Facet development guidelines

package/docs/permitAndStake_integration_guide.md

@@ -0,0 +1,266 @@
+# PermitAndStake Integration Guide
+
+This guide explains how to integrate with the new `permitAndStake` function in the Towns Protocol RewardsDistribution contract, which uses Permit2 for gasless token approvals and enhanced smart contract wallet support.
+
+## Overview
+
+The `permitAndStake` function allows users to approve and stake tokens in a single transaction using Uniswap's Permit2 protocol. This provides several advantages over traditional EIP-2612 permits:
+
+- **Smart Contract Wallet Support**: Works with smart contracts via ERC-1271 signature verification
+- **Universal Token Approval**: Uses Permit2 as a universal approval router
+- **Enhanced Security**: Cryptographically binds signatures to specific spenders and amounts
+- **Gasless Approval**: No separate approval transaction required
+
+## Prerequisites
+
+Before using `permitAndStake`, ensure:
+
+1. **Towns Token Approval**: No pre-approval needed. The Towns token gives Permit2 infinite allowance by default, so users can directly call `permitAndStake` without any prior approval transactions.
+
+2. **Permit2 Deployment**: Permit2 is deployed at the deterministic address `0x000000000022D473030F116dDEE9F6B43aC78BA3` on all networks.
+
+## Function Signature
+
+```solidity
+function permitAndStake(
+  uint96 amount, // Amount of Towns tokens to stake
+  address delegatee, // Operator or space to delegate to
+  address beneficiary, // Address that receives staking rewards
+  uint256 nonce, // Unique nonce for replay protection
+  uint256 deadline, // Expiration timestamp for the permit
+  bytes calldata signature // Permit2 signature
+) external returns (uint256 depositId);
+```
+
+## Integration Guide
+
+### TypeScript/JavaScript Integration
+
+#### Dependencies
+
+```bash
+yarn add @uniswap/permit2-sdk viem
+```
+
+#### Complete Integration Example
+
+```typescript
+import {
+  PERMIT2_ADDRESS,
+  SignatureTransfer,
+  PermitTransferFrom,
+} from "@uniswap/permit2-sdk";
+import { createWalletClient, http, parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+// Contract addresses
+const REWARDS_DISTRIBUTION_ADDRESS = "0x..."; // Your deployed contract
+const TOWNS_TOKEN_ADDRESS = "0x..."; // Towns token address
+
+// Create wallet client
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+  account,
+  chain: base,
+  transport: http(),
+});
+
+async function permitAndStake({
+  amount, // Amount to stake (in token units, e.g., "100")
+  delegatee, // Operator or space address
+  beneficiary, // Beneficiary address
+}) {
+  // 1. Convert amount to proper units
+  const amountWei = parseUnits(amount, 18); // Towns token has 18 decimals
+
+  // 2. Generate unique nonce (you can use timestamp + random)
+  const nonce =
+    BigInt(Math.floor(Date.now() / 1000)) * 1000000n +
+    BigInt(Math.floor(Math.random() * 1000000));
+
+  // 3. Set deadline (e.g., 10 minutes from now)
+  const deadline = BigInt(Math.floor(Date.now() / 1000) + 600);
+
+  // 4. Create permit data structure
+  const permit: PermitTransferFrom = {
+    permitted: {
+      token: TOWNS_TOKEN_ADDRESS,
+      amount: amountWei,
+    },
+    spender: REWARDS_DISTRIBUTION_ADDRESS,
+    nonce: nonce,
+    deadline: deadline,
+  };
+
+  // 5. Create domain for signing
+  const domain = {
+    name: "Permit2",
+    version: "1",
+    chainId: base.id,
+    verifyingContract: PERMIT2_ADDRESS as `0x${string}`,
+  };
+
+  // 6. Sign the permit
+  const signature = await walletClient.signTypedData({
+    account,
+    domain,
+    types: SignatureTransfer.getPermitData(permit, PERMIT2_ADDRESS, base.id)
+      .types,
+    primaryType: "PermitTransferFrom",
+    message: SignatureTransfer.getPermitData(permit, PERMIT2_ADDRESS, base.id)
+      .values,
+  });
+
+  // 7. Call permitAndStake
+  const txHash = await walletClient.writeContract({
+    address: REWARDS_DISTRIBUTION_ADDRESS,
+    abi: [
+      {
+        name: "permitAndStake",
+        type: "function",
+        inputs: [
+          { name: "amount", type: "uint96" },
+          { name: "delegatee", type: "address" },
+          { name: "beneficiary", type: "address" },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+          { name: "signature", type: "bytes" },
+        ],
+        outputs: [{ name: "depositId", type: "uint256" }],
+      },
+    ],
+    functionName: "permitAndStake",
+    args: [amountWei, delegatee, beneficiary, nonce, deadline, signature],
+  });
+
+  return txHash;
+}
+
+// Usage example
+async function main() {
+  const txHash = await permitAndStake({
+    amount: "100", // Stake 100 Towns tokens
+    delegatee: "0x123...", // Operator address
+    beneficiary: "0x456...", // Beneficiary address
+  });
+
+  console.log("Transaction hash:", txHash);
+}
+```
+
+#### Wallet Integration (MetaMask/WalletConnect)
+
+```typescript
+import { useAccount, useSignTypedData, useWriteContract } from 'wagmi';
+
+function StakeWithPermit() {
+  const { address } = useAccount();
+  const { signTypedDataAsync } = useSignTypedData();
+  const { writeContractAsync } = useWriteContract();
+
+  const handleStakeWithPermit = async (amount: string, delegatee: string) => {
+    try {
+      // Prepare permit data
+      const amountWei = parseUnits(amount, 18);
+      const nonce = BigInt(Date.now());
+      const deadline = BigInt(Math.floor(Date.now() / 1000) + 600);
+
+      const permit = {
+        permitted: {
+          token: TOWNS_TOKEN_ADDRESS,
+          amount: amountWei,
+        },
+        spender: REWARDS_DISTRIBUTION_ADDRESS,
+        nonce,
+        deadline,
+      };
+
+      // Sign permit
+      const signature = await signTypedDataAsync({
+        domain: {
+          name: 'Permit2',
+          version: '1',
+          chainId: base.id,
+          verifyingContract: PERMIT2_ADDRESS,
+        },
+        types: SignatureTransfer.getPermitData(permit, PERMIT2_ADDRESS, base.id).types,
+        primaryType: 'PermitTransferFrom',
+        message: SignatureTransfer.getPermitData(permit, PERMIT2_ADDRESS, base.id).values,
+      });
+
+      // Execute stake
+      const txHash = await writeContractAsync({
+        address: REWARDS_DISTRIBUTION_ADDRESS,
+        abi: rewardsDistributionAbi,
+        functionName: 'permitAndStake',
+        args: [amountWei, delegatee, address, nonce, deadline, signature]
+      });
+
+      console.log('Staking successful:', txHash);
+    } catch (error) {
+      console.error('Staking failed:', error);
+    }
+  };
+
+  return (
+    <button onClick={() => handleStakeWithPermit("100", "0x...")}>
+      Stake with Permit
+    </button>
+  );
+}
+```
+
+## Security Considerations
+
+### 1. Nonce Management
+
+- **Uniqueness**: Each permit must use a unique nonce
+- **Collision Prevention**: Use timestamp-based or incrementing nonces
+- **Replay Protection**: Never reuse nonces
+
+### 2. Deadline Validation
+
+- **Short Expiry**: Use reasonable deadlines (5-30 minutes)
+- **Clock Skew**: Account for minor time differences between client and blockchain
+
+### 3. Signature Security
+
+- **Private Key Protection**: Never expose private keys in frontend code
+- **Secure Signing**: Use hardware wallets or secure key management for production
+- **Verification**: Always verify signature validity before submission
+
+### 4. Front-running Protection
+
+The permit signature cryptographically binds to `msg.sender`, preventing front-running attacks. An attacker cannot use someone else's signature because verification will fail.
+
+## Error Handling
+
+Common errors and solutions:
+
+```typescript
+try {
+  const txHash = await permitAndStake(...);
+} catch (error) {
+  if (error.message.includes('InvalidSignature')) {
+    // Signature verification failed - check signing process
+    console.error('Invalid permit signature');
+  } else if (error.message.includes('ExpiredDeadline')) {
+    // Deadline passed - generate new permit
+    console.error('Permit expired, please try again');
+  } else if (error.message.includes('InvalidNonce')) {
+    // Nonce already used or invalid
+    console.error('Invalid nonce, generate a new one');
+  }
+}
+```
+
+## Best Practices
+
+1. **Gas Optimization**: Batch multiple operations when possible
+2. **User Experience**: Show clear signing prompts explaining what users are approving
+3. **Error Messages**: Provide user-friendly error messages
+4. **Fallback**: Offer traditional `approve` + `stake` flow as backup
+5. **Testing**: Test with different wallet types (EOA, smart contract wallets)
+
+This integration enables gasless token approvals and enhanced compatibility with smart contract wallets, providing a superior user experience for staking in the Towns Protocol.