Ссылки подписи

Ссылка подписи открывает транзакцию 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 транзакции. Он сохраняет и подписи, которые уже есть в транзакции. Благодаря этому несколько аккаунтов могут по очереди подписать одну транзакцию — для аккаунта, которым управляют несколько человек. Транзакцию, у которой список extensions не пуст, Hivesigner отклоняет.

Примечание: Перед подписью 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).
• Каждое поле передавайте параметром запроса с именем этого поля. Кодируйте каждое значение для адреса.
• Списки и объекты записывайте в 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 с 3 знаками после запятой, а VESTS с 6.
• Hive Power. Поле, которое принимает VESTS, принимает и сумму в HP, например 100 HP. Hivesigner переводит её в VESTS по текущему курсу, прежде чем человек сможет одобрить.
• __signer в любом значении превращается в имя аккаунта, который подписывает. Например, custom_json для подписки может назвать __signer подписчиком внутри своего json.
• Целые числа должны быть целыми и лежать в диапазоне, который принимает сеть, например от -10000 до 10000 для weight голоса.

Hivesigner отклоняет всю ссылку, когда значение не подходит своему полю, когда операция неизвестна или когда в ссылке нет ни одной операции. Человек видит «Упс, что-то пошло не так. Переданные данные некорректны.», и ничего не подписывается.

Параметры

Добавляйте их в строку запроса любой ссылки подписи:

Используйте адрес возврата на https://. Адрес, который не является http или https, Hivesigner не учитывает и остаётся на собственном экране результата.

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.

С помощью SDK для JavaScript

В пакете 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, чтобы получить ссылку. В браузере функция, переданная третьим аргументом, заставляет их открыть ссылку в новой вкладке вместо возврата. Смотрите SDK.

Без кода

Страница 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 показывает на экране подтверждения.