روابط التوقيع

يفتح رابط التوقيع معاملة Hive في Hivesigner. يراجعها المستخدم ويوافق عليها بمفتاحه هو ويبثّها Hivesigner من متصفحه. وبعدها يستطيع Hivesigner إعادة المستخدم إلى تطبيقك ومعه معرّف المعاملة. ولا تحتاج روابط التوقيع إلى حساب تطبيق ولا إلى رمز. وهي تغطي كل العمليات الـ 41 التي يدعمها Hivesigner، بما فيها التحويلات وغيرها من الإجراءات التي تحتاج المفتاح النشط.

كيف يعمل رابط التوقيع

1. يبني تطبيقك رابطًا يحمل عملية واحدة أو أكثر.
2. يفتح المستخدم الرابط. ويعرض Hivesigner كل عملية بكلمات واضحة على شاشة "تأكيد المعاملة"، مع المفتاح الذي تحتاجه.
3. يوافق المستخدم. ويوقّع Hivesigner المعاملة في المتصفح بمفتاح الحساب المحدد في Hivesigner. ثم يرسل المعاملة إلى شبكة Hive.
4. وعندما يسمّي الرابط عنوان استدعاء، يرسل Hivesigner المستخدم إليه ومعه معرّف المعاملة.

لا يرى تطبيقك أي مفتاح أبدًا. ويستطيع أي موقع إنشاء رابط توقيع: فلا يوجد client_id يُرسل.

أشكال الروابط

يقرأ Hivesigner نوعين من روابط التوقيع: الروابط المرمَّزة والروابط القديمة.

الروابط المرمَّزة

يحمل الرابط المرمَّز العمليات على هيئة JSON، مرمَّزة بـ base64url. ويستخدم صيغة hive://sign/... الخاصة بحزمة hive-uri، مع استبدال hive:// بـ https://hivesigner.com/.

B64U هو نص JSON، مرمَّزًا بـ UTF-8 ثم بـ base64 مع استبدال + بـ - و/ بـ _ وحشو = بـ ..

مع op وops، يبني Hivesigner المعاملة حول العمليات. فيملأ كتلة المرجع ووقت الانتهاء.

ومع tx، يحتفظ Hivesigner بقيم ref_block_num وref_block_prefix وexpiration الخاصة بالمعاملة. كما يحتفظ بالتوقيعات التي تحملها المعاملة بالفعل. وهذا يتيح لعدة حسابات توقيع معاملة واحدة بالتناوب، لحساب يتحكم به عدة أشخاص. ويرفض Hivesigner معاملة لا تكون قائمة extensions فيها فارغة.

ملاحظة: يوحّد Hivesigner بعض القيم قبل التوقيع، مثل المبالغ والحقول المتروكة على قيمها الافتراضية. وقد يصبح للمعاملة الموقّعة عندئذٍ معرّف مختلف عن الذي بنيته. اقرأ المعرّف من عنوان الاستدعاء.

الروابط القديمة

يسمّي الرابط القديم عملية واحدة في المسار ويضع حقولها في الاستعلام:

https://hivesigner.com/sign/vote?author=AUTHOR&permlink=PERMLINK&weight=10000
https://hivesigner.com/sign/transfer?to=RECIPIENT&amount=1.000%20HIVE&memo=MEMO
https://hivesigner.com/sign/transfer-to-vesting?amount=10.000%20HIVE

• اكتب اسم العملية بصيغة snake case (transfer_to_vesting) أو camel case (transferToVesting) أو kebab case (transfer-to-vesting).
• أعطِ كل حقل كمعامل استعلام باسم الحقل. ورمّز كل قيمة بترميز URL.
• اكتب القوائم والكائنات بصيغة JSON، مثل required_posting_auths=["alice"]. ويمكن أيضًا فصل قائمة المعرّفات أو الأسماء بفواصل: proposal_ids=379,380.
• اكتب القيم المنطقية true أو false.

يحمل الرابط القديم عملية واحدة. استخدم رابطًا مرمَّزًا لأكثر من واحدة.

قيم الحقول

تنطبق هذه القواعد على كل الأشكال:

• القيم الافتراضية. الحقل الذي تتركه يأخذ قيمته الافتراضية. والحساب الفاعل (voter وfrom وowner وما شابهها) يأخذ افتراضيًا الحساب الموقّع. وweight التصويت يأخذ افتراضيًا 10000 (100%).
• المبالغ رقم ورمز: 1.000 HIVE أو 0.500 HBD أو 100.000000 VESTS. ويكتب Hivesigner قيم HIVE وHBD بثلاث منازل عشرية وقيم VESTS بست.
• قوة HIVE. الحقل الذي يقبل VESTS يقبل أيضًا مبلغًا بـ HP، مثل 100 HP. ويحوّله Hivesigner إلى VESTS بالسعر الحالي قبل أن يتمكّن المستخدم من الموافقة.
• __signer في أي قيمة تصبح اسم الحساب الموقّع. فمثلًا يستطيع custom_json للمتابعة أن يسمّي __signer كمتابِع داخل json الخاص به.
• الأعداد الصحيحة يجب أن تكون أعدادًا صحيحة داخل المدى الذي تقبله السلسلة، مثل -10000 إلى 10000 لـ weight التصويت.

يرفض Hivesigner الرابط كله عندما لا تناسب قيمة حقلها، أو عندما تكون العملية غير معروفة، أو عندما لا يحمل الرابط أي عملية. ويرى المستخدم "عذرًا، حدث خطأ ما. البيانات المقدَّمة غير صالحة." ولا يُوقَّع شيء.

المعاملات

أضف هذه إلى سلسلة استعلام أي رابط توقيع:

استخدم عنوان استدعاء https://. ويتجاهل Hivesigner أي عنوان استدعاء ليس عنوان http أو https ويبقى عندئذٍ على شاشة النتيجة عنده.

يختار Hivesigner المفتاح من العمليات. ولا يوجد معامل لاختياره: فـ Hivesigner يتجاهل authority (ومعامل a في hive-uri) في روابط التوقيع. راجع أي مفتاح يحتاجه الرابط.

عناصر عنوان الاستدعاء

بعد موافقة المستخدم، يملأ Hivesigner هذه العناصر في عنوان الاستدعاء:

عنوان الاستدعاء الذي لا يحمل أيًّا من هذه العناصر يستلم معرّف المعاملة مضافًا باسم id، بعد ? أو &:

https://YOUR_APP/done           becomes  https://YOUR_APP/done?id=TRANSACTION_ID
https://YOUR_APP/done?step=2    becomes  https://YOUR_APP/done?step=2&id=TRANSACTION_ID
https://YOUR_APP/tx/{{id}}      becomes  https://YOUR_APP/tx/TRANSACTION_ID

يعيد Hivesigner التوجيه بمجرد أن تقبل عقدة Hive المعاملة. وقد لا تكون المعاملة في كتلة بعد. ابحث عنها بمعرّفها عندما تحتاج إلى التأكد من إدراجها.

ولا يُستدعى عنوانك عندما ترفض الشبكة المعاملة (يرى المستخدم الخطأ) ولا عندما يغادر المستخدم دون موافقة.

ابنِ رابطًا

باستخدام hive-uri

ترمّز حزمة hive-uri (https://www.npmjs.com/package/hive-uri) العمليات إلى روابط. استخدم الإصدار 0.2.8 أو أحدث، فهو يرمّز أي نص Unicode ترميزًا صحيحًا.

npm install hive-uri

import { encodeOp, encodeOps } from 'hive-uri';

// One vote. __signer becomes the account that signs.
const vote = encodeOp(
  ['vote', { voter: '__signer', author: 'AUTHOR', permlink: 'PERMLINK', weight: 10000 }],
  { callback: 'https://YOUR_APP/voted?tx={{id}}' },
);

// Two transfers in one transaction.
const payout = encodeOps(
  [
    ['transfer', { from: '__signer', to: 'RECIPIENT_1', amount: '1.000 HIVE', memo: 'MEMO' }],
    ['transfer', { from: '__signer', to: 'RECIPIENT_2', amount: '2.000 HIVE', memo: 'MEMO' }],
  ],
  { callback: 'https://YOUR_APP/paid' },
);

const voteLink = vote.replace('hive://', 'https://hivesigner.com/');
const payoutLink = payout.replace('hive://', 'https://hivesigner.com/');

يأخذ كائن الخيارات callback (يُكتب cb) وno_broadcast: true (يُكتب nb) وsigner (يُكتب s). وتفعل encodeTx الشيء نفسه لمعاملة كاملة.

باستخدام حزمة JavaScript SDK

تحتوي حزمة hivesigner على sendOperation وsendOperations وsendTransaction. وهي تأخذ الوسائط نفسها التي تأخذها مرمّزات hive-uri وتعيد رابط https://hivesigner.com/sign/...:

import { sendOperation } from 'hivesigner';

const link = sendOperation(
  ['transfer', { from: '__signer', to: 'RECIPIENT', amount: '1.000 HIVE', memo: 'MEMO' }],
  { callback: 'https://YOUR_APP/paid' },
);

في TypeScript تشترط الأنواع الوسيط الثالث: مرّر undefined لتستعيد الرابط. وفي المتصفح، تجعلها دالة تُمرَّر كوسيط ثالث تفتح الرابط في تبويب جديد بدل إعادته. راجع حزم التطوير.

دون شيفرة

يسرد https://hivesigner.com/signs ("توقيع معاملة") كل عملية مدعومة مع نموذج لحقولها. فيبني رابط /sign/op/ ويفتحه.

أي مفتاح يحتاجه الرابط

تحتاج كل عملية مفتاحًا واحدًا: مفتاح النشر أو المفتاح النشط أو مفتاح المالك. والجدول أدناه يسردها. وثلاث عمليات تعتمد على قيمها:

• custom_json تحتاج المفتاح النشط عندما يسمّي required_auths حسابًا. وإلا فهي تحتاج مفتاح النشر.
• account_update تحتاج مفتاح المالك عندما تضبط owner. وإلا فهي تحتاج المفتاح النشط.
• account_update2 تحتاج مفتاح المالك عندما تضبط owner. وتحتاج المفتاح النشط عندما تضبط active أو posting أو memo_key أو json_metadata. ومع posting_json_metadata وحدها، تحتاج مفتاح النشر.

يوقّع Hivesigner الرابط بمفتاح واحد، ولذلك يجب أن تحتاج كل العمليات في رابط واحد المفتاح نفسه. ويرفض Hivesigner توقيع رابط يخلط بينها ويخبر المستخدم بالسبب. أرسل تلك العمليات في روابط منفصلة.

وعندما لا يحمل الحساب المحدد المفتاح على الجهاز، يقول Hivesigner أي مفتاح ينقص ويعرض إضافته. راجع عندما ينقص المفتاح.

ما يراه المستخدم

• شاشة عنوانها "تأكيد المعاملة"، فيها بطاقة لكل عملية: ملخّص بكلمات واضحة، والمفتاح الذي تحتاجه، والقيم التي تحملها.
• "ستتم إعادة توجيهك إلى HOST." عندما يحمل الرابط عنوان استدعاء. استخدم عنوان استدعاء على موقعك أنت، ليتعرّف المستخدمون على المضيف.
• تحذير عندما تتصرف عملية باسم حساب غير الحساب الموقّع.
• موافقة، أو توقيع لرابط التوقيع فقط. والحساب المقفل يطلب رمز المرور أولًا.
• بعد البثّ، "تم بث المعاملة بنجاح" مع معرّف المعاملة. ثم إعادة التوجيه إلى عنوان الاستدعاء الخاص بك.

المراجعة والتوقيع تصف الشاشة للمستخدمين.

العمليات المدعومة

يوقّع Hivesigner هذه العمليات الـ 41، بأسمائها على السلسلة. وأي عملية غيرها تُرفض. والاسم هو الذي يعرضه Hivesigner على شاشة التأكيد.