From 9bb47c8c6162cc34313212586ce5483fc29e602e Mon Sep 17 00:00:00 2001
From: Trent Nelson <trent@solana.com>
Date: Fri, 20 Dec 2019 13:07:07 -0500
Subject: [PATCH] Book: Document CLI offline signing (#7575)

* Book: Document offline signing

* Address review

* nits

* consistency

* one voice
---
 book/src/SUMMARY.md                |  1 +
 book/src/offline-signing/README.md | 77 ++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 book/src/offline-signing/README.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 123b208950..50f98d7541 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -38,6 +38,7 @@
 * [Paper Wallet](paper-wallet/README.md)
   * [Installation](paper-wallet/installation.md)
   * [Paper Wallet Usage](paper-wallet/usage.md)
+* [Offline Signing](offline-signing/README.md)
 * [API Reference](api-reference/README.md)
   * [Transaction](api-reference/transaction-api.md)
   * [Instruction](api-reference/instruction-api.md)
diff --git a/book/src/offline-signing/README.md b/book/src/offline-signing/README.md
new file mode 100644
index 0000000000..e80827634f
--- /dev/null
+++ b/book/src/offline-signing/README.md
@@ -0,0 +1,77 @@
+# Offline Transaction Signing
+
+Some security models require keeping signing keys, and thus the signing
+process, separated from transaction creation and network broadcast. Examples
+include:
+  * Collecting signatures from geographically disparate signers in a
+[multi-signature scheme](../api-reference/cli.md#multiple-witnesses)
+  * Signing transactions using an [airgapped](https://en.wikipedia.org/wiki/Air_gap_(networking))
+signing device
+
+This document describes using Solana's CLI to separately sign and submit a
+transaction.
+
+## Commands Supporting Offline Signing
+
+At present, the following commands support offline signing:
+  * [`delegate-stake`](../api-reference/cli.md#solana-delegate-stake)
+  * [`deactivate-stake`](../api-reference/cli.md#solana-deactivate-stake)
+  * [`pay`](../api-reference/cli.md#solana-pay)
+
+## Signing Transactions Offline
+
+To sign a transaction offline, pass the following arguments on the command line
+1) `--sign-only`, prevents the client from submitting the signed transaction
+to the network. Instead, the pubkey/signature pairs are printed to stdout. 
+2) `--blockhash BASE58_HASH`, allows the caller to specify the value used to
+fill the transaction's `recent_blockhash` field. This serves a number of
+purposes, namely:
+    * Eliminates the need to connect to the network and query a recent blockhash
+via RPC
+    * Enables the signers to coordinate the blockhash in a multiple-signature
+scheme
+
+### Example: Offline Signing a Payment
+
+Command
+
+```bash
+solana@offline$ solana pay --sign-only --blockhash 5Tx8F3jgSHx21CbtjwmdaKPLM5tWmreWAnPrbqHomSJF \
+    recipient-keypair.json 1 SOL
+```
+
+Output
+
+```text
+
+Blockhash: 5Tx8F3jgSHx21CbtjwmdaKPLM5tWmreWAnPrbqHomSJF
+Signers (Pubkey=Signature):
+  FhtzLVsmcV7S5XqGD79ErgoseCLhZYmEZnz9kQg1Rp7j=4vC38p4bz7XyiXrk6HtaooUqwxTWKocf45cstASGtmrD398biNJnmTcUCVEojE7wVQvgdYbjHJqRFZPpzfCQpmUN
+
+{"blockhash":"5Tx8F3jgSHx21CbtjwmdaKPLM5tWmreWAnPrbqHomSJF","signers":["FhtzLVsmcV7S5XqGD79ErgoseCLhZYmEZnz9kQg1Rp7j=4vC38p4bz7XyiXrk6HtaooUqwxTWKocf45cstASGtmrD398biNJnmTcUCVEojE7wVQvgdYbjHJqRFZPpzfCQpmUN"]}'
+```
+
+## Submitting Offline Signed Transactions to the Network
+
+To submit a transaction that has been signed offline to the network, pass the
+following arguments on the command line
+1) `--blockhash BASE58_HASH`, must be the same blockhash as was used to sign
+2) `--signer BASE58_PUBKEY=BASE58_SIGNATURE`, one for each offline signer. This
+includes the pubkey/signature pairs directly in the transaction rather than
+signing it with any local keypair(s)
+
+### Example: Submitting an Offline Signed Payment
+
+Command
+
+```bash
+solana@online$ solana pay --blockhash 5Tx8F3jgSHx21CbtjwmdaKPLM5tWmreWAnPrbqHomSJF \
+    --signer FhtzLVsmcV7S5XqGD79ErgoseCLhZYmEZnz9kQg1Rp7j=4vC38p4bz7XyiXrk6HtaooUqwxTWKocf45cstASGtmrD398biNJnmTcUCVEojE7wVQvgdYbjHJqRFZPpzfCQpmUN
+    recipient-keypair.json 1 SOL
+```
+
+Output
+
+```text
+4vC38p4bz7XyiXrk6HtaooUqwxTWKocf45cstASGtmrD398biNJnmTcUCVEojE7wVQvgdYbjHJqRFZPpzfCQpmUN
+```