پرش به مطلب اصلی

بازپرداخت صندوق

در یک نگاه​

این مستندات نشان می‌دهد که چگونه بازپرداخت صندوق را در سیستم استیبل‌کوین زربان پیاده می‌کنید. این SDK با کمک Web3 و API زربان، بازپرداخت صندوق‌های موجود و مدیریت تراکنش و ثبت جزئیات بازپرداخت را در اختیارتان می‌گذارد.

پیش‌نیازها​

  • نصب Web3
  • نصب Zarban
  • دسترسی به نود اتریوم، یعنی یک آدرس RPC
  • کلید خصوصی‌ای که موجودی کافی داشته باشد

نصب​

pip install zarban

اجزای اصلی​

۱. تبدیل مقادیر​

to_native(amount)​

مقدار خوانا برای انسان را به قالب بومی بلاکچین (wei) تبدیل می‌کند.

پارامترها:

  • amount (float): مقداری که می‌خواهید تبدیل کنید

خروجی:

  • str: مقدار به قالب بومی بلاکچین

مثال:

native_amount = to_native(1.5)

۲. پردازش تراکنش بازپرداخت صندوق​

get_vault_tx_steps(api, wallet_address, vault_id, amount)​

مراحل تراکنشِ بازپرداخت صندوق را برمی‌گرداند.

پارامترها:

  • api (service.StableCoinSystemApi): نمونه StableCoinSystemApi
  • wallet_address (str): آدرس کیف پول کاربر
  • vault_id (int): شناسه صندوقی که می‌خواهید بازپرداخت کنید
  • amount (float): مقدار بازپرداخت

خروجی:

  • dict: (تعداد مراحل، شماره مرحله، مراحل)

۳. مدیریت تراکنش​

wait_for_transaction_receipt(w3, tx_hash, max_wait_time=120, check_interval=15)​

منتظر می‌ماند تا تراکنش تأیید شود.

پارامترها:

  • w3: نمونه Web3
  • tx_hash: هش تراکنش
  • max_wait_time: حداکثر زمان انتظار به ثانیه
  • check_interval: فاصله بررسی به ثانیه

خروجی:

  • رسید تراکنش یا None

۴. ثبت تراکنش​

save_transaction_details(tx, tx_hash)​

جزئیات تراکنش را در یک فایل JSON می‌نویسد.

پارامترها:

  • tx: شیء تراکنش
  • tx_hash: هش تراکنش

مثال پیاده‌سازی کامل​

# Configuration
HTTPS_RPC_URL = "your_ethereum_node_url"
PRIVATE_KEY = "your_private_key"
WALLET_ADDRESS = get_address_from_private_key(PRIVATE_KEY)

# Setup API client
cfg = service.Configuration(host="https://testapi.zarban.io")
api_client = ApiClient(cfg)
stable_coin_system_api = service.StableCoinSystemApi(api_client)

# Setup Web3
w3 = Web3(Web3.HTTPProvider(HTTPS_RPC_URL))

# Vault repayment parameters
VAULT_ID = 123  # Replace with your actual vault ID
REPAYMENT_AMOUNT = 500  # Replace with your actual repayment amount

# Repay vault
num_of_steps, step_number, steps = get_vault_tx_steps(
    stable_coin_system_api,
    WALLET_ADDRESS,
    VAULT_ID,
    REPAYMENT_AMOUNT
)

جریان تراکنش​

  1. مقداردهی اولیه

    • کلاینت API و اتصال Web3 را راه بیندازید
    • پارامترهای بازپرداخت صندوق را پیکربندی کنید

  2. مراحل تراکنش

    • مراحل بازپرداخت صندوق را بگیرید
    • هر مرحله را به ترتیب پردازش کنید
    • تراکنش را امضا و ارسال کنید

  3. نظارت بر تراکنش

    • منتظر تأیید تراکنش بمانید
    • جزئیات تراکنش را ثبت کنید

  4. تأیید نتیجه

    • لاگ‌های تراکنش را بررسی کنید تا از موفق بودن بازپرداخت مطمئن شوید

مدیریت خطا​

try:
    # Vault repayment code
except service.ApiException as e:
    print(f"Response body: {beautify_json(e.body)}")
except Exception as e:
    print(f"Unexpected error: {e}")

نکات مهم​

  1. امنیت

    • هرگز کلید خصوصی را داخل کد ننویسید
    • داده‌های حساس را در متغیرهای محیطی بگذارید
    • همه پارامترهای تراکنش را پیش از امضا وارسی کنید

  2. مدیریت تراکنش

    • همیشه منتظر بمانید تا تراکنش تأیید شود
    • خطاها را درست مدیریت کنید
    • همه تراکنش‌ها را برای حسابرسی ثبت کنید

  3. مدیریت گس1

    • محدودیت گس را درست تنظیم کنید
    • قیمت گس را رصد کنید
    • برای تراکنش‌های ناموفق سازوکار تلاش مجدد بگذارید

ثبت و نظارت​

سیستم یک فایل ثبت تراکنش (repay_transaction_log.json) را با اطلاعات زیر نگهداری می‌کند:

  • زمان
  • جزئیات تراکنش
  • هش تراکنش

مثال ورودی لاگ:

{
  "timestamp": "2024-03-13T10:00:00",
  "tx": {
    "from": "0x...",
    "to": "0x...",
    "value": "1000000000000000",
    "gas": 200000
  },
  "tx_hash": "0x..."
}

محدودیت‌ها و ملاحظات​

  1. وابستگی‌های شبکه

    • به اتصال پایدار شبکه نیاز دارد
    • به وضعیت شبکه اتریوم وابسته است
    • ازدحام شبکه می‌تواند رویش اثر بگذارد

  2. نیازمندی‌های منابع

    • اتر کافی برای هزینه گس
    • دسترسی معتبر به API

  3. زمان‌بندی تراکنش

    • زمان تأیید تراکنش ثابت نیست
    • حداکثر زمان انتظار را می‌توانید تنظیم کنید
    • ممکن است چند مرحله لازم باشد

عیب‌یابی​

مشکلات اتصال​

if not w3.is_connected():
    print(f"Failed to connect to {HTTPS_RPC_URL}")
    exit(1)

شکست تراکنش‌ها​

  • قیمت و محدودیت گس را بررسی کنید
  • موجودی حساب را وارسی کنید
  • وضعیت شبکه را بررسی کنید

خطاهای API​

  • اعتبارنامه API را وارسی کنید
  • پارامترهای درخواست را بررسی کنید
  • پاسخ خطا را بخوانید

پشتیبانی​

برای پشتیبانی بیشتر یا گزارش اشکال، با تیم پشتیبانی زربان تماس بگیرید یا به مستندات API سر بزنید.

بیشتر بخوانید​

Footnotes​

  1. gas ↩