This is the docs specimen page. Ideally, it will help ensure we implement everything we need to implement.

It’s pretty typical for docs start with writing like this and to have a lot of words. So a primary goal here: make sure the page looks good with a lot of words. For instance:

In Stellar, an asset is really just a credit from a particular account. When you trade US dollars on the Stellar network, you don’t actually trade US dollars—you trade US dollars credited from a particular account. Often, that account will be a bank, but if your neighbor had a banana plant, they might issue banana assets that you could trade with other people.

Here’s a quote

Here’s where I elaborate

After that little bit of text, I actually start writing more about that main point under this h3. I’m explaining more about that main point, and it should be clear that what I’m saying now is nested under that main point. I’ve got a few things I want to highlight about it, and this is just the first of those thing.

Here’s where I elaborate more

I’m going to try to give an example here of the things get used in docs, starting with this unordered list of common markdown:

• Paragraph and headings (h1, h2, h3)
• Unordered lists
  • Unordered lists with nesting
    • Unordered lists with second-level nesting
    • Another point so we can see how that looks.
• Ordered lists
  • Which we’ll look at below
• Tables
• Inline code
  • Code blocks
  • Another point so we can see how that looks
• Block Quotes
• Definition lists
• Line break
• Images
  • Images with a caption

I’m going to start pulling examples from docs at this point to illustrate some of these needs. First, a table. I have a feeling these are going to be pretty common.

Now we’ll add a big chunk of text because, like I said, these docs tend to be fairly text heavy.

To issue a new type of asset, all you need to do is choose a code. It can be any combination of up to 12 letters or numbers, but you should use the appropriate ISO 4217 code (e.g. USD for US dollars). Once you’ve chosen a code, you can begin paying people using that asset code. You don’t need to do anything to declare your asset on the network.

However, other people can’t receive your asset until they’ve chosen to trust it. Because a Stellar asset is really a credit, you should trust that the issuer can redeem that credit if necessary later on. You might not want to trust your neighbor to issue banana assets if they don’t even have a banana plant, for example.

An account can create a trustline, or a declaration that it trusts a particular asset, using the change trust operation. A trustline can also be limited to a particular amount. If your banana-growing neighbor only has a few plants, you might not want to trust them for more than about 200 bananas.

Once you’ve chosen an asset code and someone else has created a trustline for your asset, you’re free to start making payment operations to them using your asset. If someone you want to pay doesn’t trust your asset, you might also be able to use the distributed exchange.

More on that: a short code example

Here’s a short code example:

var astroDollar = new StellarSdk.Asset(
  "AstroDollar",
  "GC2BKLYOOYPDEFJKLKY6FNNRQMGFLVHJKQRGNSSRRGSMPGF32LHCQVGF",
);

More on that: a longer code example

Here’s a longer example in Javascript, Java, and Go:

var StellarSdk = require("stellar-sdk");
StellarSdk.Network.useTestNetwork();
var server = new StellarSdk.Server("https://horizon-testnet.stellar.org");

// Keys for accounts to issue and receive the new asset
var issuingKeys = StellarSdk.Keypair.fromSecret(
  "SCZANGBA5YHTNYVVV4C3U252E2B6P6F5T3U6MM63WBSBZATAQI3EBTQ4",
);
var receivingKeys = StellarSdk.Keypair.fromSecret(
  "SDSAVCRE5JRAI7UFAVLE5IMIZRD6N6WOJUWKY4GFN34LOBEEUS4W2T2D",
);

// Create an object to represent the new asset
var astroDollar = new StellarSdk.Asset("AstroDollar", issuingKeys.publicKey());

// First, the receiving account must trust the asset
server
  .loadAccount(receivingKeys.publicKey())
  .then(function(receiver) {
    var transaction = new StellarSdk.TransactionBuilder(receiver)
      // The `changeTrust` operation creates (or alters) a trustline
      // The `limit` parameter below is optional
      .addOperation(
        StellarSdk.Operation.changeTrust({
          asset: astroDollar,
          limit: "1000",
        }),
      )
      // setTimeout is required for a transaction
      .setTimeout(100)
      .build();
    transaction.sign(receivingKeys);
    return server.submitTransaction(transaction);
  })

  // Second, the issuing account actually sends a payment using the asset
  .then(function() {
    return server.loadAccount(issuingKeys.publicKey());
  })
  .then(function(issuer) {
    var transaction = new StellarSdk.TransactionBuilder(issuer)
      .addOperation(
        StellarSdk.Operation.payment({
          destination: receivingKeys.publicKey(),
          asset: astroDollar,
          amount: "10",
        }),
      )
      // setTimeout is required for a transaction
      .setTimeout(100)
      .build();
    transaction.sign(issuingKeys);
    return server.submitTransaction(transaction);
  })
  .catch(function(error) {
    console.error("Error!", error);
  });

Another thing that will be fairly common: block quotes. Short stuff gets this treatment. Longer stuff will end up looking like this:

# stellar.toml example asset
[[CURRENCIES]]
code="GOAT"
issuer="GD5T6IPRNCKFOHQWT264YPKOZAWUMMZOLZBJ6BNQMUGPWGRLBK3U7ZNP"
display_decimals=2
name="goat share"
desc="1 GOAT token entitles you to a share of revenue from Elkins Goat Farm."
conditions="There will only ever be 10,000 GOAT tokens in existence. We will distribute the revenue share annually on Jan. 15th"
image="https://pbs.twimg.com/profile_images/666921221410439168/iriHah4f.jpg"

Elaborating on the third point

Again, there’s going to be some text for looks. This time, we’ll also try out an ordered list.

Accounts have several flags related to issuing assets.

If you’d like to control who can be paid with your asset, or if your asset has some special purpose requiring sign-off from you, use the AUTHORIZATION REQUIRED flag, which requires that the issuing account also approves a trustline before the receiving account is allowed to be paid with the asset.

AUTHORIZATION REVOCABLE flag allows you to freeze assets you issued in case of theft or other special circumstances. This can be useful for national currencies, but is not always applicable to other kinds of assets.

For most cases, you should avoid setting AUTHORIZATION REVOCABLE on your asset. In the past, some issuers have used the AUTHORIZATION REVOCABLE flag in order to impose lock-up periods. However, this is a problematic mechanism because it does not provide the user any guarantees with regard to when or if the assets will be unlocked.

More importantly though, it requires a lot of effort to undo once it has been set. This is because if AUTHORIZATION REVOCABLE or AUTHORIZATION REQUIRED is disabled on an asset, it has no effect on existing user accounts. In order to be able to send your asset to existing accounts after these flags have been turned off, you will still need to run the Allow Trust operation for each existing user account. This requires creating a transaction with the following operations for every existing user account:

1. Set Options to set the flags on the issuing account to 0x1 to enable AUTHORIZATION REQUIRED. This is necessary because you cannot run the Allow Trust operation without AUTHORIZATION REQUIRED being set on your issuing account.
2. Allow Trust on the existing user’s account in order to authorize it. Note: You can actually place as many as MAX OPERATIONS PER TRANSACTION - 2 (currently the maximum is 100) Allow Trust operations for different accounts to minimize the number of transactions submitted to the network.
3. Set Options to set the flags on the issuing account to 0x0 to disable AUTHORIZATION REQUIRED.
   1. If I had more points to make about Set Options, I’d start listing those here.
   2. But the truth is, we’ve already covered it pretty well above.
      1. Do we need to cover second-level nesting here?
      2. Probably, though I am not a fan of it most of the time
      3. It feels pretty complicated, and my brain can’t process the lower levels
   3. I just can’t figure out how they relate to top level, two levels up. Not without some thought, at least.

There would probably be some text here for emphasis. I’m putting some to see how it looks. Imagine the above list needed some kind of poignant conclusion. This is that.

Yet more on that third point

When a user would like to redeem their asset off of the Stellar Network (such as receiving cold, hard cash for an asset representing a physical currency), the process takes places in two steps:

1. On the Stellar Network, the holder of the asset (i.e. the account with the trustline for the asset) sends funds back to the issuing account via a Payment operation.
2. Outside of the network, the Asset issuer provides liquidity, such as handing over cash at a cashier or ATM.

It’s of note that when tokens are sent back to the issuing (original source) account, they are removed from the global supply of tokens. As an asset issuer you may not want this behavior, and you can instead establish a distribution account which establishes the first trustline with the issuing account. This has the benefit of also setting an initial monetary supply for your asset, and doesn’t cause your asset’s monetary supply to grow or shrink each time that payments are sent from or to the issuing account, respectively.

Regardless of which strategy you use for managing your token’s supply, as an asset issuer it is very important to make it clear to asset holders to send the asset back to a specified account of yours, and to provide information on how and when you will provide liquidity upon redemption.

There are a few outstanding assets that we need to include, and I’m putting them here for now. This section will require a little bit of work before it’s useful.

Images

Not sure how we’re handling images for this specimen since there’s no folder to put them in.

They would take this form: ””

But I don’t have an image uploaded yet, so this needs work.

Diagrams

We’re using Mermaid for diagrams, and I think they’ll be pretty useful moving forward, especially as we try to describe how various SEP flows work. I’m not sure what we need to do to enable Mermaid, and what I’m attempting isn’t rendering correctly in my gist.

That said, here’s an attempt to create one of those diagrams using Mermaid:

There will be a newsletter signup at the bottom, I think. Putting it here so we can take a look.