Metadata-Version: 2.4
Name: flexvaults-sdk
Version: 0.1.13
Summary: Python SDK for Flexvaults - manage deposits, withdrawals, locks, and transfers
Project-URL: Homepage, https://github.com/oasisprotocol/flexvaults-sdk
Project-URL: Repository, https://github.com/oasisprotocol/flexvaults-sdk
Project-URL: Issues, https://github.com/oasisprotocol/flexvaults-sdk/issues
Author-email: Oasis Protocol Foundation <security@oasisprotocol.org>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.13.0
Requires-Dist: eth-typing>=5.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# flexvaults-sdk

Python SDK for Flexvaults - manage deposits, withdrawals, locks, and transfers on the accounting module.

## Installation

```bash
pip install flexvaults-sdk
```

## Quick Start

```python
import asyncio
from flexvaults import FlexvaultsClient, DepositQuoteRequest

async def main():
    async with FlexvaultsClient(base_url="https://api.example.com") as client:
        # Get a deposit quote
        quote = await client.get_deposit_quote(
            DepositQuoteRequest(
                user_address="0xYourAddress",
                token_id="0xTokenId",
                amount=1000000,
            )
        )
        print(f"Deposit to: {quote.deposit_address}")

asyncio.run(main())
```

## Direct SIWE Private Reads

Private read endpoints such as balances and locked funds use the backend's direct SIWE flow.
The Python SDK exposes the raw helpers and token setters rather than a hosted auth-code wrapper.

```python
import asyncio
from flexvaults import FlexvaultsClient

async def main():
    async with FlexvaultsClient(base_url="https://api.example.com") as client:
        domain = await client.get_siwe_domain()
        nonce = await client.get_siwe_nonce("0xYourAddress")

        # Build and sign the SIWE message in your app, then submit it here.
        login = await client.authenticate_private_reads(
            siwe_message="your signed-in message",
            signature="0xYourSignature",
        )

        balance = await client.get_balance("0xTokenId")
        print(domain.domain, nonce.nonce, login.address, balance.balance)

asyncio.run(main())
```

## EIP-712 Signing

```python
from eth_account import Account
from flexvaults import (
    sign_lock_message,
    LockNonceResponse,
    SignLockParams,
    LockMessage,
    get_accounting_contract,
    create_lock_expiry,
)

account = Account.from_key("0xYourPrivateKey")

signature = sign_lock_message(
    SignLockParams(
        account=account,
        network="testnet",
        verifying_contract=get_accounting_contract("testnet"),
        message=LockMessage(
            user_address=account.address,
            service_address="0xServiceAddress",
            token_id="0xTokenId",
            amount=1000000,
            expiry=create_lock_expiry(60),
            nonce=0,
        ),
    )
)
```

## API Reference

### Client

- `FlexvaultsClient(base_url, timeout=30.0, headers=None)` - Main API client
  - `get_deposit_quote(request)` - Get deposit quote
  - `include_deposit(request)` - Include deposit proof
  - `get_balance(token_id)` - Get token balance for the authenticated user
  - `get_batch_balances(request)` - Get multiple token balances
  - `get_token_info(token_id)` - Get token information
  - `lock_funds(request)` - Lock funds for a service
  - `get_lock_nonce(user_address)` - Get next create-lock nonce
  - `get_modify_lock_nonce(user_address)` - Get next modify-lock nonce
  - `modify_lock(request)` - Modify an existing lock (add funds and/or extend expiry)
  - `unlock_funds(request)` - Unlock specific lock
  - `unlock_all_expired(request)` - Unlock all expired locks
  - `get_locked_funds(service_address=None)` - Get locked funds for the authenticated user
  - `get_total_locked_balance(token_id)` - Get total locked balance for the authenticated user
  - `get_expired_locks()` - Get expired locks for the authenticated user
  - `transfer_funds(request)` - Transfer tokens (requires nonce)
  - `get_transfer_nonce(user_address)` - Get next transfer nonce
  - `transfer_locked_funds(request)` - Transfer locked tokens
  - `get_transfer_locked_nonce(service_address)` - Get next transfer-from-lock nonce
  - `request_withdrawal(request)` - Request withdrawal
  - `get_withdrawal_nonce(user_address)` - Get next withdrawal nonce
  - `get_pending_withdrawals(user_address)` - Get pending withdrawals
  - `get_withdrawal_info(index)` - Get withdrawal info
  - `get_siwe_domain()` - Get the direct SIWE auth domain
  - `get_siwe_nonce(user_address)` - Get a SIWE login nonce
  - `login_with_siwe(siwe_message, signature)` - Exchange a signed SIWE message for tokens
  - `authenticate_private_reads(siwe_message, signature)` - Login and store `X-SIWE-Token`
  - `set_private_read_token(token)` / `clear_private_read_token()` - Manage `X-SIWE-Token`
  - `set_bearer_token(token)` / `clear_bearer_token()` - Manage bearer auth headers

### Signing

- `sign_lock_message(params)` - Sign lock message
- `sign_modify_lock_message(params)` - Sign modify lock message
- `sign_transfer_message(params)` - Sign transfer message
- `sign_transfer_locked_message(params)` - Sign transfer locked message
- `sign_withdraw_message(params)` - Sign withdrawal message
- `create_lock_expiry(minutes_from_now=60)` - Create expiry timestamp

### Utilities

- `format_token_amount(amount, decimals=18)` - Format wei to human-readable
- `parse_token_amount(amount, decimals=18)` - Parse human-readable to wei
- `shorten_address(address, chars=4)` - Shorten Ethereum address
- `format_timestamp(timestamp)` - Format Unix timestamp to readable string
- `is_expired(expiry)` - Check if timestamp is expired
- `format_time_remaining(expiry_timestamp)` - Format time remaining
- `format_relative_time(timestamp)` - Format relative time (e.g., "5m ago")

## License

Apache-2.0
