From 3cc89855b2cad919bcc58e895524e7956bd176bd Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Fri, 18 Nov 2022 14:16:52 -0700 Subject: [PATCH] Update control-asset-access.mdx (#59) --- docs/issuing-assets/control-asset-access.mdx | 26 ++++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/issuing-assets/control-asset-access.mdx b/docs/issuing-assets/control-asset-access.mdx index 3160cf000..effe19bae 100644 --- a/docs/issuing-assets/control-asset-access.mdx +++ b/docs/issuing-assets/control-asset-access.mdx @@ -6,7 +6,7 @@ sidebar_position: 20 import { CodeExample } from "@site/src/components/CodeExample"; import { Alert } from "@site/src/components/Alert"; -# Issuing and distribution accounts +## Issuing and distribution accounts It is best practice on the Stellar network to create two accounts when issuing an asset: 1) the issuing account and 2) the distribution account. @@ -18,17 +18,17 @@ Note that you can also issue an asset by creating an offer or liquidity pool dep It is best practice to issue an asset by sending it from the issuing account to a distribution account for two main reasons: security and auditing. -## Security +### Security The distribution account will be a hot account, meaning that some web service out there has direct access to sign its transactions. For example, if the account you're distributing from is also the issuing account and it is compromised by a malicious actor, the actor can now issue as much of the asset as they want. If the malicious actor redeems the newly issued tokens with an anchor service, the anchor may not have the liquidity to support the customer withdrawals. Stakes are lower if you use a distribution account- if the distribution account is compromised, you can freeze the account’s asset balance and start with a new distribution account without changing the issuing account. -## Auditing +### Auditing Using a distribution account is better for auditing because an issuing account can’t actually hold a balance of its own asset. Sending an asset back to its issuing account burns (deletes) the asset. If you have a standing inventory of the issued asset in a separate account, it’s easier to track and can help with bookkeeping. -# Naming an asset +## Naming an asset One thing you must decide when issuing an asset is what to call it. An asset code is the asset’s identifying code. There are three possible formats: Alphanumeric 4, Alphanumeric 12, and liquidity pool shares. @@ -40,17 +40,17 @@ Learn about liquidity pool shares in the [Liquidity Pool Encyclopedia Entry](../ Provided it falls into one of these buckets, you can choose any asset code you like. That said, if you’re issuing a currency, you should use the appropriate ISO 4217 code, and if you’re issuing a stock or bond, the appropriate ISIN number. Doing so makes it easier for Stellar interfaces to properly display and sort your token in their listings and allows potential token holders to understand what your token represents. -# Controlling access to an asset with flags +## Controlling access to an asset with flags When you issue an asset on Stellar, anyone can hold it by default. In general, that’s a good thing: easy access means better reach and better liquidity. 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 are created on the account level using a `set_options` operation. They can be set at any time in the life cycle of an asset, not just when you issue it. -## Flag types +### Flag types The (0xn) next to each flag type denotes the bit settings for each flag. -### Authorization Required (0x1) +#### Authorization Required (0x1) 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 and to approve trustlines. @@ -61,7 +61,7 @@ There are two levels of authorization an asset issuer can grant using the `Set_T - `AUTHORIZED`: signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders. - `AUTHORIZED_TO_MAINTAIN_LIABILITIES`: denotes limited authorization that allows an account to maintain current orders but not to otherwise transact with the asset. -### Authorization Revocable (0x2) +#### Authorization Revocable (0x2) 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 transferring or trading the asset and cancels the account’s open orders for the asset. @@ -75,7 +75,7 @@ There are three levels of authorization an asset issuer can remove using the `Se - `AUTHORIZED_TO_MAINTAIN_LIABILITIES`: denotes limited authorization that allows an account to maintain current orders but not to otherwise transact with the asset. - `CLAWBACK_ENABLED`: enables the issuing account to take back (burning) all of the asset. See our [section on Clawbacks](../encyclopedia/clawbacks) for more information. -### Clawback Enabled (0x8) +#### Clawback Enabled (0x8) With the `AUTHORIZATION_CLAWBACK_ENABLED` flag set, any subsequent trustlines established with this account will have clawbacks enabled. @@ -83,15 +83,15 @@ Read more about clawbacks in the [Clawback Encyclopedia Entry](../encyclopedia/c Note that this flag requires that revocable is also set. -### Authorization Immutable (0x4) +#### Authorization Immutable (0x4) With this setting, none of the other authorization flags (`AUTHORIZATION REQUIRED`, `AUTHORIZATION REVOCABLE`) 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 the ledger in an open and accessible state. -## Set Trustline Flag operation +### Set Trustline Flag operation The issuing account can configure various authorization and trustline flags for individual trustlines to an asset. 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, this is the liquidity pool’s unique ID. -## Example flow +### Example flow Let’s look at how an issuer of a regulated asset might use the `AUTHORIZED_TO_MAINTAIN_LIABILITIES` flag. @@ -109,7 +109,7 @@ Here’s a payment from A to B sandwiched between `set_trust_line_flags` operati The authorization sandwich allows the issuer to inspect the specific 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 +### Sample code In the following code samples, proper error checking is omitted. However, you should always validate your results, as there are many ways that requests can fail. Refer to the Error Handling Encyclopedia Entry for tips on error management strategies.