Skip to content

Commit 391213e

Browse files
werner-stacksgitbook-bot
werner-stacks
authored and
gitbook-bot
committed
GITBOOK-41: Post-conditions reference: em dashes, version availability, internal links, comparator ordering, inv
1 parent 92dadb6 commit 391213e

7 files changed

Lines changed: 92 additions & 50 deletions

File tree

‎docs/reference/stacks.js/stacks-transactions/post-conditions/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,4 @@ type PostCondition =
3333
| PoxPostCondition;
3434
```
3535

36-
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later. See [PostConditionType](../types/PostConditionType.md) for the wire values and the condition codes each type pairs with.
36+
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later. See [PostCondition](../types/PostCondition.md) for the shape of each, and [PostConditionType](../types/PostConditionType.md) for the wire values and the condition codes each type pairs with.

‎docs/reference/stacks.js/stacks-transactions/post-conditions/fromHex.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,14 @@ const postCondition = Pc.fromHex(hex);
2222
#### Notes
2323

2424
* Useful for parsing post conditions from serialized transaction data.
25+
* The inverse of [`postConditionToHex`](postConditionToHex.md).
2526

2627
[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/b7f0ed3f87cd4c5bfb7ab3c4bd8787c2018e3cec/packages/transactions/src/pc.ts)
2728

29+
{% hint style="info" %}
30+
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later.
31+
{% endhint %}
32+
2833
***
2934

3035
### Signature
@@ -37,7 +42,7 @@ function fromHex(hex: string): PostCondition;
3742

3843
### Returns
3944

40-
`PostCondition`
45+
[`PostCondition`](../types/PostCondition.md)
4146

4247
```ts
4348
type PostCondition =
@@ -48,10 +53,6 @@ type PostCondition =
4853
| PoxPostCondition;
4954
```
5055

51-
A deserialized post condition object.
52-
53-
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later.
54-
5556
***
5657

5758
### Parameters

‎docs/reference/stacks.js/stacks-transactions/post-conditions/origin.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,15 @@ Pc.origin().willNotPerformPox();
2727
#### Notes
2828

2929
* Use `Pc.origin()` when the post condition should apply to the sender of the transaction without specifying a specific address.
30-
* The builder chain is the same as `Pc.principal()`, including the staking and PoX terminals.
30+
* `Pc.origin()` takes no arguments.
31+
* The builder chain is the same as [`Pc.principal`](principal.md), including the staking and PoX terminals.
3132

3233
[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/b7f0ed3f87cd4c5bfb7ab3c4bd8787c2018e3cec/packages/transactions/src/pc.ts)
3334

35+
{% hint style="info" %}
36+
`.ustxToLock()` and the PoX methods were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later.
37+
{% endhint %}
38+
3439
***
3540

3641
### Signature
@@ -45,4 +50,4 @@ function origin(): PartialPcWithPrincipal;
4550

4651
`PartialPcWithPrincipal`
4752

48-
An intermediate builder object. See `Pc.principal` for the full chain API.
53+
An intermediate builder object. See [`Pc.principal`](principal.md) for the full chain API.

‎docs/reference/stacks.js/stacks-transactions/post-conditions/postConditionToHex.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,23 @@ import { postConditionToHex } from '@stacks/transactions';
1111

1212
const hex = postConditionToHex({
1313
type: 'stx-postcondition',
14-
address: 'ST00000000000000000002Q6VF78',
14+
address: 'SP000000000000000000002Q6VF78',
1515
condition: 'eq',
1616
amount: '1000000000000000000',
1717
});
1818
```
1919

2020
#### Notes
2121

22-
* The inverse of `Pc.fromHex`.
22+
* The inverse of [`Pc.fromHex`](fromHex.md).
2323
* Useful for serializing post conditions for storage or transmission.
2424

2525
[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/b7f0ed3f87cd4c5bfb7ab3c4bd8787c2018e3cec/packages/transactions/src/postcondition.ts)
2626

27+
{% hint style="info" %}
28+
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later.
29+
{% endhint %}
30+
2731
***
2832

2933
### Signature
@@ -38,15 +42,15 @@ function postConditionToHex(postcondition: PostCondition): string;
3842

3943
`string`
4044

41-
A hex-encoded string representation of the post condition.
45+
The hex-encoded serialization of the post condition.
4246

4347
***
4448

4549
### Parameters
4650

4751
#### postcondition (required)
4852

49-
* **Type**: `PostCondition`
53+
* **Type**: [`PostCondition`](../types/PostCondition.md)
5054

5155
```ts
5256
type PostCondition =
@@ -57,4 +61,4 @@ type PostCondition =
5761
| PoxPostCondition;
5862
```
5963

60-
The post condition object to serialize. `StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later.
64+
The post condition object to serialize.

‎docs/reference/stacks.js/stacks-transactions/post-conditions/principal.md‎

Lines changed: 28 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Entry point for building post conditions. Starts the post condition builder chain by specifying the principal (address) the condition applies to.
44

5-
The `Pc` builder uses a chainable API pattern: `PRINCIPAL → [AMOUNT] → CODE → ASSET`. PoX conditions are the exception — they terminate directly on the principal.
5+
The `Pc` builder uses a chainable API pattern: `PRINCIPAL → [AMOUNT] → CODE → ASSET`. PoX conditions are the exception: they terminate directly on the principal.
66

77
***
88

@@ -11,7 +11,7 @@ The `Pc` builder uses a chainable API pattern: `PRINCIPAL → [AMOUNT] → CODE
1111
```ts
1212
import { Pc, Cl } from '@stacks/transactions';
1313

14-
// STX post condition — principal will send exactly 10,000 microSTX
14+
// STX post condition: principal will send exactly 10,000 microSTX
1515
Pc.principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
1616
.willSendEq(10000)
1717
.ustx();
@@ -31,12 +31,12 @@ Pc.principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
3131
.willMaybeSendAsset()
3232
.nft('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft-contract::nft-name', Cl.uint(1));
3333

34-
// Staking post condition — principal will lock at most 1 STX
34+
// Staking post condition: principal will lock at most 1 STX
3535
Pc.principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
3636
.willSendLte(1000000)
3737
.ustxToLock();
3838

39-
// PoX post condition — terminates directly, no amount or asset
39+
// PoX post condition: terminates directly, no amount or asset
4040
Pc.principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6').willNotPerformPox();
4141

4242
// Contract principal
@@ -48,12 +48,22 @@ Pc.principal('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract')
4848
#### Notes
4949

5050
* The address can be a standard principal (`ST...`) or a contract principal (`address.contract-name`).
51-
* After calling `Pc.principal()`, chain one of the amount/comparator methods, then finalize with an asset method — except for the PoX methods, which return a complete post condition on their own.
51+
* After calling `Pc.principal()`, chain one of the amount/comparator methods, then finalize with an asset method. The PoX methods are the exception: they return a complete post condition on their own.
52+
* To apply a post condition to the transaction sender without naming an address, use [`Pc.origin`](origin.md).
5253

5354
[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/b7f0ed3f87cd4c5bfb7ab3c4bd8787c2018e3cec/packages/transactions/src/pc.ts)
5455

5556
***
5657

58+
### Availability
59+
60+
| Feature | Available from |
61+
| --------------------------------------------- | ---------------------------------------------- |
62+
| `.willMaybeSendAsset()` (SIP-040) | `@stacks/transactions` 7.4.0, Stacks epoch 3.4 |
63+
| `.ustxToLock()` and the PoX methods (SIP-045) | `@stacks/transactions` 7.5.0, Stacks epoch 4.0 |
64+
65+
***
66+
5767
### Signature
5868

5969
```ts
@@ -71,13 +81,13 @@ An intermediate builder object. Chain with one of the following methods:
7181
| Method | Description |
7282
| ----------------------- | --------------------------------------------------------------------- |
7383
| `.willSendEq(amount)` | Amount sent will be **equal to** the specified amount |
74-
| `.willSendLte(amount)` | Amount sent will be **less than or equal to** the specified amount |
75-
| `.willSendLt(amount)` | Amount sent will be **less than** the specified amount |
76-
| `.willSendGte(amount)` | Amount sent will be **greater than or equal to** the specified amount |
7784
| `.willSendGt(amount)` | Amount sent will be **greater than** the specified amount |
85+
| `.willSendGte(amount)` | Amount sent will be **greater than or equal to** the specified amount |
86+
| `.willSendLt(amount)` | Amount sent will be **less than** the specified amount |
87+
| `.willSendLte(amount)` | Amount sent will be **less than or equal to** the specified amount |
7888
| `.willSendAsset()` | The principal **will send** the NFT asset |
7989
| `.willNotSendAsset()` | The principal **will not send** the NFT asset |
80-
| `.willMaybeSendAsset()` | The NFT asset **may or may not** be sent — always passes |
90+
| `.willMaybeSendAsset()` | The NFT asset **may or may not** be sent; always passes |
8191

8292
After an amount comparator, finalize with an asset method:
8393

@@ -93,21 +103,21 @@ After an NFT comparator, finalize with:
93103
| -------------------------- | ---------------------------------------------------------------------- |
94104
| `.nft(assetName, assetId)` | Non-fungible token post condition (returns `NonFungiblePostCondition`) |
95105

106+
See [PostCondition](../types/PostCondition.md) for the shape each of these returns.
107+
96108
***
97109

98110
### PoX methods
99111

100-
These return a complete `PoxPostCondition` immediately — there is no amount and no asset to supply.
112+
These return a complete `PoxPostCondition` immediately. There is no amount and no asset to supply.
101113

102-
| Method | Condition code | Description |
103-
| ---------------------- | ---------------- | ------------------------------------------------------------ |
104-
| `.willPerformPox()` | `WillPerform` | The principal **must** perform a gated PoX action |
105-
| `.willNotPerformPox()` | `WillNotPerform` | The principal **must not** perform a gated PoX action |
106-
| `.mayPerformPox()` | `MayPerform` | The principal **may or may not** perform one — always passes |
114+
| Method | Condition code | Description |
115+
| ---------------------- | ---------------- | ----------------------------------------------------------- |
116+
| `.willNotPerformPox()` | `WillNotPerform` | The principal **must not** perform a gated PoX action |
117+
| `.mayPerformPox()` | `MayPerform` | The principal **may or may not** perform one; always passes |
118+
| `.willPerformPox()` | `WillPerform` | The principal **must** perform a gated PoX action |
107119

108-
{% hint style="info" %}
109-
`.willMaybeSendAsset()` comes from [SIP-040](https://github.com/stacksgov/sips/blob/main/sips/sip-040/sip-040-post-conds.md) and is available in `@stacks/transactions` 7.4.0 and later. `.ustxToLock()` and the PoX methods were added for Stacks epoch 4.0 and are available in 7.5.0 and later.
110-
{% endhint %}
120+
See [PostConditionType](../types/PostConditionType.md) for the wire values behind these condition codes.
111121

112122
***
113123

‎docs/reference/stacks.js/stacks-transactions/types/PostCondition.md‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# PostCondition
22

3-
Union type representing the five kinds of post-conditions: STX, fungible token, non-fungible token, staking, and PoX.
3+
Union type representing every kind of post-condition: STX, fungible token, non-fungible token, staking, and PoX.
44

55
***
66

@@ -44,8 +44,19 @@ type PostCondition =
4444
| PoxPostCondition;
4545
```
4646

47+
See [PostConditionType](PostConditionType.md) for the wire value each of these serializes to.
48+
49+
***
50+
51+
### Availability
52+
53+
| Member | Available from |
54+
| ------------------------------------------------------- | ---------------------------------------------- |
55+
| `maybe-sent` on `NonFungiblePostCondition` (SIP-040) | `@stacks/transactions` 7.4.0, Stacks epoch 3.4 |
56+
| `StakingPostCondition` and `PoxPostCondition` (SIP-045) | `@stacks/transactions` 7.5.0, Stacks epoch 4.0 |
57+
4758
{% hint style="info" %}
48-
`StakingPostCondition` and `PoxPostCondition` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later. The source labels them SIP-044 in its JSDoc; the post-conditions themselves are specified in [SIP-045 §3.4.3](https://github.com/stacksgov/sips/blob/main/sips/sip-045/sip-045-pox-5-bitcoin-staking.md).
59+
Staking and PoX post-conditions are specified in [SIP-045 §3.4.3](https://github.com/stacksgov/sips/blob/main/sips/sip-045/sip-045-pox-5-bitcoin-staking.md). The `@stacks/transactions` JSDoc labels these SIP-044; the two SIPs activated together.
4960
{% endhint %}
5061

5162
***
@@ -100,13 +111,13 @@ interface NonFungiblePostCondition {
100111
}
101112
```
102113

103-
`maybe-sent` was added by [SIP-040](https://github.com/stacksgov/sips/blob/main/sips/sip-040/sip-040-post-conds.md) and is available in `@stacks/transactions` 7.4.0 and later. It always passes, and still counts as covering that NFT instance under `Deny` or `Originator` mode.
114+
`maybe-sent` was added by [SIP-040](https://github.com/stacksgov/sips/blob/main/sips/sip-040/sip-040-post-conds.md). It always passes, and still counts as covering that NFT instance under `Deny` or `Originator` mode.
104115

105116
***
106117

107118
### StakingPostCondition
108119

109-
Guards staking STX, or modifying staked STX, for a principal — for example the pox-5 `stake`, `register-for-bond`, and `stake-update` calls. Uses the same comparators as `StxPostCondition`.
120+
Guards staking STX, or modifying staked STX, for a principal. For example, the pox-5 `stake`, `register-for-bond`, and `stake-update` calls. Uses the same comparators as `StxPostCondition`.
110121

111122
```ts
112123
interface StakingPostCondition {
@@ -124,7 +135,7 @@ interface StakingPostCondition {
124135

125136
### PoxPostCondition
126137

127-
Guards PoX state changes that do not alter locking status — for example the pox-5 `unstake`, `unstake-sbtc`, `update-bond-registration`, and `announce-l1-early-exit` calls. Carries only a principal and a condition code: there is no asset and no amount.
138+
Guards PoX state changes that do not alter locking status. For example, the pox-5 `unstake`, `unstake-sbtc`, `update-bond-registration`, and `announce-l1-early-exit` calls. Carries only a principal and a condition code: there is no asset and no amount.
128139

129140
```ts
130141
interface PoxPostCondition {
@@ -140,8 +151,8 @@ interface PoxPostCondition {
140151
type PoxComparator = 'will-not-perform' | 'may-perform' | 'will-perform';
141152
```
142153

143-
| Comparator | Meaning |
144-
| ------------------ | -------------------------------------------------------- |
145-
| `will-not-perform` | The principal must not perform a gated PoX action |
146-
| `may-perform` | The principal may or may not perform one — always passes |
147-
| `will-perform` | The principal must perform a gated PoX action |
154+
| Comparator | Meaning |
155+
| ------------------ | ------------------------------------------------------- |
156+
| `will-not-perform` | The principal must not perform a gated PoX action |
157+
| `may-perform` | The principal may or may not perform one; always passes |
158+
| `will-perform` | The principal must perform a gated PoX action |

‎docs/reference/stacks.js/stacks-transactions/types/PostConditionType.md‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,16 +35,27 @@ enum PostConditionType {
3535

3636
### Values
3737

38-
| Value | Number | Description |
39-
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
40-
| `STX` | `0x00` | STX token post-condition |
41-
| `Fungible` | `0x01` | Fungible token (SIP-010) post-condition |
42-
| `NonFungible` | `0x02` | Non-fungible token (SIP-009) post-condition |
43-
| `Staking` | `0x03` | Guards staking STX, or modifying staked STX, for a principal. Mirrors the `STX` shape — principal, a `FungibleConditionCode`, and an amount. |
44-
| `PoX` | `0x04` | Guards PoX state changes that do not alter locking status. Carries a principal and a `PoxConditionCode`, with no amount. |
38+
| Value | Number | Description |
39+
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| `STX` | `0x00` | STX token post-condition |
41+
| `Fungible` | `0x01` | Fungible token (SIP-010) post-condition |
42+
| `NonFungible` | `0x02` | Non-fungible token (SIP-009) post-condition |
43+
| `Staking` | `0x03` | Guards staking STX, or modifying staked STX, for a principal. Mirrors the `STX` shape: principal, a `FungibleConditionCode`, and an amount. |
44+
| `PoX` | `0x04` | Guards PoX state changes that do not alter locking status. Carries a principal and a `PoxConditionCode`, with no amount. |
45+
46+
See [PostCondition](PostCondition.md) for the object shape behind each of these.
47+
48+
***
49+
50+
### Availability
51+
52+
| Member | Available from |
53+
| ----------------------------- | ---------------------------------------------- |
54+
| `MaybeSent` (SIP-040) | `@stacks/transactions` 7.4.0, Stacks epoch 3.4 |
55+
| `Staking` and `PoX` (SIP-045) | `@stacks/transactions` 7.5.0, Stacks epoch 4.0 |
4556

4657
{% hint style="info" %}
47-
`Staking` and `PoX` were added for Stacks epoch 4.0 and are available in `@stacks/transactions` 7.5.0 and later. The source labels them SIP-044 in its JSDoc; the post-conditions themselves are specified in [SIP-045 §3.4.3](https://github.com/stacksgov/sips/blob/main/sips/sip-045/sip-045-pox-5-bitcoin-staking.md).
58+
Staking and PoX post-conditions are specified in [SIP-045 §3.4.3](https://github.com/stacksgov/sips/blob/main/sips/sip-045/sip-045-pox-5-bitcoin-staking.md). The `@stacks/transactions` JSDoc labels these SIP-044; the two SIPs activated together.
4859
{% endhint %}
4960

5061
***
@@ -75,7 +86,7 @@ enum NonFungibleConditionCode {
7586
}
7687
```
7788

78-
`MaybeSent` was added by [SIP-040](https://github.com/stacksgov/sips/blob/main/sips/sip-040/sip-040-post-conds.md), is enabled from epoch 3.4, and is available in `@stacks/transactions` 7.4.0 and later. It always passes, and still counts as covering that NFT instance under `Deny` or `Originator` mode.
89+
`MaybeSent` was added by [SIP-040](https://github.com/stacksgov/sips/blob/main/sips/sip-040/sip-040-post-conds.md). It always passes, and still counts as covering that NFT instance under `Deny` or `Originator` mode.
7990

8091
`PoX` uses `PoxConditionCode`:
8192

0 commit comments

Comments
 (0)