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

Commit

Permalink
Use consistent names for issuer flags
Browse files Browse the repository at this point in the history
  • Loading branch information
sisuresh committed Feb 14, 2023
1 parent c7ac66e commit fe8e20e
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 19 deletions.
35 changes: 20 additions & 15 deletions content/docs/issuing-assets/control-asset-access.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,44 +10,46 @@ When you issue an asset on Stellar, anyone can hold it by default. In general, t

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.


## Flags

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:

### Authorization Required
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.

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.

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.

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

* `AUTHORIZED`: This flag signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders.
* `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.

- `AUTHORIZED_FLAG`: This flag signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders.
- `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.

### Authorization Revocable
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.

`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.
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.

`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.

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

### Authorization Immutable

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.

### Clawback Enabled
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).

Note that this flag requires that [revocable](#authorization-revocable) is also set.
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).

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

## Example flow
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.

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.
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.

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.

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.
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.

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

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

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.
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.

## Sample code

<Alert>

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.

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.

</Alert>


The following example sets authorization to be both required and revocable:

<CodeExample title="Asset Authorization">


```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Server("https://horizon-testnet.stellar.org");
Expand Down Expand Up @@ -154,7 +159,7 @@ transaction = (
base_fee=100,
)
.append_set_options_op(
set_flags=AuthorizationFlag.AUTHORIZATION_REVOCABLE | AuthorizationFlag.AUTHORIZATION_REQUIRED
set_flags=AuthorizationFlag.AUTH_REVOCABLE_FLAG | AuthorizationFlag.AUTHORIZATION_REQUIRED
)
.build()
)
Expand Down
8 changes: 4 additions & 4 deletions content/docs/start/list-of-operations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ Creates, updates, or deletes a trustline. For more on trustlines, please refer t

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

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.
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.

Threshold: Medium

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

Updates the `authorized` flag of an existing trustline.

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.
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.

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.

Expand Down Expand Up @@ -622,7 +622,7 @@ Possible errors:

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.

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.
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.

Threshold: Low

Expand Down Expand Up @@ -700,7 +700,7 @@ Possible errors:

Deposits assets into a liquidity pool.

Depositing increases the reserves of a liquidity pool in exchange for pool shares.
Depositing increases the reserves of a liquidity pool in exchange for pool shares.

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.

Expand Down

0 comments on commit fe8e20e

Please sign in to comment.