kknongchang_2506/app/Module/Blockchain/Contracts/BlockchainServiceInterface.php

<?php

namespace App\Module\Blockchain\Contracts;

use App\Module\Blockchain\Dto\TransactionStatus;
use App\Module\Transaction\Enums\ACCOUNT_TYPE;

interface BlockchainServiceInterface
{

    /**
     * 获取代币余额
     *
     * @param string $address 钱包地址
     * @param ACCOUNT_TYPE $tokenType 代币类型
     * @return float 余额
     */
    public function getBalance(string $address, ACCOUNT_TYPE $tokenType): float;

    /**
     * 验证地址是否有效
     *
     * @param string $address 钱包地址
     * @return bool
     */
    public function isValidAddress(string $address): bool;

    /**
     * 获取交易状态
     *
     * @param string $txHash 交易哈希
     * @return array{
     *     status: int,
     *     blockNumber: ?int,
     *     gasUsed: ?string,
     *     effectiveGasPrice: ?string
     * }
     */
    public function getTransactionStatus(string $txHash): TransactionStatus;

    /**
     * 获取交易收据
     *
     * @param string $txHash 交易哈希
     * @return array 交易收据详情
     */
    public function getTransactionReceipt(string $txHash): array;

    /**
     * 估算Gas费用
     *
     * @param string $from 发送地址
     * @param string $to 接收地址
     * @param ACCOUNT_TYPE $tokenType 代币类型
     * @param float $amount 金额
     * @return float Gas费用（BNB）
     */
    public function estimateGasFee(string $from, string $to, ACCOUNT_TYPE $tokenType, float $amount): float;

    /**
     * 获取交易历史
     *
     * @param string $address 钱包地址
     * @param ACCOUNT_TYPE $tokenType 代币类型
     * @param int $page 页码
     * @param int $limit 每页数量
     * @return array 交易历史列表
     */
    public function getTransactionHistory(string $address, ACCOUNT_TYPE $tokenType, int $page = 1, int $limit = 10): array;

}