wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/vaults/adapters/ledger_adapter/README.md

@@ -0,0 +1,158 @@
+# Ledger Adapter
+
+A Wayfinder adapter that provides high-level operations for vault transaction history and bookkeeping. This adapter wraps the `LedgerClient` to offer strategy-friendly methods for recording and retrieving vault operations.
+
+## Capabilities
+
+- `ledger.read`: Read vault transaction data and net deposits
+- `ledger.write`: Record deposits, withdrawals, and operations
+- `vault.transactions`: Access vault transaction history
+- `vault.deposits`: Record deposit transactions
+- `vault.withdrawals`: Record withdrawal transactions
+- `vault.operations`: Record vault operations (swaps, rebalances, etc.)
+
+## Configuration
+
+The adapter uses the LedgerClient which automatically handles authentication and API configuration through the Wayfinder settings. No additional configuration is required.
+
+The LedgerClient will automatically:
+- Use the WAYFINDER_API_URL from settings
+- Handle authentication via environment variables or config.json
+- Manage token refresh and retry logic
+
+## Usage
+
+### Initialize the Adapter
+
+```python
+from wayfinder_paths.vaults.adapters.ledger_adapter.adapter import LedgerAdapter
+
+# No configuration needed - uses LedgerClient with automatic settings
+adapter = LedgerAdapter()
+```
+
+### Get Vault Transaction History
+
+```python
+success, data = await adapter.get_vault_transactions(
+    wallet_address="0x1234567890123456789012345678901234567890",
+    limit=10,
+    offset=0
+)
+if success:
+    transactions = data.get("transactions", [])
+    print(f"Found {len(transactions)} transactions")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Net Deposit Amount
+
+```python
+success, data = await adapter.get_vault_net_deposit(
+    wallet_address="0x1234567890123456789012345678901234567890"
+)
+if success:
+    net_deposit = data.get("net_deposit", 0)
+    print(f"Net deposit: {net_deposit} USDC")
+else:
+    print(f"Error: {data}")
+```
+
+### Record a Deposit
+
+```python
+success, data = await adapter.record_deposit(
+    wallet_address="0x1234567890123456789012345678901234567890",
+    chain_id=8453,
+    token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    token_amount="1000000000000000000",
+    usd_value="1000.00",
+    strategy_name="StablecoinYieldStrategy"
+)
+if success:
+    print(f"Deposit recorded: {data.get('transaction_id')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Record a Withdrawal
+
+```python
+success, data = await adapter.record_withdrawal(
+    wallet_address="0x1234567890123456789012345678901234567890",
+    chain_id=8453,
+    token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+    token_amount="500000000000000000",
+    usd_value="500.00",
+    strategy_name="StablecoinYieldStrategy"
+)
+if success:
+    print(f"Withdrawal recorded: {data.get('transaction_id')}")
+else:
+    print(f"Error: {data}")
+```
+
+### Record an Operation or Cashflow
+
+```python
+success, op = await adapter.record_operation(
+    wallet_address=vault_address,
+    operation_data={
+        "type": "SWAP",
+        "from_token": "...",
+        "to_token": "...",
+        "amount_in": "1000000000000000000",
+        "amount_out": "995000000000000000",
+    },
+    usd_value="1000.00",
+    strategy_name="StablecoinYieldStrategy",
+)
+
+success, cashflow = await adapter.record_cashflow(
+    wallet_address=vault_address,
+    block_timestamp=int(time.time()),
+    token_addr="0x...",
+    amount="250000000000000000",
+    description="reward",
+    strategy_name="StablecoinYieldStrategy",
+)
+```
+
+### Latest Transactions and Summaries
+
+```python
+success, latest = await adapter.get_vault_latest_transactions(wallet_address=vault_address)
+success, summary = await adapter.get_transaction_summary(wallet_address=vault_address, limit=5)
+if success:
+    print(f"Total transactions: {summary.get('total_transactions')}")
+```
+
+## API Endpoints
+
+The adapter uses the following Wayfinder API endpoints:
+
+- `GET /api/v1/public/vaults/transactions/` - Get vault transactions
+- `GET /api/v1/public/vaults/net-deposit/` - Get net deposit amount
+- `POST /api/v1/public/vaults/deposits/` - Record a deposit
+- `POST /api/v1/public/vaults/withdrawals/` - Record a withdrawal
+- `POST /api/v1/public/vaults/operations/` - Record an operation
+
+## Error Handling
+
+All methods return a tuple of `(success: bool, data: Any)` where:
+- `success` is `True` if the operation succeeded
+- `data` contains the response data on success or error message on failure
+
+## Testing
+
+Run the adapter tests:
+
+```bash
+pytest wayfinder_paths/vaults/adapters/ledger_adapter/test_adapter.py -v
+```
+
+## Dependencies
+
+- `LedgerClient` - Low-level API client for ledger operations
+- `BaseAdapter` - Base adapter class with common functionality

wayfinder_paths/vaults/adapters/ledger_adapter/__init__.py

@@ -0,0 +1,7 @@
+"""
+Ledger Adapter Package
+"""
+
+from .adapter import LedgerAdapter
+
+__all__ = ["LedgerAdapter"]

wayfinder_paths/vaults/adapters/ledger_adapter/adapter.py

@@ -0,0 +1,286 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.LedgerClient import LedgerClient
+
+
+class LedgerAdapter(BaseAdapter):
+    """
+    Ledger adapter for vault transaction history and bookkeeping operations.
+
+    Provides high-level operations for:
+    - Fetching vault transaction history
+    - Getting net deposit amounts
+    - Getting last rotation time
+    - Recording deposits, withdrawals, operations, and cashflows
+    """
+
+    adapter_type: str = "LEDGER"
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        ledger_client: LedgerClient | None = None,
+    ):
+        super().__init__("ledger_adapter", config)
+        self.ledger_client = ledger_client or LedgerClient()
+
+    async def get_vault_transactions(
+        self, wallet_address: str, limit: int = 50, offset: int = 0
+    ) -> tuple[bool, Any]:
+        """
+        Get paginated vault transaction history.
+
+        Args:
+            wallet_address: Vault wallet address
+            limit: Maximum number of transactions to return
+            offset: Number of transactions to skip
+
+        Returns:
+            Tuple of (success, data) where data is transaction list or error message
+        """
+        try:
+            data = await self.ledger_client.get_vault_transactions(
+                wallet_address=wallet_address, limit=limit, offset=offset
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching vault transactions: {e}")
+            return (False, str(e))
+
+    async def get_vault_net_deposit(self, wallet_address: str) -> tuple[bool, Any]:
+        """
+        Get net deposit amount (deposits - withdrawals) for a vault.
+
+        Args:
+            wallet_address: Vault wallet address
+
+        Returns:
+            Tuple of (success, data) where data contains net_deposit or error message
+        """
+        try:
+            data = await self.ledger_client.get_vault_net_deposit(
+                wallet_address=wallet_address
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching vault net deposit: {e}")
+            return (False, str(e))
+
+    async def get_vault_latest_transactions(
+        self, wallet_address: str
+    ) -> tuple[bool, Any]:
+        """
+        Get the latest transactions for a vault.
+
+        Args:
+            wallet_address: Vault wallet address
+
+        Returns:
+            Tuple of (success, data) where data contains latest transactions or error message
+        """
+        try:
+            data = await self.ledger_client.get_vault_latest_transactions(
+                wallet_address=wallet_address
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching vault last transactions: {e}")
+            return (False, str(e))
+
+    async def record_deposit(
+        self,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> tuple[bool, Any]:
+        """
+        Record a vault deposit transaction.
+
+        Args:
+            wallet_address: Vault wallet address
+            chain_id: Blockchain chain ID
+            token_address: Token contract address
+            token_amount: Amount deposited (in token units)
+            usd_value: USD value of the deposit
+            data: Additional transaction data
+            strategy_name: Name of the strategy making the deposit
+
+        Returns:
+            Tuple of (success, data) where data is transaction record or error message
+        """
+        try:
+            result = await self.ledger_client.add_vault_deposit(
+                wallet_address=wallet_address,
+                chain_id=chain_id,
+                token_address=token_address,
+                token_amount=token_amount,
+                usd_value=usd_value,
+                data=data,
+                strategy_name=strategy_name,
+            )
+            return (True, result)
+        except Exception as e:
+            self.logger.error(f"Error recording deposit: {e}")
+            return (False, str(e))
+
+    async def record_withdrawal(
+        self,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> tuple[bool, Any]:
+        """
+        Record a vault withdrawal transaction.
+
+        Args:
+            wallet_address: Vault wallet address
+            chain_id: Blockchain chain ID
+            token_address: Token contract address
+            token_amount: Amount withdrawn (in token units)
+            usd_value: USD value of the withdrawal
+            data: Additional transaction data
+            strategy_name: Name of the strategy making the withdrawal
+
+        Returns:
+            Tuple of (success, data) where data is transaction record or error message
+        """
+        try:
+            result = await self.ledger_client.add_vault_withdraw(
+                wallet_address=wallet_address,
+                chain_id=chain_id,
+                token_address=token_address,
+                token_amount=token_amount,
+                usd_value=usd_value,
+                data=data,
+                strategy_name=strategy_name,
+            )
+            return (True, result)
+        except Exception as e:
+            self.logger.error(f"Error recording withdrawal: {e}")
+            return (False, str(e))
+
+    async def record_operation(
+        self,
+        wallet_address: str,
+        operation_data: dict[str, Any],
+        usd_value: str | float,
+        strategy_name: str | None = None,
+    ) -> tuple[bool, Any]:
+        """
+        Record a vault operation (e.g., swaps, rebalances) for bookkeeping.
+
+        Args:
+            wallet_address: Vault wallet address
+            operation_data: Details of the operation performed
+            usd_value: USD value of the operation
+            strategy_name: Name of the strategy performing the operation
+
+        Returns:
+            Tuple of (success, data) where data is operation record or error message
+        """
+        try:
+            result = await self.ledger_client.add_vault_operation(
+                wallet_address=wallet_address,
+                operation_data=operation_data,
+                usd_value=usd_value,
+                strategy_name=strategy_name,
+            )
+            return (True, result)
+        except Exception as e:
+            self.logger.error(f"Error recording operation: {e}")
+            return (False, str(e))
+
+    async def record_cashflow(
+        self,
+        wallet_address: str,
+        block_timestamp: int,
+        token_addr: str,
+        amount: str | int | float,
+        description: str,
+        strategy_name: str | None = None,
+    ) -> tuple[bool, Any]:
+        """
+        Record a vault cashflow (interest, funding, reward, or fee).
+
+        Args:
+            wallet_address: Vault wallet address
+            block_timestamp: Block timestamp (Unix timestamp)
+            token_addr: Token contract address
+            amount: Cashflow amount (in token units)
+            description: Cashflow type - must be one of: "interest", "funding", "reward", "fee"
+            strategy_name: Optional strategy name
+
+        Returns:
+            Tuple of (success, data) where data is cashflow record or error message
+        """
+        try:
+            result = await self.ledger_client.add_vault_cashflow(
+                wallet_address=wallet_address,
+                block_timestamp=block_timestamp,
+                token_addr=token_addr,
+                amount=amount,
+                description=description,
+                strategy_name=strategy_name,
+            )
+            return (True, result)
+        except Exception as e:
+            self.logger.error(f"Error recording cashflow: {e}")
+            return (False, str(e))
+
+    async def get_transaction_summary(
+        self, wallet_address: str, limit: int = 10
+    ) -> tuple[bool, Any]:
+        """
+        Get a summary of recent vault transactions.
+
+        Args:
+            wallet_address: Vault wallet address
+            limit: Number of recent transactions to include
+
+        Returns:
+            Tuple of (success, data) where data is transaction summary or error message
+        """
+        try:
+            success, transactions_data = await self.get_vault_transactions(
+                wallet_address=wallet_address, limit=limit
+            )
+
+            if not success:
+                return (False, transactions_data)
+
+            transactions = transactions_data.get("transactions", [])
+
+            # Create summary
+            summary = {
+                "total_transactions": len(transactions),
+                "recent_transactions": transactions[:limit],
+                "operations": {
+                    "deposits": len(
+                        [t for t in transactions if t.get("operation") == "DEPOSIT"]
+                    ),
+                    "withdrawals": len(
+                        [t for t in transactions if t.get("operation") == "WITHDRAW"]
+                    ),
+                    "operations": len(
+                        [
+                            t
+                            for t in transactions
+                            if t.get("operation") not in ["DEPOSIT", "WITHDRAW"]
+                        ]
+                    ),
+                },
+            }
+
+            return (True, summary)
+        except Exception as e:
+            self.logger.error(f"Error creating transaction summary: {e}")
+            return (False, str(e))

wayfinder_paths/vaults/adapters/ledger_adapter/examples.json

@@ -0,0 +1,131 @@
+{
+  "get_vault_transactions": {
+    "description": "Get vault transaction history",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "limit": 10,
+      "offset": 0
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "transactions": [
+          {
+            "id": "tx_123",
+            "operation": "DEPOSIT",
+            "timestamp": "2024-01-15T10:30:00Z",
+            "amount": "1000000000000000000",
+            "token_address": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+            "usd_value": "1000.00",
+            "strategy_name": "StablecoinYieldStrategy"
+          }
+        ],
+        "total": 1,
+        "limit": 10,
+        "offset": 0
+      }
+    }
+  },
+  "get_vault_net_deposit": {
+    "description": "Get net deposit amount for a vault",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890"
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "net_deposit": "1000.00",
+        "total_deposits": "1500.00",
+        "total_withdrawals": "500.00"
+      }
+    }
+  },
+  "record_deposit": {
+    "description": "Record a vault deposit",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "chain_id": 8453,
+      "token_address": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+      "token_amount": "1000000000000000000",
+      "usd_value": "1000.00",
+      "strategy_name": "StablecoinYieldStrategy"
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "transaction_id": "tx_456",
+        "status": "recorded",
+        "timestamp": "2024-01-15T10:30:00Z"
+      }
+    }
+  },
+  "record_withdrawal": {
+    "description": "Record a vault withdrawal",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "chain_id": 8453,
+      "token_address": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+      "token_amount": "500000000000000000",
+      "usd_value": "500.00",
+      "strategy_name": "StablecoinYieldStrategy"
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "transaction_id": "tx_789",
+        "status": "recorded",
+        "timestamp": "2024-01-15T11:00:00Z"
+      }
+    }
+  },
+  "record_operation": {
+    "description": "Record a vault operation (swap, rebalance, etc.)",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "operation_data": {
+        "type": "SWAP",
+        "from_token": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+        "to_token": "0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+        "amount_in": "1000000000000000000",
+        "amount_out": "995000000000000000"
+      },
+      "usd_value": "1000.00",
+      "strategy_name": "StablecoinYieldStrategy"
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "operation_id": "op_123",
+        "status": "recorded",
+        "timestamp": "2024-01-15T10:45:00Z"
+      }
+    }
+  },
+  "get_transaction_summary": {
+    "description": "Get a summary of recent vault transactions",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "limit": 5
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "total_transactions": 3,
+        "recent_transactions": [
+          {
+            "id": "tx_123",
+            "operation": "DEPOSIT",
+            "timestamp": "2024-01-15T10:30:00Z",
+            "amount": "1000000000000000000",
+            "usd_value": "1000.00"
+          }
+        ],
+        "operations": {
+          "deposits": 1,
+          "withdrawals": 1,
+          "operations": 1
+        }
+      }
+    }
+  }
+}

wayfinder_paths/vaults/adapters/ledger_adapter/manifest.yaml

@@ -0,0 +1,11 @@
+schema_version: "0.1"
+entrypoint: "vaults.adapters.ledger_adapter.adapter.LedgerAdapter"
+capabilities:
+  - "ledger.read"
+  - "ledger.write"
+  - "vault.transactions"
+  - "vault.deposits"
+  - "vault.withdrawals"
+  - "vault.operations"
+dependencies:
+  - "LedgerClient"