سرویس کیف پول دارانو

معرفی

سرویس کیف پول یکی از اصلی‌ترین بخش‌های سیستم دارانو است که مسئول مدیریت دارایی‌های دیجیتال کاربران، تولید و نگهداری کلیدهای رمزنگاری، و تعامل با بلاکچین می‌باشد.

معماری کیف پول

HD Wallet (Hierarchical Deterministic Wallet)

سیستم دارانو از معماری HD Wallet برای مدیریت کلیدهای کاربران استفاده می‌کند:

• کلید مادر (Master Key): یک کلید اصلی که به صورت امن در سیستم نگهداری می‌شود
• کلیدهای فرزند: برای هر کاربر بر اساس کد ملی، یک کلید فرزند منحصر به فرد تولید می‌شود
• مزایا:
• امکان بازیابی تمام کلیدها از روی یک کلید مادر
• امنیت بالا
• عدم نیاز به ذخیره‌سازی کلیدهای خصوصی برای هر کاربر
• تولید کلیدهای قابل پیش‌بینی و قابل بازسازی

استفاده از BIP32

استاندارد BIP32 برای تولید کلیدهای سلسله‌مراتبی استفاده می‌شود:

1. خواندن کلید مادر از فضای امن
2. تبدیل کد ملی کاربر به ایندکس منحصر به فرد
3. تولید کلید فرزند بر اساس ایندکس
4. ایجاد هش SHA-256 از کلید تولید شده
5. تولید کلید عمومی Stellar از روی هش

عملکردهای اصلی

1. ایجاد کیف پول

زمان ایجاد: هنگام ثبت‌نام یا اولین ورود کاربر

فرآیند:

1. بررسی وجود کیف پول برای کاربر
2. در صورت عدم وجود:
3. دریافت کد ملی کاربر
4. تولید کلید عمومی از طریق HD Wallet
5. ایجاد آدرس کیف پول در بلاکچین Stellar
6. ذخیره کلید عمومی در پایگاه داده
7. فعال‌سازی کیف پول

اطلاعات ذخیره‌شده: - کلید عمومی (Public Key) - آدرس کیف پول - تاریخ ایجاد - وضعیت کیف پول (فعال/غیرفعال)

2. خط اعتماد (Trust Line)

قبل از اینکه کاربر بتواند توکنی را دریافت کند، باید خط اعتماد آن توکن را ایجاد کند.

چیستی خط اعتماد: - مکانیزمی برای قبول دریافت یک نوع توکن خاص - نوعی قرارداد بین کاربر و ناشر توکن - محدودیت حداکثر موجودی قابل نگهداری

مراحل ایجاد خط اعتماد:

1. کاربر توکن مورد نظر را انتخاب می‌کند
2. قوانین و شرایط توکن نمایش داده می‌شود
3. کاربر قوانین را می‌پذیرد
4. تراکنش خط اعتماد در بلاکچین ثبت می‌شود
5. کاربر آماده دریافت توکن است

پارامترهای خط اعتماد: - نوع توکن (Asset Code) - ناشر توکن (Issuer) - حداکثر موجودی قابل نگهداری (Limit)

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

ارسال توکن

ورودی‌ها: - آدرس کیف پول مقصد - نوع توکن - مقدار توکن - یادداشت (اختیاری)

فرآیند:

1. بررسی موجودی کافی
2. بررسی صحت آدرس مقصد
3. بررسی وجود خط اعتماد در کیف پول مقصد
4. ایجاد تراکنش در بلاکچین
5. امضای تراکنش با کلید خصوصی
6. ارسال به شبکه Stellar
7. پیگیری تایید تراکنش
8. به‌روزرسانی موجودی

دریافت توکن

فرآیند:

1. پیگیری تراکنش‌های ورودی به آدرس کیف پول
2. تایید تراکنش در بلاکچین
3. بررسی نوع و مقدار توکن
4. به‌روزرسانی موجودی کاربر
5. ارسال اعلان به کاربر

4. نمایش موجودی

کاربران می‌توانند موجودی کیف پول خود را مشاهده کنند:

اطلاعات نمایش داده‌شده: - لیست تمام توکن‌های موجود - مقدار هر توکن - ارزش ریالی (در صورت وجود قیمت) - تراکنش‌های اخیر - توکن‌های قفل‌شده (در حال اقساط یا تعهد)

5. تاریخچه تراکنش‌ها

اطلاعات تراکنش: - نوع تراکنش (ارسال/دریافت) - مقدار - نوع توکن - آدرس مقصد/مبدا - تاریخ و زمان - وضعیت (موفق/ناموفق/در انتظار) - هش تراکنش (Transaction Hash) - کارمزد شبکه

امنیت کیف پول

حفاظت از کلیدهای خصوصی

• عدم ذخیره‌سازی مستقیم: کلیدهای خصوصی هرگز در پایگاه داده ذخیره نمی‌شوند
• تولید پویا: کلیدهای خصوصی هنگام نیاز از کلید مادر تولید می‌شوند
• محیط ایزوله: عملیات امضا در محیط امن و ایزوله انجام می‌شود
• HSM (اختیاری): امکان استفاده از ماژول امنیتی سخت‌افزاری برای کلید مادر

احراز هویت دو مرحله‌ای (2FA)

برای عملیات حساس: - برداشت توکن به کیف خارجی - تغییر تنظیمات امنیتی - برداشت مبالغ بالا

محدودیت‌های امنیتی

• محدودیت برداشت روزانه: بر اساس سطح احراز هویت کاربر
• آدرس‌های سفید (Whitelist): امکان تعریف آدرس‌های مورد اعتماد
• قفل زمانی: امکان قفل موقت کیف پول
• اعلان‌های امنیتی: اطلاع‌رسانی فوری برای تمام تراکنش‌ها

تعامل با بلاکچین Stellar

چرا Stellar؟

• سرعت بالای تراکنش‌ها (3-5 ثانیه)
• کارمزد بسیار پایین
• پشتیبانی از توکن‌های سفارشی
• قابلیت اعتماد و مقیاس‌پذیری

عملیات بلاکچین

ایجاد حساب

فرآیند ایجاد حساب جدید در Stellar:
1. تولید جفت کلید (Public/Private)
2. فعال‌سازی حساب با حداقل موجودی (1 XLM)
3. تنظیم امضاکنندگان (Signers)
4. پیکربندی تنظیمات حساب

ارسال تراکنش

ساختار تراکنش Stellar:
- Source Account: حساب فرستنده
- Sequence Number: شماره ترتیبی تراکنش
- Operations: عملیات‌های درخواستی
  - Payment: انتقال دارایی
  - Create Trust Line: ایجاد خط اعتماد
  - Manage Offer: مدیریت سفارش‌ها
- Fee: کارمزد تراکنش
- Memo: یادداشت (اختیاری)
- Signatures: امضاهای لازم

پیگیری وضعیت شبکه

• مانیتورینگ وضعیت Horizon Server
• بررسی وضعیت تراکنش‌ها
• دریافت اطلاعات لحظه‌ای بلاکچین

API های کیف پول

متدهای اصلی

1. GetPublicKeyByNationalID

توضیح: دریافت کلید عمومی بر اساس کد ملی

ورودی:

{
  "nationalId": "1234567890"
}

خروجی:

{
  "publicKey": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "address": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "isActive": true
}

2. CreateTrustLine

توضیح: ایجاد خط اعتماد برای یک توکن

ورودی:

{
  "userId": "user_id",
  "assetCode": "ANDISHE",
  "assetIssuer": "GXXXXXXXXXX",
  "limit": "1000000"
}

خروجی:

{
  "success": true,
  "transactionHash": "abc123...",
  "trustLineId": "tl_12345"
}

3. SendPayment

توضیح: ارسال توکن به آدرس مقصد

ورودی:

{
  "fromUserId": "user_id",
  "toAddress": "GYYYYYYYYYYYYYY",
  "assetCode": "ANDISHE",
  "amount": "100",
  "memo": "پرداخت"
}

خروجی:

{
  "success": true,
  "transactionHash": "def456...",
  "fee": "0.00001",
  "timestamp": "2025-12-08T10:30:00Z"
}

4. GetBalance

توضیح: دریافت موجودی کیف پول

ورودی:

{
  "userId": "user_id"
}

خروجی:

{
  "balances": [
    {
      "assetCode": "ANDISHE",
      "balance": "500.0000000",
      "locked": "100.0000000",
      "available": "400.0000000"
    },
    {
      "assetCode": "XLM",
      "balance": "10.0000000"
    }
  ]
}

5. GetTransactionHistory

توضیح: دریافت تاریخچه تراکنش‌ها

ورودی:

{
  "userId": "user_id",
  "limit": 50,
  "offset": 0,
  "assetCode": "ANDISHE" // اختیاری
}

خروجی:

{
  "transactions": [
    {
      "id": "tx_12345",
      "type": "payment",
      "direction": "outgoing",
      "amount": "100",
      "assetCode": "ANDISHE",
      "fromAddress": "GXXX...",
      "toAddress": "GYYY...",
      "timestamp": "2025-12-08T10:30:00Z",
      "status": "success",
      "hash": "abc123..."
    }
  ],
  "total": 150,
  "hasMore": true
}

مدیریت خطاها

انواع خطاها

کد خطا	پیام	توضیح
WALLET_NOT_FOUND	کیف پول یافت نشد	کیف پول برای این کاربر وجود ندارد
INSUFFICIENT_BALANCE	موجودی ناکافی	موجودی کافی برای انجام تراکنش نیست
INVALID_ADDRESS	آدرس نامعتبر	آدرس مقصد صحیح نیست
TRUSTLINE_NOT_FOUND	خط اعتماد یافت نشد	کاربر خط اعتماد این توکن را ایجاد نکرده
TRANSACTION_FAILED	تراکنش ناموفق	تراکنش در بلاکچین ناموفق بود
DAILY_LIMIT_EXCEEDED	محدودیت روزانه	از محدودیت برداشت روزانه تجاوز شده
NETWORK_ERROR	خطای شبکه	خطا در ارتباط با بلاکچین

نظارت و گزارش‌دهی

متریک‌های مهم

• تعداد کیف پول‌های فعال
• تعداد تراکنش‌های روزانه
• حجم معاملات
• میانگین زمان تایید تراکنش
• نرخ موفقیت تراکنش‌ها
• کارمزدهای پرداختی به شبکه

لاگ‌ها

تمام عملیات مهم لاگ می‌شوند: - ایجاد کیف پول جدید - تراکنش‌های ارسالی و دریافتی - ایجاد خط اعتماد - خطاها و استثناها - تلاش‌های ناموفق

بهینه‌سازی و عملکرد

کش کردن داده‌ها

• موجودی کاربران
• اطلاعات توکن‌ها
• تاریخچه اخیر تراکنش‌ها

صف پردازش (Queue)

برای مدیریت بهتر تراکنش‌های پرتعداد: - صف تراکنش‌های در انتظار - پردازش مجموعه‌ای (Batch Processing) - اولویت‌بندی تراکنش‌ها

پیوندهای مرتبط

• سرویس احراز هویت
• سرویس‌های مالی
• بازار ثانویه
• دیاگرام‌های سیستم