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

ایجاد صندوق

نمای کلی​

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

پیش‌نیازها​

  • نصب Web3
  • نصب Zarban SDK
  • دسترسی به نود اتریوم (آدرس RPC)
  • کلید خصوصی با موجودی کافی

نصب​

pip install zarban

اجزای اصلی​

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

get_ilks_symbol(api)​

انواع وثیقه‌های موجود در سیستم را بازیابی می‌کند.

پارامترها:

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

خروجی:

  • list: نمادهای منحصر به فرد انواع وثیقه

مثال:

symbols = get_ilks_symbol(stable_coin_system_api)

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

to_native(api, symbol, amount)​

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

پارامترها:

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

خروجی:

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

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

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
configuration = Configuration(host="https://testapi.zarban.io")
api_client = ApiClient(configuration)
stable_coin_system_api = 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
num_of_steps, step_number, steps = get_vault_tx_steps(
  stable_coin_system_api,
  ILK_NAME,
  SYMBOL,
  WALLET_ADDRESS,
  COLLATERAL_AMOUNT,
  LOAN_AMOUNT
)

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

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

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

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

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

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

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

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

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

مدیریت خطا​

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

نکات مهم​

۱. امنیت

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

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

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

۳. مدیریت گس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"
}

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

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

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

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

  • ETH کافی برای هزینه‌های گس
  • وثیقه کافی برای ایجاد صندوق
  • دسترسی معتبر به API

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

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

عیب‌یابی​

۱. مشکلات اتصال

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

۲. شکست تراکنش‌ها

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

۳. خطاهای API

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

پشتیبانی​

برای پشتیبانی بیشتر یا گزارش اشکالات، لطفاً با تیم پشتیبانی زربان تماس بگیرید یا به مستندات API مراجعه کنید.

همچنین ببینید​

  1. gas↩