You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 23, 2023. It is now read-only.
Update documentation to include Protocol 19 features (#673)
* Add signed payloads to alternative signer types
* Describe new transaction preconditions
* Add new transaction and account fields to API docs
* Touch-ups to signed payloads and extra signers, cross-ref
* I think I'm missing some required properties?
* Blind leading the blind at this point
* Simplify types so that they render cleaner
* Specify correct verbiage for seqnum changes
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
* Consolidate terminology for consistency.
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
* Reword paragraph relating seqage to timebounds
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
* Improve verbiage around account sequence number "touch time".
* Clarify types for all of the new fields in API docs
* Clarify how signed payloads can be revealed
* New verbiage around sequence number touch-time: age!
* Fix relative links
* Improve verbiage around signed payload signers.
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
* More verbiage and seqnum age improvements
* Fix another broken link
* Drop txMALFORMED reference
* Clarify condition type in paragraph body
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Copy file name to clipboardExpand all lines: content/api/resources/transactions/object.mdx
+35-2
Original file line number
Diff line number
Diff line change
@@ -69,10 +69,43 @@ When Horizon returns information about a transaction, it uses the following form
69
69
- An array of signatures used to sign this transaction.
70
70
- valid_after
71
71
- RFC3339 date-time string
72
-
- The date after which a transaction is valid.
72
+
- The date after which a transaction is valid. This field is deprecated in lieu of `preconditions.time_bounds.min_time` and will be removed in Horizon v3.
73
73
- valid_before
74
74
- RFC3339 date-time string
75
-
- The date before which a transaction is valid.
75
+
- The date before which a transaction is valid. This field is deprecated in lieu of `preconditions.time_bounds.max_time` and will be removed in Horizon v3.
76
+
- preconditions
77
+
- object
78
+
- A set of transaction preconditions affecting its validity.
79
+
- time_bounds
80
+
- object
81
+
- The time range for which this transaction is valid, with bounds as unsigned 64-bit UNIX timestamps
82
+
- min_time
83
+
- string
84
+
- the lower bound
85
+
- max_time
86
+
- string
87
+
- the upper bound
88
+
- ledger_bounds
89
+
- object
90
+
- The ledger range for which this transaction is valid, as unsigned 32-bit integers.
91
+
- min_ledger
92
+
- number
93
+
- the lower bound
94
+
- max_ledger
95
+
- number
96
+
- the upper bound
97
+
- min_account_sequence
98
+
- string
99
+
- Containing a positive, signed 64-bit integer representing the lowest source account sequence number for which the transaction is valid.
100
+
- min_account_sequence_age
101
+
- number
102
+
- The minimum duration of time (in seconds as an unsigned 64-bit integer) that must have passed since the source account's sequence number changed for the transaction to be valid.
103
+
- min_account_sequence_ledger_gap
104
+
- number
105
+
- An unsigned 32-bit integer representing the minimum number of ledgers that must have closed since the source account's sequence number changed for the transaction to be valid.
106
+
- extra_signers
107
+
- array of strings
108
+
- The list of up to two additional signers that must have corresponding signatures for this transaction to be valid.
Copy file name to clipboardExpand all lines: content/docs/glossary/accounts.mdx
+4
Original file line number
Diff line number
Diff line change
@@ -33,6 +33,10 @@ The public key that was used to create the account. Even if you replace the sign
33
33
34
34
The current transaction sequence number of the account. This number starts equal to the ledger number at which the account was created, and increments upward as the account signs transactions.
35
35
36
+
### Sequence time and ledger
37
+
38
+
These two fields reflect the last time an account touched its sequence number. This occurs both when an account is the source account for a transaction and when it's the target of a [Bump Sequence](../start/list-of-operations.mdx#bump-sequence) operation. Both the ledger number and timestamp (i.e. the close time of the ledger) of the last touch is tracked by the network. Note that even if the [Bump Sequence](../start/list-of-operations.mdx#bump-sequence) operation has no effect, i.e. does not increase the sequence number, it still counts as a "touch".
39
+
36
40
### Number of subentries
37
41
38
42
Number of entries the account owns. This number is used to calculate the account's minimum balance: each subentry increases an account’s reserve by 0.5XLM. Subentries include:
Copy file name to clipboardExpand all lines: content/docs/glossary/multisig.mdx
+13-1
Original file line number
Diff line number
Diff line change
@@ -55,6 +55,10 @@ If the weight of the master key is updated to 0, it cannot be used to sign trans
55
55
56
56
Each additional signer beyond the master key increases the account's [minimum balance](./minimum-balance.mdx).
57
57
58
+
## Extra Signers
59
+
60
+
You can require that a transaction have a particular signer that isn't associated with any of the accounts used in the transaction by including it in the [transaction validity precondition](./transactions.mdx#extra-signers). The extra signer applies only to that one transaction.
61
+
58
62
## Alternate Signature Types
59
63
60
64
To enable some advanced smart contract features there are a couple of additional signature types. These signature types also have weights and can be added and removed similarly to normal signature types. But rather than check a cryptographic signature for authorization they have a different method of proving validity to the network.
@@ -69,10 +73,18 @@ This type of signer is especially useful in escrow accounts. You can pre-authori
69
73
70
74
### Hash(x)
71
75
72
-
Adding a signature of type hash(x) allows anyone who knows `x` to sign the transaction. This type of signer is especially useful in [atomic cross-chain swaps](https://en.bitcoin.it/wiki/Atomic_cross-chain_trading) which are needed for inter-blockchain protocols like [lightning networks](https://lightning.network).
76
+
Adding a signer of type hash(x) allows anyone who knows `x` to sign the transaction. This type of signer is especially useful in [atomic cross-chain swaps](https://en.bitcoin.it/wiki/Atomic_cross-chain_trading) which are needed for inter-blockchain protocols like [lightning networks](https://lightning.network).
73
77
74
78
First, create a random 256 bit value, which we call `x`. The SHA256 hash of that value can be added as a signer of type hash(x). Then in order to authorize a transaction, `x` is added as one of the signatures of the transaction. Keep in mind that `x` will be known to the world as soon as a transaction is submitted to the network with `x` as a signature. This means anyone will be able to sign for that account with the hash(x) signer at that point. Often you want there to be additional signers so someone must have a particular secret key and know `x` in order to reach the weight threshold required to authorize transactions on the account.
75
79
80
+
### Signed Payloads
81
+
82
+
Adding a signed payload as a signer means that transactions are only valid if they are accompanied by a signature of the signer's payload. The signature must be produced using the private key corresponding to the public key specified in the signer.
83
+
84
+
More verbosely, you add a signer of `(public key, payload)`, where the public key is the Stellar address of the expected signer and the payload is any arbitrary data of up to 64 bytes. A valid signature, then, is a signature on that payload by the private key corresponding to the public key. This is also described in [CAP-40](https://stellar.org/protocol/cap-40) which introduced this new signer.
85
+
86
+
Like with [hash signers](#hashx), once the signed payload signature is revealed to the world, anyone can use the signature to authorize transactions that are contingent on that signed payload signer.
87
+
76
88
## Envelopes
77
89
78
90
A transaction **envelope** wraps a transaction with a set of signatures. The transaction object is the thing that the signers are actually signing. Technically, a transaction envelope is the thing that is passed around the network and included in transaction sets.
Copy file name to clipboardExpand all lines: content/docs/glossary/transactions.mdx
+39-4
Original file line number
Diff line number
Diff line change
@@ -42,10 +42,38 @@ The memo contains optional extra information. It is the responsibility of the cl
42
42
-`MEMO_HASH` : A 32 byte hash.
43
43
-`MEMO_RETURN` : A 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding.
44
44
45
-
### Time Bounds
45
+
### Validity Conditions
46
46
47
+
There are a number of ways to control when a transaction should be considered valid. These conditions are checked first, prior to the validity of the operations or other parts of the transaction, so they're often referred to as "preconditions". They can all be combined, provided the combination is logically sound.
48
+
49
+
Some of the validity preconditions, namely the minimum sequence [age](#minimum-sequence-age) or [ledger gap](#minimum-sequence-ledger-gap) preconditions, are based on the account's [sequence number age](./accounts.mdx#sequence-time-and-ledger).
50
+
51
+
#### Time Bounds
47
52
The optional UNIX timestamp (in seconds), determined by ledger time, of a lower and upper bound of when this transaction will be valid. If a transaction is submitted too early or too late, it will fail to make it into the transaction set. `maxTime` equal `0` means that it's not set. _We highly advise for all transactions to use time bounds, and many SDKs enforce their usage._ If a transaction doesn't make it into the transaction set, it is kept around in memory in order to be added to the next transaction set on a best-effort basis. Because of this behavior, we highly advise that all transactions are created with time bounds in order to invalidate transactions after a certain amount of time, especially if you plan to resubmit your transaction at a later time.
48
53
54
+
#### Ledger Bounds
55
+
These are like [Time Bounds](#time-bounds), except they apply to ledger numbers. With them set, a transaction will only be valid for ledger numbers that fall into the range you set. The lower bound is inclusive while the upper bound is not. If you set the upper bound to zero, this indicates that there is no upper bound.
56
+
57
+
#### Minimum Sequence Number
58
+
If a minimum sequence number is set, the transaction will only be valid when its source account's sequence number (call it `S`) is large enough. Specifically, it's valid when `S` satisfies `minSeqNum <= S < tx.seqNum`. If this precondition is omitted, the default behavior applies: the transaction's sequence number must be exactly one greater than the account's sequence number.
59
+
60
+
Note that after a transaction is executed, the account will always set its sequence number to the transaction's sequence number.
61
+
62
+
#### Minimum Sequence Age
63
+
When the sequence age precondition is set, the transaction is only valid after a particular duration (expressed in seconds) elapses since the account's [sequence number age](./accounts.mdx#sequence-time-and-ledger).
64
+
65
+
Minimum sequence age is a precondition relating to time, but unlike [time bounds](#time-bounds) which express absolute times, minimum sequence age is relative to when the transaction source account's sequence number was touched.
66
+
67
+
#### Minimum Sequence Ledger Gap
68
+
When the ledger gap precondition is set, the transaction is only valid after the current network ledger number meets (or exceeds) a particular gap relative to the ledger corresponding to the account's [sequence number age](./accounts.mdx#sequence-time-and-ledger).
69
+
70
+
This is similar to the [minimum sequence age](#minimum-sequence-age), except it's expressed as a number of ledgers rather than a duration of time.
71
+
72
+
#### Extra Signers
73
+
A transaction can specify up to two extra signers as a precondition, meaning it must have signatures that correspond to those extra signers, even if those signatures would not otherwise be required to authorize the transaction (i.e. for its source account or operations).
74
+
75
+
The additional signers can be of any type besides a pre-authorized transaction signer, since to pre-authorize a transaction, you need to know its hash, but the hash must include the extra signers. This Catch-22 relationship means including this type of extra signer will return an error.
76
+
49
77
## Transaction Envelopes
50
78
51
79
Once a transaction is ready to be signed, the transaction object is wrapped in an object called a `Transaction Envelope`, which contains the transaction as well as a set of signatures. Most transaction envelopes only contain a single signature along with the transaction, but in [multi-signature setups](./multisig.mdx) it can contain many signatures.
@@ -67,7 +95,14 @@ To determine if a transaction is valid, many checks take place over the course o
67
95
- The appropriate network passphrase was part of the transaction hash that was signed by each of the signers. See [Network Passphrases](./network-passphrase.mdx) for more.
68
96
- The combined weight of all signatures for the source account _of the transaction_ meets the low threshold for the source account. This is necessary in order for fees to be taken and the sequence number to be incremented later in the transaction lifecycle.
69
97
-**Memo** — The memo type must be a valid type, and the memo itself must be adhere to the formatting of the memo type.
70
-
-**Time Bounds** — The transaction must be submitted within the set time bounds of the transaction, otherwise it will be considered invalid.
98
+
-**Preconditions** — refer to the [Validity Conditions](#validity-conditions) described above for thorough explanations of each of these. For each of these that are set, the transaction will be considered invalid unless the transaction is submitted:
99
+
***Time Bounds** — within the set time bounds of the transaction
100
+
***Ledger Bounds** — within the set ledger bounds of the transaction
101
+
***Minimum Sequence Number** — by a source account whose sequence number is greater than or equal to this value
102
+
***Minimum Sequence Age** — after a duration meeting or exceeding the source account's [sequence number age](./accounts.mdx#sequence-time-and-ledger)
103
+
***Minimum Sequence Ledger Gap** — in a ledger meeting or exceeding the source account's [sequence number age](./accounts.mdx#sequence-time-and-ledger)
104
+
***Extra Signers** — with signatures that fulfill each of the extra signers
105
+
71
106
72
107
## Transaction Lifecycle
73
108
@@ -162,5 +197,5 @@ found in [List of Operations](../start/list-of-operations.mdx) doc.
162
197
| NOT_SUPPORTED | -12 | The transaction type is not supported. |
0 commit comments