signerlist node updates; signers tx field; signerlistset stub

content/reference-ledger-format.md

@@ -415,12 +415,12 @@ A SignerList node has the following fields:
 
 | Name            | JSON Type | Internal Type | Description |
 |-----------------|-----------|---------------|-------------|
-| OwnerNode       |           | UInt64        | <span class='draft-comment'>?</span> |
+| OwnerNode       | String    | UInt64        | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes. |
 | SignerQuorum    | Number    | UInt32        | A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more. |
 | SignerEntries   | Array     | Array         | An array of SignerEntry objects representing the parties who are part of this signer list. |
 | SignerListID    |           | UInt32        | An ID for this signer list. Currently always set to `0`. If a future update allows multiple signer lists for an account, this may change. |
-| PreviousTxnID   |           | Hash256       | The identifying hash of a previous transaction <span class='draft-comment'>that modified this node?</span> |
+| PreviousTxnID   | String    | Hash256       | The identifying hash of the transaction that most recently modified this node. |
-| PreviousTxnLgrSeq |         | UInt32        | The sequence number of the ledger that included the `PreviousTxnID`. |
+| PreviousTxnLgrSeq | Number  | UInt32        | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
 
 ### SignerEntry object ###
 
@@ -428,7 +428,7 @@ Each member of the `SignerEntries` field is an object that describes that signer
 
 | Name            | JSON Type | Internal Type | Description |
 |-----------------|-----------|---------------|-------------|
-| Account         | String    | AccountID     | An address whose signature contributes to the multi-signature. <span class='draft-comment'>It doesn't have to exist in the ledger, or does it?</span> |
+| Account         | String    | AccountID     | An address whose signature contributes to the multi-signature. This does not need to be a funded Ripple account. |
 | SignerWeight    | Number    | UInt16        | The weight of signatures from this signer. A multi-signature is only valid of the sum weight of the signatures provided meets or exceeds the SignerList's `SignerQuorum` value. |
 
 

content/reference-transaction-format.md

@@ -193,7 +193,8 @@ Every transaction type has the same set of fundamental fields:
 | [LastLedgerSequence](#lastledgersequence) | Number | UInt32 | (Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in. |
 | [Memos](#memos) | Array of Objects | Array | (Optional) Additional arbitrary information used to identify this transaction. |
 | [Sequence](#canceling-or-skipping-a-transaction) | Unsigned Integer | UInt32 | (Required, but [auto-fillable](#auto-fillable-fields)) The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the last-valided transaction from the same account. |
-| SigningPubKey | String | PubKey | (Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. |
+| SigningPubKey | String | PubKey | (Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. |
+| [Signers](#multi-signing) | Array | Array | (Optional) Array of objects that represent a multi-signature which authorizes this transaction. |
 | SourceTag | Unsigned Integer | UInt32 | (Optional) Arbitrary integer used to identify the reason for this payment, or the hosted wallet on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
 | TransactionType | String | UInt16 | The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, and `SetRegularKey`. |
 | TxnSignature | String | VariableLength | (Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from. |
@@ -213,11 +214,14 @@ For a production system, we recommend *not* leaving these fields to be filled by
 
 The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also be automatically filled in.
 
+
 ### Transaction Cost ###
 
-In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
+In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
 
-The `Fee` field specifies an amount, in [drops of XRP](reference-rippled.html#specifying-currency-amounts), to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
+The `Fee` field specifies an amount, in [drops of XRP](reference-rippled.html#specifying-currency-amounts), to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
+
+**Note:** [Multi-signed transactions](#multi-signing) require additional fees to relay to the network.
 
 
 ### Canceling or Skipping a Transaction ###
@@ -248,7 +252,7 @@ In order to use AccountTxnID, you must first set the [asfAccountTxnID](#accounts
 
 ### Memos ###
 
-The Memos field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields:
+The `Memos` field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields:
 
 | Field | Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
 |-------|------|--------------------------------------------------------|-------------|
@@ -279,10 +283,27 @@ Example of a transaction with a Memos field:
 }
 ```
 
+### Multi-signing ###
+
+The `Signers` field contains a multi-signature, which has signatures from up to 8 key pairs, that together should authorize the transaction. A multi-signature replaces a single signature by either the master key or regular key. To provide a multi-signature, an account must first have a SignerList associated with it, which it can do by sending a [SignerListSet](#signerlistset) transaction.
+
+The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields:
+
+| Field | Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
+|-------|------|--------------------------------------------------------|-------------|
+| Account | String | AccountID | The address associated with this signature, as it appears in the SignerList. |
+| TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. |
+| SigningPubKey | String | The public key used to create this signature. |
+
+The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [lsfDisableMaster](ripple-ledger.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address.
+
+Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-siganture increases the `Fee` required by the amount of the minimum transaction fee. For example, if the current minimum `Fee` value to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would cost `40000` drops to relay.
+
+
 
 ### Flags ###
 
-The Flags field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
+The `Flags` field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
 
 Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the `TransactionType` field when setting and reading flags.
 
@@ -776,6 +797,16 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv
 
 
 
+## SignerListSet ##
+
+The SignerListSet transaction creates, modifies, or removes a list of signers that can be used to multi-sign a transaction.
+<span class='draft-comment'>(TODO)</span>
+
+
+
+
+
+
 # Transaction Results #
 
 ## Immediate Response ##
@@ -1042,4 +1073,3 @@ These codes are only ever returned by the `ripple-lib` client library, not by `r
 | tejSecretUnknown | The secret for a given account was omitted from the transaction, and ripple-lib was unable to automatically fill it in from saved data. |
 | tejServerUntrusted | The application attempted to submit an account secret to an untrusted server for transaction signing. |
 | tejUnconnected | The application is not connected to a `rippled` server, but it needs to be in order to process the transaction. |
-