Liens de signature

Un lien de signature ouvre une transaction Hive dans Hivesigner. La personne l’examine, l’approuve avec sa propre clé et Hivesigner la diffuse depuis son navigateur. Hivesigner peut ensuite renvoyer la personne vers votre application avec l’identifiant de la transaction. Les liens de signature ne nécessitent ni compte d’application ni jeton. Ils couvrent les 41 opérations que Hivesigner prend en charge, y compris les transferts et les autres actions qui nécessitent la clé active.

Comment fonctionne un lien de signature

1. Votre application construit un lien qui porte une ou plusieurs opérations.
2. La personne ouvre le lien. Hivesigner affiche chaque opération en mots clairs sur l’écran « Confirmer la transaction », avec la clé qu’elle nécessite.
3. La personne approuve. Hivesigner signe la transaction dans le navigateur avec la clé du compte sélectionné dans Hivesigner. Puis il envoie la transaction au réseau Hive.
4. Quand le lien nomme une URL de rappel, Hivesigner y envoie la personne avec l’identifiant de la transaction.

Votre application ne voit jamais de clé. N’importe quel site peut créer un lien de signature : il n’y a aucun client_id à envoyer.

Formes de liens

Hivesigner lit deux sortes de liens de signature : les liens encodés et les liens historiques.

Liens encodés

Un lien encodé porte les opérations en JSON, encodé en base64url. Il utilise le format hive://sign/... du paquet hive-uri, avec https://hivesigner.com/ à la place de hive://.

B64U est le texte JSON, encodé en UTF-8, puis en base64 avec - à la place de +, _ à la place de / et . à la place du remplissage =.

Pour op et ops, Hivesigner construit la transaction autour des opérations. Il remplit le bloc de référence et l’expiration.

Pour tx, Hivesigner conserve les ref_block_num, ref_block_prefix et expiration propres à la transaction. Il conserve aussi les signatures que la transaction porte déjà. Cela permet à plusieurs comptes de signer une même transaction à tour de rôle, pour un compte que plusieurs personnes contrôlent. Hivesigner refuse une transaction dont la liste extensions n’est pas vide.

Remarque : Hivesigner normalise certaines valeurs avant de signer, comme les montants et les champs laissés à leur valeur par défaut. La transaction signée peut alors avoir un identifiant différent de celui que vous avez construit. Lisez l’identifiant depuis l’URL de rappel.

Liens historiques

Un lien historique nomme une opération dans le chemin et met ses champs dans la requête :

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

• Écrivez le nom de l’opération en snake case (transfer_to_vesting), camel case (transferToVesting) ou kebab case (transfer-to-vesting).
• Donnez chaque champ comme paramètre de requête portant le nom du champ. Encodez chaque valeur pour une URL.
• Écrivez les listes et les objets en JSON, par exemple required_posting_auths=["alice"]. Une liste d’identifiants ou de noms peut aussi être séparée par des virgules : proposal_ids=379,380.
• Écrivez les booléens true ou false.

Un lien historique porte une seule opération. Pour plus d’une, utilisez un lien encodé.

Valeurs des champs

Ces règles valent pour toutes les formes :

• Valeurs par défaut. Un champ que vous omettez prend sa valeur par défaut. Le compte qui agit (voter, from, owner et les champs semblables) vaut par défaut le compte qui signe. Le weight d’un vote vaut par défaut 10000 (100%).
• Les montants sont un nombre et un symbole : 1.000 HIVE, 0.500 HBD ou 100.000000 VESTS. Hivesigner écrit HIVE et HBD avec 3 décimales et VESTS avec 6.
• Hive Power. Un champ qui accepte des VESTS accepte aussi un montant en HP, comme 100 HP. Hivesigner le convertit en VESTS au taux du moment avant que la personne puisse approuver.
• __signer dans n’importe quelle valeur devient le nom du compte qui signe. Par exemple un custom_json d’abonnement peut nommer __signer comme abonné dans son json.
• Les entiers doivent être des nombres entiers dans la plage que la blockchain accepte, comme -10000 à 10000 pour le weight d’un vote.

Hivesigner refuse le lien entier quand une valeur ne convient pas à son champ, quand une opération est inconnue ou quand le lien ne porte aucune opération. La personne voit « Oups, une erreur s’est produite. Les données fournies ne sont pas valides. » et rien n’est signé.

Paramètres

Ajoutez-les à la chaîne de requête de n’importe quel lien de signature :

Utilisez une URL de rappel en https://. Hivesigner ignore une URL de rappel qui n’est pas une URL http ou https et reste alors sur son propre écran de résultat.

Hivesigner choisit la clé d’après les opérations. Il n’y a aucun paramètre pour la choisir : Hivesigner ignore authority (et le paramètre a de hive-uri) sur les liens de signature. Voir Quelle clé nécessite un lien.

Jetons de remplacement de l’URL de rappel

Après l’approbation de la personne, Hivesigner remplit ces jetons de remplacement dans l’URL de rappel :

Une URL de rappel sans aucun de ces jetons reçoit l’identifiant de la transaction ajouté comme id, après ? ou & :

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 redirige dès qu’un nœud Hive accepte la transaction. Celle-ci n’est peut-être pas encore dans un bloc. Recherchez-la par son identifiant quand vous devez savoir qu’elle a bien été incluse.

Votre URL de rappel n’est pas appelée quand le réseau rejette la transaction (la personne voit l’erreur) ni quand la personne part sans approuver.

Construire un lien

Avec hive-uri

Le paquet hive-uri (https://www.npmjs.com/package/hive-uri) encode des opérations en liens. Utilisez la version 0.2.8 ou plus récente, qui encode correctement tout texte 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/');

L’objet d’options accepte callback (écrit cb), no_broadcast: true (écrit nb) et signer (écrit s). encodeTx fait la même chose pour une transaction entière.

Avec le SDK JavaScript

Le paquet hivesigner propose sendOperation, sendOperations et sendTransaction. Ils prennent les mêmes arguments que les encodeurs de hive-uri et renvoient le lien 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' },
);

En TypeScript, les types exigent le troisième argument : passez undefined pour récupérer le lien. Dans un navigateur, une fonction passée en troisième argument leur fait ouvrir le lien dans un nouvel onglet au lieu de le renvoyer. Voir SDK.

Sans code

https://hivesigner.com/signs (« Signer une transaction ») liste chaque opération prise en charge avec un formulaire pour ses champs. Il construit un lien /sign/op/ et l’ouvre.

Quelle clé nécessite un lien

Chaque opération nécessite une clé : publication, active ou propriétaire. Le tableau ci-dessous les liste. Trois opérations dépendent de leurs valeurs :

• custom_json nécessite la clé active quand required_auths nomme un compte. Sinon elle nécessite la clé de publication.
• account_update nécessite la clé propriétaire quand elle définit owner. Sinon elle nécessite la clé active.
• account_update2 nécessite la clé propriétaire quand elle définit owner. Elle nécessite la clé active quand elle définit active, posting, memo_key ou json_metadata. Avec seulement posting_json_metadata, elle nécessite la clé de publication.

Hivesigner signe un lien avec une seule clé, toutes les opérations d’un même lien doivent donc nécessiter la même. Hivesigner refuse de signer un lien qui les mélange et en explique la raison à la personne. Envoyez de telles opérations dans des liens distincts.

Quand le compte sélectionné n’a pas la clé sur l’appareil, Hivesigner dit quelle clé manque et propose de l’ajouter. Voir Quand la clé manque.

Ce que voit la personne

• Un écran intitulé « Confirmer la transaction », avec une carte par opération : un résumé en mots clairs, la clé qu’elle nécessite et les valeurs qu’elle porte.
• « Vous allez être redirigé vers HOST. » quand le lien a une URL de rappel. Utilisez une URL de rappel sur votre propre site, pour que les gens reconnaissent l’hôte.
• Un avertissement quand une opération agit en tant qu’un compte autre que celui qui signe.
• Approuver, ou Signer pour un lien de signature seule. Un compte verrouillé demande d’abord son code d’accès.
• Après une diffusion, « Transaction diffusée avec succès » avec l’identifiant de la transaction. Puis la redirection vers votre URL de rappel.

Examiner et signer décrit l’écran pour les utilisateurs.

Opérations prises en charge

Hivesigner signe ces 41 opérations, sous leurs noms sur la blockchain. Tout le reste est refusé. Le nom est celui que Hivesigner affiche sur l’écran de confirmation.