wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/adapters/ledger_adapter/README.md

@@ -0,0 +1,145 @@
+# Ledger Adapter
+
+A Wayfinder adapter that provides high-level operations for strategy transaction history and bookkeeping. This adapter wraps the `LedgerClient` to offer strategy-friendly methods for recording and retrieving strategy operations.
+
+## Capabilities
+
+- `ledger.read`: Read strategy transaction data and net deposits
+- `ledger.write`: Record deposits, withdrawals, and operations
+- `strategy.transactions`: Access strategy transaction history
+- `strategy.deposits`: Record deposit transactions
+- `strategy.withdrawals`: Record withdrawal transactions
+- `strategy.operations`: Record strategy 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.adapters.ledger_adapter.adapter import LedgerAdapter
+
+# No configuration needed - uses LedgerClient with automatic settings
+adapter = LedgerAdapter()
+```
+
+### Get Strategy Transaction History
+
+```python
+success, data = await adapter.get_strategy_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_strategy_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
+
+```python
+from wayfinder_paths.adapters.ledger_adapter.models import SWAP
+
+operation = SWAP(
+    from_token_id="0xA0b86...",
+    to_token_id="0xB1c97...",
+    from_amount="1000000000000000000",
+    to_amount="995000000000000000",
+    from_amount_usd=1000.0,
+    to_amount_usd=995.0,
+)
+
+success, op = await adapter.record_operation(
+    wallet_address=strategy_address,
+    operation_data=operation,
+    usd_value="1000.00",
+    strategy_name="StablecoinYieldStrategy",
+)
+
+```
+
+### Latest Transactions and Summaries
+
+```python
+success, latest = await adapter.get_strategy_latest_transactions(wallet_address=strategy_address)
+success, summary = await adapter.get_transaction_summary(wallet_address=strategy_address, limit=5)
+if success:
+    print(f"Total transactions: {summary.get('total_transactions')}")
+```
+
+## 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/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/adapters/ledger_adapter/__init__.py

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

wayfinder_paths/adapters/ledger_adapter/adapter.py

@@ -0,0 +1,289 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.adapters.models import Operation
+from wayfinder_paths.core.clients.LedgerClient import (
+    LedgerClient,
+    NetDeposit,
+    StrategyTransactionList,
+    TransactionRecord,
+)
+from wayfinder_paths.core.strategies.Strategy import StatusDict
+
+
+class LedgerAdapter(BaseAdapter):
+    """
+    Ledger adapter for strategy transaction history and bookkeeping operations.
+
+    Provides high-level operations for:
+    - Fetching strategy transaction history
+    - Getting net deposit amounts
+    - Getting last rotation time
+    - Recording deposits, withdrawals, and operations
+    """
+
+    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_strategy_transactions(
+        self, wallet_address: str, limit: int = 50, offset: int = 0
+    ) -> tuple[bool, StrategyTransactionList | str]:
+        """
+        Get paginated strategy transaction history.
+
+        Args:
+            wallet_address: Strategy 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_strategy_transactions(
+                wallet_address=wallet_address, limit=limit, offset=offset
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching strategy transactions: {e}")
+            return (False, str(e))
+
+    async def get_strategy_net_deposit(
+        self, wallet_address: str
+    ) -> tuple[bool, NetDeposit | str]:
+        """
+        Get net deposit amount (deposits - withdrawals) for a strategy.
+
+        Args:
+            wallet_address: Strategy wallet address
+
+        Returns:
+            Tuple of (success, data) where data contains net_deposit or error message
+        """
+        try:
+            data = await self.ledger_client.get_strategy_net_deposit(
+                wallet_address=wallet_address
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching strategy net deposit: {e}")
+            return (False, str(e))
+
+    async def get_strategy_latest_transactions(
+        self, wallet_address: str
+    ) -> tuple[bool, StrategyTransactionList | str]:
+        """
+        Get the latest transactions for a strategy.
+
+        Args:
+            wallet_address: Strategy wallet address
+
+        Returns:
+            Tuple of (success, data) where data contains latest transactions or error message
+        """
+        try:
+            data = await self.ledger_client.get_strategy_latest_transactions(
+                wallet_address=wallet_address
+            )
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error fetching strategy 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, TransactionRecord | str]:
+        """
+        Record a strategy deposit transaction.
+
+        Args:
+            wallet_address: Strategy 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_strategy_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, TransactionRecord | str]:
+        """
+        Record a strategy withdrawal transaction.
+
+        Args:
+            wallet_address: Strategy 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_strategy_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: Operation,
+        usd_value: str | float,
+        strategy_name: str | None = None,
+    ) -> tuple[bool, TransactionRecord | str]:
+        """
+        Record a strategy operation (e.g., swaps, rebalances) for bookkeeping.
+
+        Args:
+            wallet_address: Strategy wallet address
+            operation_data: Operation model (SWAP, LEND, BORROW, etc.)
+            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_strategy_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 get_transaction_summary(
+        self, wallet_address: str, limit: int = 10
+    ) -> tuple[bool, Any]:
+        """
+        Get a summary of recent strategy transactions.
+
+        Args:
+            wallet_address: Strategy 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_strategy_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))
+
+    async def record_strategy_snapshot(
+        self, wallet_address: str, strategy_status: StatusDict
+    ) -> tuple[bool, None | str]:
+        """
+        Record a strategy snapshot with current state.
+
+        Args:
+            wallet_address: Strategy wallet address
+            strat_portfolio_value: Current portfolio value
+            net_deposit: Net deposit amount
+            strategy_status: Current strategy status dictionary
+            gas_available: Available gas amount
+            gassed_up: Whether the strategy is gassed up
+
+        Returns:
+            Tuple of (success, None) on success or (False, error_message) on failure
+        """
+        try:
+            await self.ledger_client.strategy_snapshot(
+                wallet_address=wallet_address,
+                strat_portfolio_value=strategy_status["portfolio_value"],
+                net_deposit=strategy_status["net_deposit"],
+                strategy_status=strategy_status["strategy_status"],
+                gas_available=strategy_status["gas_available"],
+                gassed_up=strategy_status["gassed_up"],
+            )
+            return (True, None)
+        except Exception as e:
+            self.logger.error(f"Error recording strategy snapshot: {e}")
+            return (False, str(e))

wayfinder_paths/adapters/ledger_adapter/examples.json

@@ -0,0 +1,137 @@
+{
+  "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.)",
+    "note": "operation_data must be a Pydantic Operation model (currently only SWAP is implemented)",
+    "input": {
+      "wallet_address": "0x1234567890123456789012345678901234567890",
+      "operation_data": {
+        "type": "SWAP",
+        "from_token_id": "0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
+        "to_token_id": "0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+        "from_amount": "1000000000000000000",
+        "to_amount": "995000000000000000",
+        "from_amount_usd": 1000.0,
+        "to_amount_usd": 995.0,
+        "transaction_hash": "0xabcdef...",
+        "transaction_status": "success",
+        "transaction_receipt": null
+      },
+      "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/adapters/ledger_adapter/manifest.yaml

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