مرجع RPC API

واجهة HTTP التي تقدّمها العقدة للمحافظ: أربع نقاط نهاية، وJSON للحالة والأخطاء، وترميز ثنائي مضغوط للكتل والدفعات.

عنوان العقدة العامة للاختبار الأساسي هو https://node.tint.top. لا ترى الواجهة أبدًا مفتاحًا ولا مبلغًا: ترسل المحفظة دفعات جاهزة وتقرأ كتلًا كاملة تفكّ تشفيرها بنفسها.

نقاط النهاية

الطريقة والمسار	يجيب بـ
`GET /v1/status`	أين وصلت السلسلة، بصيغة JSON.
`GET /v1/blocks/{height}`	كتلة نهائية واحدة، بترميز الأسلاك (wire encoding).
`GET /v1/blocks?from=N`	الكتل التي فيها دفعات من الارتفاع N فصاعدًا، كدفعة كتل (block batch).
`POST /v1/transactions`	يستلم دفعة بترميز الأسلاك؛ ويجيب بمعرّفها بصيغة JSON.

GET /v1/status

طلب

curl -s https://node.tint.top/v1/status

استجابة (قيم توضيحية)

{
  "chain_id": 6073471695170043905,
  "height": 128431,
  "tip": "9f3c…e21a",
  "genesis": "04b7…c9d0",
  "queued": 0,
  "pools": [
    { "asset": 1, "native": 20000000000000, "other": 10000000000000, "fee_bps": 30 }
  ]
}

الحقل	المعنى
`chain_id`	معرّف الشبكة، مربوط في كل توقيع وكل تجزئة كتلة.
`height`	ارتفاع آخر كتلة نهائية.
`tip`	تجزئة آخر كتلة نهائية، بالنظام الست عشري.
`genesis`	تجزئة الكتلة الأولى، بالنظام الست عشري. قد تتشارك شبكتا اختبار `chain_id` نفسه؛ وهذا يميّز بينهما.
`queued`	الدفعات المنتظرة كتلة.
`pools[].asset`	العملة التي يبادلها المجمّع بالعملة الأصلية (1 هي `TUSD`).
`pools[].native`, `pools[].other`	ما يحتفظ به المجمّع، بالوحدات (1 عملة = 100,000,000 وحدة)، حتى آخر كتلة نهائية.
`pools[].fee_bps`	رسوم المجمّع بأجزاء من عشرة آلاف؛ 30 تعني 0.3%.

GET /v1/blocks/{height}

يعيد كتلة نهائية واحدة بصيغة application/octet-stream. الكتلة النهائية لا تتغير أبدًا، لذا تحمل الاستجابة Cache-Control: public, max-age=31536000, immutable. الارتفاع غير الرقمي يُجاب عنه بـ invalid_height، والمجهول بـ not_found.

GET /v1/blocks?from=N

يعيد الكتل التي تحتوي على دفعات من الارتفاع N فصاعدًا، كدفعة كتل واحدة (application/octet-stream)، مع آخر ارتفاع تحسبه الإجابة (through). المحفظة التي تلحق بالسلسلة تسأل مجددًا من الارتفاع الذي يلي through. تكبر الإجابة مع السلسلة، لذا تُرسل مع Cache-Control: no-store. يجب أن يكون from عددًا صحيحًا.

POST /v1/transactions

أرسل دفعة جاهزة بترميز الأسلاك كجسم للطلب. تبنيها المحفظة؛ والصيغة معرّفة في وحدة wire.rs من tint-core: حقول بعرض ثابت، وترميز صالح واحد لكل قيمة، دون بايتات زائدة في النهاية.

طلب

curl -s -X POST https://node.tint.top/v1/transactions \
  -H 'content-type: application/octet-stream' \
  --data-binary @payment.bin

استجابة

{ "txid": "5be1…07af" }

تبدأ المعاملة بالأصل (u32) وارتفاع الانتهاء (u64) والنوع (0 للدفعة، 1 للمبادلة)، يليها حزمة: أعلام، وميزان قيمة، ومرساة (anchor)، وعدد الإجراءات، والإجراءات مع إثباتها. وتضيف المبادلة العملة المشتراة والمبلغ المدفوع وحزمة ثانية.

الأخطاء

الأخطاء بصيغة JSON: {"error":{"code":"...","message":"..."}}.

HTTP	code	المعنى
400	`malformed`	الجسم ليس دفعة.
400	`invalid_height`	الارتفاع أو `from` ليس عددًا صحيحًا.
404	`not_found`	لا توجد كتلة نهائية عند هذا الارتفاع، أو لا يوجد مورد كهذا.
409	`double_spend`	إحدى ملاحظات هذه الدفعة أُنفقت بالفعل.
409	`conflict`	دفعة منتظرة أخرى تنفق إحدى الملاحظات نفسها.
409	`price_moved`	لم يعد المجمّع يعطي ما تطلبه هذه المبادلة.
413	`too_large`	الدفعة أكبر مما تسمح به السلسلة.
422	`rejected`	الدفعة تخرق قاعدة من قواعد السلسلة؛ والرسالة تذكر أيها.
429	`rate_limited`	استنفد عنوان هذا العميل ميزانية طلباته. أعد المحاولة بعد المدة في ترويسة `Retry-After`.
500	`internal`	تعذّر على العقدة الفحص أو الترميز.
503	`busy`, `queue_full`	العقدة تتحقق من دفعات أخرى، أو طابورها ممتلئ. حاول مجددًا؛ `Retry-After: 1`.

حدود المعدّل

افتراضيًا يحق لكل عنوان عميل إجراء 50 طلبًا في الثانية بشكل مستمر، مع دفعة اندفاع قدرها 100، ولا يُتحقق في آن واحد من أكثر من 4 دفعات عبر جميع العملاء. يمكن للمشغّلين تغيير الحدّين. خلف وكيل عكسي تعدّ العقدة العملاء بحسب آخر عنوان كتبه الوكيل في X-Forwarded-For؛ ولا تصدّق الإدخالات السابقة.

مثال: تتبّع السلسلة

python (من جهة الخادم)

import json, time, urllib.request

BASE = "https://node.tint.top"

while True:
    with urllib.request.urlopen(f"{BASE}/v1/status", timeout=10) as r:
        status = json.load(r)
    print(status["height"], status["queued"])
    time.sleep(5)

ما يستطيع مشغّل العقدة أن يعرفه من هذه الواجهة هو عنوان الشبكة الذي أتت منه الدفعة. أما المبالغ والمرسلون والمستلمون فهي داخل الإثبات والملاحظات المشفّرة.