# KuruForwarder

A Rust implementation for handling meta-transactions (gasless transactions) through a forwarder contract.

## Quick Reference

```rust
// Initialize forwarder
let forwarder = KuruForwarder::new(
    "0x1234...", 
    provider,
    Arc::new(wallet)
)?;

// Create forward request
let request = KuruRequest::ForwardRequest(ForwardRequest {
    from: user_address,
    market: market_address,
    value: U256::ZERO,
    nonce: forwarder.nonce(user_address).await?,
    data: transaction_data,
});

// Execute meta-transaction
let receipt = forwarder.execute(request, signature).await?;
```

## Types

### Request Structures
```rust
pub struct ForwardRequest {
    pub from: Address,      // Original transaction sender
    pub market: Address,    // Target market contract
    pub value: U256,        // Transaction value
    pub nonce: U256,       // User's current nonce
    pub data: Bytes,       // Encoded transaction data
}

pub struct MarginRequest {
    pub from: Address,
    pub margin_account: Address,
    pub value: U256,
    pub nonce: U256,
    pub data: Bytes,
}

pub enum KuruRequest {
    ForwardRequest(ForwardRequest),
    MarginRequest(MarginRequest),
}
```

### Error Types
```rust
pub enum KuruForwarderError {
    InitializationError(String),
    ContractError(String),
    NonceFetchError(String),
    TxBuildError(String),
    ProviderError(String),
    SignatureError(String),
    InvalidReturnValue,
    RequestConversionError(String),
}
```

## Main Methods

### Constructor
```rust
pub fn new(
    kuru_forwarder_address: &str,
    provider: P,
    wallet: Arc<EthereumWallet>
) -> Result<Self, KuruForwarderError>
```

### Transaction Methods
```rust
// Get current nonce for user
pub async fn nonce(
    &self, 
    user_address: Address
) -> Result<U256, KuruForwarderError>

// Execute meta-transaction
pub async fn execute(
    &self,
    request: KuruRequest,
    signature: String
) -> Result<TransactionReceipt, KuruForwarderError>
```

## Usage Example

```rust
// 1. Get user's current nonce
let user_nonce = forwarder.nonce(user_address).await?;

// 2. Create forward request
let forward_request = ForwardRequest {
    from: user_address,
    market: market_address,
    value: U256::ZERO,
    nonce: user_nonce,
    data: encoded_function_call,
};

// 3. Wrap in KuruRequest enum
let request = KuruRequest::ForwardRequest(forward_request);

// 4. Execute with user's signature
let receipt = forwarder.execute(request, user_signature).await?;
```

## Security Considerations

1. Nonce Management
   - Always fetch fresh nonce before creating request
   - Nonce prevents replay attacks
   - Verify nonce hasn't changed before submission

2. Signature Validation
   - Signatures must be 65 bytes (r, s, v format)
   - Include '0x' prefix in signature strings
   - Invalid signatures will be rejected

3. Gas Management
   - Forwarder handles gas estimation
   - Requires sufficient balance in relayer wallet
   - Gas limits are automatically calculated

## Notes
- Supports both regular and margin trading meta-transactions
- Automatically handles gas estimation and pricing
- Converts between Rust and Solidity types
- Requires valid EthereumWallet for transaction signing
- All errors are properly propagated with context