Skip to content
This repository was archived by the owner on Feb 23, 2023. It is now read-only.

Commit fe8e20e

Browse files
committed
Use consistent names for issuer flags
1 parent c7ac66e commit fe8e20e

2 files changed

Lines changed: 24 additions & 19 deletions

File tree

content/docs/issuing-assets/control-asset-access.mdx

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,44 +10,46 @@ When you issue an asset on Stellar, anyone can hold it by default. In general, t
1010

1111
However, if you need to control access to an asset to comply with regulations (or for any other reason), you can easily do so by enabling flags on your issuing account.
1212

13-
1413
## Flags
1514

1615
Flags are created on the _account level_ using a [`set_options`](../start/list-of-operations.mdx#set-options) operation. They can be set at any time in the life cycle of an asset, not just when you issue it:
1716

1817
### Authorization Required
19-
When `AUTHORIZATION REQUIRED` is enabled, an issuer must approve an account before that account can hold its asset. This setting allows issuers to vet potential token holders using whatever means they see fit, and to approve trustlines if and only if the holders pass muster.
18+
19+
When `AUTH_REQUIRED_FLAG` is enabled, an issuer must approve an account before that account can hold its asset. This setting allows issuers to vet potential token holders using whatever means they see fit, and to approve trustlines if and only if the holders pass muster.
2020

2121
To allow access, the user creates a trustline, and the issuer approves it by changing the `AUTHORIZE` flag with the [`allow_trust`](../start/list-of-operations.mdx#allow-trust) operation.
2222

2323
There are two levels of authorization an asset issuer can grant using the `allow_trust` operation:
2424

25-
* `AUTHORIZED`: This flag signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders.
26-
* `AUTHORIZED_TO_MAINTAIN_LIABILITIES`: This flag denotes limited authorization that allows an account to maintain current orders, but not to otherwise transact with the asset.
27-
25+
- `AUTHORIZED_FLAG`: This flag signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders.
26+
- `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG`: This flag denotes limited authorization that allows an account to maintain current orders, but not to otherwise transact with the asset.
2827

2928
### Authorization Revocable
30-
When `AUTHORIZATION_REVOCABLE` is enabled, an issuer can revoke an existing trustline's authorization, thereby freezing the asset held by an account. Doing so prevents that account from transfering or trading the asset, and cancels the account’s open orders for the asset.
3129

32-
`AUTHORIZATION_REVOCABLE` also allows an issuer to reduce authorization from complete to limited, which prevents the account from transferring or trading the asset, but does not cancel the account's open orders for the asset. This setting is useful for issuers of regulated assets who need to authorize transactions on a case-by-case basis to ensure each conforms to certain requirements.
30+
When `AUTH_REVOCABLE_FLAG` is enabled, an issuer can revoke an existing trustline's authorization, thereby freezing the asset held by an account. Doing so prevents that account from transfering or trading the asset, and cancels the account’s open orders for the asset.
31+
32+
`AUTH_REVOCABLE_FLAG` also allows an issuer to reduce authorization from complete to limited, which prevents the account from transferring or trading the asset, but does not cancel the account's open orders for the asset. This setting is useful for issuers of regulated assets who need to authorize transactions on a case-by-case basis to ensure each conforms to certain requirements.
3333

3434
All changes to asset authorization are performed with the [`allow_trust`](../start/list-of-operations.mdx#allow-trust) operation.
3535

3636
### Authorization Immutable
37+
3738
With this setting, neither of the other authorization flags can be set, and the issuing account can’t be merged. You set this flag to signal to potential token holders that your issuing account and its assets will persist on ledger in an open and accessible state.
3839

3940
### Clawback Enabled
40-
With the `AUTHORIZATION_CLAWBACK_ENABLED` flag set, any *subsequent* trustlines established with this account will have clawbacks enabled. You can read more about clawbacks (and selectively controlling them on a per-trustline basis) [here](../glossary/clawback.mdx).
4141

42-
Note that this flag requires that [revocable](#authorization-revocable) is also set.
42+
With the `AUTH_CLAWBACK_ENABLED_FLAG` flag set, any _subsequent_ trustlines established with this account will have clawbacks enabled. You can read more about clawbacks (and selectively controlling them on a per-trustline basis) [here](../glossary/clawback.mdx).
4343

44+
Note that this flag requires that [revocable](#authorization-revocable) is also set.
4445

4546
## Example flow
46-
To get a sense of how authorization flags work, let's look at how an issuer of a regulated asset might use the `AUTHORIZED_TO_MAINTAIN_LIABILITIES` flag.
4747

48-
If the issuer wants to approve transactions on a case-by-base basis while allowing accounts to maintain offers, they can leave an account in the `AUTHORIZED_TO_MAINTAIN_LIABILITIES` state. That account can own offers, but cannot otherwise do anything with the asset.
48+
To get a sense of how authorization flags work, let's look at how an issuer of a regulated asset might use the `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG` flag.
49+
50+
If the issuer wants to approve transactions on a case-by-base basis while allowing accounts to maintain offers, they can leave an account in the `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG` state. That account can own offers, but cannot otherwise do anything with the asset.
4951

50-
To intitiate a new operation, the holding account requests that the issuer approve and sign a transaction. Once the issuer inspects the operation and decides to approve it, they sandwich it between a set of operations, first granting authorization, then reducing it.
52+
To intitiate a new operation, the holding account requests that the issuer approve and sign a transaction. Once the issuer inspects the operation and decides to approve it, they sandwich it between a set of operations, first granting authorization, then reducing it.
5153

5254
Here's a payment from A to B sandwiched between [`set_trust_line_flags`](../start/list-of-operations.mdx#set-trustline-flags) operations:
5355

@@ -57,20 +59,23 @@ Here's a payment from A to B sandwiched between [`set_trust_line_flags`](../star
5759
- Operation 4: Issuer uses `SetTrustLineFlags` to set account B, asset X to `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG` state
5860
- Operation 5: Issuer uses `SetTrustLineFlags` to set account A, asset X to `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG` state
5961

60-
The authorization sandwich allows the issuer to inspect the specifc payment, and to grant authorization for it and it alone. Since operations bundled in a transaction are simultaneous, A and B are only authorized for the specific, pre-approved payment operation. Complete authorization does not extend beyond the specific transaction.
62+
The authorization sandwich allows the issuer to inspect the specifc payment, and to grant authorization for it and it alone. Since operations bundled in a transaction are simultaneous, A and B are only authorized for the specific, pre-approved payment operation. Complete authorization does not extend beyond the specific transaction.
6163

6264
## Sample code
6365

6466
<Alert>
6567

66-
In the following code samples, proper error checking is omitted for brevity. However, you should *always* validate your results, as there are many ways that requests can fail. You should refer to the guide on [Handling Errors Gracefully](../tutorials/handling-errors.mdx) for tips on error management strategies.
68+
69+
In the following code samples, proper error checking is omitted for brevity. However, you should _always_ validate your results, as there are many ways that requests can fail. You should refer to the guide on [Handling Errors Gracefully](../tutorials/handling-errors.mdx) for tips on error management strategies.
6770

6871
</Alert>
6972

73+
7074
The following example sets authorization to be both required and revocable:
7175

7276
<CodeExample title="Asset Authorization">
7377

78+
7479
```js
7580
var StellarSdk = require("stellar-sdk");
7681
var server = new StellarSdk.Server("https://horizon-testnet.stellar.org");
@@ -154,7 +159,7 @@ transaction = (
154159
base_fee=100,
155160
)
156161
.append_set_options_op(
157-
set_flags=AuthorizationFlag.AUTHORIZATION_REVOCABLE | AuthorizationFlag.AUTHORIZATION_REQUIRED
162+
set_flags=AuthorizationFlag.AUTH_REVOCABLE_FLAG | AuthorizationFlag.AUTHORIZATION_REQUIRED
158163
)
159164
.build()
160165
)

content/docs/start/list-of-operations.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ Creates, updates, or deletes a trustline. For more on trustlines, please refer t
359359

360360
To delete an existing trustline, set Line to the asset of the trustline, and Limit to `0`.
361361

362-
The `Line` parameter is an instance of a `ChangeTrustAsset`. If you are modifying a trustline to a regular asset (i.e. one in a `Code:Issuer` format), this is equivalent to the `Asset` type. If you are modifying a trustline to a *pool share*, however, this is composed of the liquidity pool reserve assets and the pool fee. You can refer to the liquidity pool [glossary entry](../glossary/liquidity-pool.mdx#liquidity-pool-participation) and the examples therein for details.
362+
The `Line` parameter is an instance of a `ChangeTrustAsset`. If you are modifying a trustline to a regular asset (i.e. one in a `Code:Issuer` format), this is equivalent to the `Asset` type. If you are modifying a trustline to a _pool share_, however, this is composed of the liquidity pool reserve assets and the pool fee. You can refer to the liquidity pool [glossary entry](../glossary/liquidity-pool.mdx#liquidity-pool-participation) and the examples therein for details.
363363

364364
Threshold: Medium
365365

@@ -397,7 +397,7 @@ This operation is deprecated as of Protocol 17. Prefer [SetTrustLineFlags](#set-
397397

398398
Updates the `authorized` flag of an existing trustline.
399399

400-
This can only be called by the issuer of a trustline's [asset](../glossary/assets.mdx), and only when `AUTHORIZATION REQUIRED` has been set on the issuer's account.
400+
This can only be called by the issuer of a trustline's [asset](../glossary/assets.mdx), and only when `AUTH_REQUIRED_FLAG` has been set on the issuer's account.
401401

402402
There are two different kinds of asset authorization: complete authorization, which allows an account to transact with an asset (by making payments, creating offers, etc.) and limited authorization, which allows an account to maintain and reduce current offers, but not to perform other operations with the asset.
403403

@@ -622,7 +622,7 @@ Possible errors:
622622

623623
Allows an issuing account to configure various authorization and trustline flags for all trustlines to an asset. This supersedes the deprecated [`AllowTrust`](#allow-trust), but the documentation there still applies.
624624

625-
The `Asset` parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a `Code:Issuer` format), this is equivalent to the `Asset` type. If you are modifying a trustline to a *pool share*, however, this is composed of the liquidity pool's unique ID. You can refer to the liquidity pool [glossary entry](../glossary/liquidity-pool.mdx#liquidity-pool-participation) and the examples therein for details.
625+
The `Asset` parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a `Code:Issuer` format), this is equivalent to the `Asset` type. If you are modifying a trustline to a _pool share_, however, this is composed of the liquidity pool's unique ID. You can refer to the liquidity pool [glossary entry](../glossary/liquidity-pool.mdx#liquidity-pool-participation) and the examples therein for details.
626626

627627
Threshold: Low
628628

@@ -700,7 +700,7 @@ Possible errors:
700700

701701
Deposits assets into a liquidity pool.
702702

703-
Depositing increases the reserves of a liquidity pool in exchange for pool shares.
703+
Depositing increases the reserves of a liquidity pool in exchange for pool shares.
704704

705705
Parameters to this operation depend on the ordering of assets in the liquidity pool: “A” refers to the first asset in the liquidity pool, and “B” refers to the second asset in the liquidity pool. Refer to the liquidity pool [glossary entry](../glossary/liquidity-pool.mdx#liquidity-pool-participation) for information about how to determine the fixed ordering of assets. SDKs often have helpers (like [`Asset.compare`](https://stellar.github.io/js-stellar-base/Asset.html#.compare)) to determine the right order.
706706

0 commit comments

Comments
 (0)