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

ایجاد صندوق

در یک نگاه​

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

پیش‌نیازها​

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

نصب​

pip install zarban

اجزای اصلی​

۱. مدیریت انواع وثیقه​

get_ilks_symbol(api)​

انواع وثیقه‌ای را که سیستم پشتیبانی می‌کند برمی‌گرداند.

پارامترها:

  • api (service.StableCoinSystemApi): نمونه کلاینت API

خروجی:

  • list: نماد یکتای هر نوع وثیقه

مثال:

symbols = get_ilks_symbol(stable_coin_system_api)

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

to_native(api, symbol, amount)​

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

پارامترها:

  • api (service.StableCoinSystemApi): نمونه کلاینت API
  • symbol (str): نماد دارایی (مثلاً "ETH"، "ZAR")
  • amount (float): مقدار خوانا برای انسان

خروجی:

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

مثال:

native_amount = to_native(api, "ETH", 0.01)

۳. پردازش تراکنش صندوق​

get_vault_tx_steps(api, ilk_name, symbol, wallet_address, collateral_amount, loan_amount)​

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

پارامترها:

  • api (service.StableCoinSystemApi): نمونه کلاینت API
  • ilk_name (str): نام نوع وثیقه
  • symbol (str): نماد دارایی
  • wallet_address (str): آدرس کیف پول کاربر
  • collateral_amount (float): مقدار وثیقه
  • loan_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, vault_id)​

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

پارامترها:

  • tx: شیء تراکنش
  • tx_hash: هش تراکنش
  • vault_id: شناسه صندوق؛ می‌تواند None باشد

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

# 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 = service.ApiClient(cfg)
stable_coin_system_api = service.StableCoinSystemApi(api_client)

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

# Vault parameters
ILK_NAME = "ETHA"
SYMBOL = "ETH"
COLLATERAL_AMOUNT = 0.01
LOAN_AMOUNT = 1000

# Create vault
api_response = get_vault_tx_steps(
    stable_coin_system_api,
    ILK_NAME,
    SYMBOL,
    WALLET_ADDRESS,
    COLLATERAL_AMOUNT,
    LOAN_AMOUNT
)

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

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

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

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

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

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

    • منتظر تأیید تراکنش بمانید
    • جزئیات تراکنش را ثبت کنید
    • ساخته شدن صندوق را وارسی کنید

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

    • لاگ‌های تراکنش را بگیرید
    • شناسه صندوق را از آن بیرون بکشید
    • سوابق تراکنش را به‌روز کنید

مدیریت خطا​

try:
    # Vault creation 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

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

ثبت و نظارت​

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

  • زمان
  • جزئیات تراکنش
  • هش تراکنش
  • شناسه صندوق (در صورت وجود)

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

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

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

  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 ↩