README

Minimal, asset-agnostic wallet contract for crypto assets (BTC, ETH, tokens, etc.).

Provides a clean and minimal WalletInterface to abstract wallet operations such as
creating addresses, validating them, querying balances, and sending transfers.

✨ Features

• Minimal API surface
  Only the essentials: create address, validate, query balances, transfer.

• Asset-agnostic
  Works for coins (BTC/ETH) and tokens (ERC-20, etc.).

• Safe amount handling
  All amounts are passed as decimal strings to avoid floating-point errors.

• Extensible via options
  transferMany() accepts optional parameters (fee_rate, nonce, gas_limit, …).

• Testability
  Ships with pestphp/pest integration and phpstan support.

📦 Installation

composer require tetthys/wallet

For development:

composer install
composer test
composer analyse

🚀 Usage

use Tetthys\Wallet\Contracts\WalletInterface;

/** @var WalletInterface $wallet */

// Create a new address
$addr = $wallet->createAddress('customer:123');

// Validate
if (!$wallet->validateAddress($addr)) {
    throw new \RuntimeException("Invalid address");
}

// Query balances
$spendable = $wallet->getAvailableBalance();   // "0.015"
$received  = $wallet->getReceivedAmount($addr); // "0.010"

// Transfer to many
$txid = $wallet->transferMany(
    [
        ['to' => 'addr1...', 'amount' => '0.004'],
        ['to' => 'addr2...', 'amount' => '0.001', 'memo' => 'invoice#42'],
    ],
    [
        'fee_rate' => 'fast',
        'subtract_fee_from' => [0],
    ]
);

⚠️ Exceptions

All exceptions extend \RuntimeException:

• AddressCreationException
• BalanceQueryException
• DepositQueryException
• AddressValidationException
• TransferException

🧪 Testing

composer test

Runs the Pest test suite inside the package.

🔍 Static Analysis

composer analyse

Runs PHPStan at max level on src/.

📂 Project Structure

tetthys/wallet
├── src/
│   ├── Contracts/
│   │   └── WalletInterface.php
│   └── Exceptions/
│       ├── AddressCreationException.php
│       ├── BalanceQueryException.php
│       ├── DepositQueryException.php
│       ├── AddressValidationException.php
│       └── TransferException.php
├── tests/
│   └── WalletInterfaceTest.php
├── composer.json
└── README.md

📜 License

MIT License. See LICENSE file.