diff --git a/source/guides/transfer/index.rst b/source/guides/transfer/index.rst index 243c68c7c..3aec27693 100644 --- a/source/guides/transfer/index.rst +++ b/source/guides/transfer/index.rst @@ -9,3 +9,4 @@ Guides related to :doc:`transfer transactions <../../concepts/transfer-transacti sending-a-transfer-transaction sending-an-encrypted-message + signing-transaction-offline diff --git a/source/guides/transfer/signing-transaction-offline.rst b/source/guides/transfer/signing-transaction-offline.rst new file mode 100644 index 000000000..4dba4bf48 --- /dev/null +++ b/source/guides/transfer/signing-transaction-offline.rst @@ -0,0 +1,127 @@ +.. post:: 8 Jun, 2020 + :category: Transfer Transaction + :tags: SDK, CLI + :excerpt: 1 + :nocomments: + +############################# +Signing a transaction offline +############################# + +This guide will show you how to sign a transaction offline then use an online computer to announce the transaction. + +This can be useful for when you are keeping your private keys in an offline device (cold wallet) for security reasons. By signing a transaction offline, you will be able to execute transactions from your cold wallet while keeping your private keys completely safe. + +The example in the guide will send 155 |networkcurrency| from your offline wallet to Bob (``TCHS3AOXFGWGTN2QUUHDCXJ4SBYLIQIPNUPHHA2N``) + +************* +Prerequisites +************* + +- Create a new :ref:`account `. +- Load the account with enough |networkcurrency| to pay for transaction fees. +- Both your offline and online :doc:`workstations <../../getting-started/setup-workstation.rst>` are set up for Symbol-CLI and Symbol-SDK. +- You installed the `Symbol URI scheme `_. + +********************************* +Step 1: Create an offline account +********************************* + +.. note:: This step is only necessary if you don't already have an offline account. + +On your offline workstation, open up your terminal and type: + +.. code-block:: bash + + symbol-cli account generate --network TEST_NET --generation-hash 4009619EB7A9F824C5D0EE0E164E0F99CCD7906A475D7768FD60B452204BD0A2 --namespace-id symbol.xym --divisibility 6 --url http://api-01-ap-northeast-1 + +But replace the "generation hash" and node "url" to match the information on your CLI. + +.. note:: To figure out the node information, pass `symbol-cli node info` + +Select to save the account, by either the Private Key or Mnemonic Phrase. Enter the desired wallet profile name and password. +If successful, the CLI should return the information of the created account. + +.. figure:: ../../resources/images/screenshots/offline-transaction-account-create.png + :align: center + :width: 800px + +.. note:: Remember to transfer some XYM tokens into this account before you continue with the guide. + +*************************************************** +Step 2: Set up a transaction through the symbol-cli +*************************************************** + +On your offline workstation, open up your terminal and type: + +.. code-block:: bash + + symbol-cli transaction transfer + +Enter your wallet password and the details of your transfer transaction. + +Once you have entered this information, the CLI will return the transaction information and ask you if you wish to announce the transaction. Type ``n`` for "no". + +Here, you have already successfully signed the transaction offline. Save the signed transaction payload provided by the CLI. + +.. figure:: ../../resources/images/screenshots/offline-transaction-set-up.png + :align: center + :width: 800px + +***************************************************** +Step 3: Set up to convert the transaction into an URI +***************************************************** + +Open a text editor and set up the following typescript file to generate a URI: + +.. example-code:: + + .. viewsource:: ../../resources/examples/typescript/transfer/SigningATransactionOffline.ts + :language: typescript + :start-after: /* start block 01 */ + :end-before: /* end block 01 */ + +Make sure you replace the transaction payload provided in the example with your own from step 2. + +Save the typescript file. + +*********************************** +Step 4: Obtain your transaction URI +*********************************** + +Run the file from step 2 in your terminal. + +.. code-block:: bash + + tsc transaction-uri.ts + node transaction-uri.js + +When executed successfully, your terminal should return the URI of your transaction. + +.. code-block:: bash + + web+symbol://transaction?data=BC00000000000000E103B81AF5C9B507AEA2D9F72A5F34C24174C57A36C6E118D520FF2B12E681C3C7B90E7EB37F06CE313466EF96A850E7845ECBF84FCD48D0DEB22A618FE7750BC0D6111B2AC378C69A4C71D013D3C4A748BE4EE48635EB79FC3B4696157BF6320000000001985441A0860100000000007044243C04000000988F2D81D729AC69B750A50E315D3C9070B4410F6D1E73834D010C0000000000EEAFF441BA994BE7C0D454070000000000496D2074686520626F7373&generationHash=test&nodeUrl=http://localhost:3000&webhookUrl=http://myapp.local/id + +Save the URI of your transaction. + +********************************************** +Step 5: Announce the transaction using the URI +********************************************** + +Move to your online workstation. + +Navigate to announce the transaction in the Symbol-CLI. + +.. code-block:: bash + + symbol-cli transaction uri + +After you enter your wallet password, enter the transaction URI obtained from step 3. + +Announce the transaction by typing ``Y`` for "Yes". + +If successful, the terminal should return: ``SUCCESS Transaction announced correctly.`` + +.. figure:: ../../resources/images/screenshots/offline-transaction-announce.png + :align: center + :width: 800px diff --git a/source/resources/examples/typescript/transfer/SigningATransactionOffline.ts b/source/resources/examples/typescript/transfer/SigningATransactionOffline.ts new file mode 100644 index 000000000..8acaca59c --- /dev/null +++ b/source/resources/examples/typescript/transfer/SigningATransactionOffline.ts @@ -0,0 +1,21 @@ +// transaction-uri.ts + +/* start block 01 */ +import { TransactionURI } from '../node_modules/symbol-uri-scheme/dist/src/uris/TransactionURI'; + +// Replace with your transaction payload from step 2 +const serializedTransaction = + 'C400000000000000955D258534DE29AC7F111A3E201C35779619EFC13EC3A309' + + '7AC8721A55799FF43C173EA4A6BC3174847086D28F0257FBE6E771C798A1A5D2' + + '2BF64E3C0F358001C0D6111B2AC378C69A4C71D013D3C4A748BE4EE48635EB79' + + 'FC3B4696157BF6320000000001985441A08601000000000049D4EB3A04000000' + + '988F2D81D729AC69B750A50E315D3C9070B4410F6D1E73834D01140000000000' + + 'EEAFF441BA994BE74054890000000000006F66666C696E65207472616E736163' + + '74696F6E'; + +const URI = 'web+symbol://transaction?data=' + serializedTransaction + '&generationHash=test' + + '&nodeUrl=http://localhost:3000&webhookUrl=http://myapp.local/id'; + +console.log(URI); + +/* end block 01 */ diff --git a/source/resources/images/screenshots/offline-transaction-account-create.png b/source/resources/images/screenshots/offline-transaction-account-create.png new file mode 100644 index 000000000..f6a3613a6 Binary files /dev/null and b/source/resources/images/screenshots/offline-transaction-account-create.png differ diff --git a/source/resources/images/screenshots/offline-transaction-announce.png b/source/resources/images/screenshots/offline-transaction-announce.png new file mode 100644 index 000000000..5af9a996f Binary files /dev/null and b/source/resources/images/screenshots/offline-transaction-announce.png differ diff --git a/source/resources/images/screenshots/offline-transaction-set-up.png b/source/resources/images/screenshots/offline-transaction-set-up.png new file mode 100644 index 000000000..483661106 Binary files /dev/null and b/source/resources/images/screenshots/offline-transaction-set-up.png differ