Signatures should accompany transaction examples for the asset tutorial

[ozgunozerk]

Issue an asset tutorial: transactions are shown, but signature part is not shown. Signing part would be helpful due to:

• at first, I couldn’t understand why the operations were secure (for example trustline creation), because only public keys were used. I thought “anybody can create a trustline for any account then?”.
• Signing part would also convey the message who is initiating and responsible from the action (transaction).

[anataliocs]

Could you give me a bit more info here?

In the full code sample: https://developers.stellar.org/docs/tokens/how-to-issue-an-asset#full-code-sample

A keypair is created from a secret key:

var receivingKeys = StellarSdk.Keypair.fromSecret(
  "SDSAVCRE5JRAI7UFAVLE5IMIZRD6N6WOJUWKY4GFN34LOBEEUS4W2T2D",
);

Then is used to sign the change trustline transaction

server
  .loadAccount(receivingKeys.publicKey())
  .then(function (receiver) {
    var transaction = new StellarSdk.TransactionBuilder(receiver, {
      fee: 100,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      // 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); // <------------------------- Signed here
    return server.submitTransaction(transaction);
  })
  .then(console.log)

Are you referring to this code fragment:
https://developers.stellar.org/docs/tokens/how-to-issue-an-asset#approve-distributor-trustline

We commonly use this pattern where isolated code fragments are shown for brevity and then a complete example is displayed.

Let me know if this resolves your question @ozgunozerk

[ozgunozerk]

Hey @anataliocs , sure I can provide more info. I'm aware of the complete example is provided at the end, and there is sign() method present there.

The reason I created this issue is, back when I was reading your documentation, this step confused me, and without proceeding to the next part in the page, I thought that I first have to figure out what is confusing me.

Now that I read it again, I can still see why I got confused back then.

The wording and especially the headings/subheadings of the page conveyed the wrong message to me. I understand and agree that for brevity purposes, the chunks should be displayed instead of the full code.

However, let me be more concrete here. Here is the section from your docs:

# Network transactions
## Establish distributor trustline

Accounts must establish a [trustline](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines) with the issuing account to hold that issuer’s asset. This is true for all assets except for the network’s native token, [Lumens](https://developers.stellar.org/docs/learn/fundamentals/lumens).

And then comes the code piece:

const StellarSdk = require("stellar-sdk");
const server = new StellarSdk.Horizon.Server(
  "https://horizon-testnet.stellar.org",
);
const account = await server.loadAccount(distributorKeypair.publicKey());

const transaction = new StellarSdk.TransactionBuilder(account, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  // The `changeTrust` operation creates (or alters) a trustline
  .addOperation(
    StellarSdk.Operation.changeTrust({
      asset: astroDollar,
      limit: "1000", // optional
      source: distributorKeypair.publicKey(),
    }),
  )
  .setTimeout(100)
  .build();

And due to the sub-heading: Establish distributor trustline, I expect this chunk of code is establishing distributor trustline, but in fact, it doesn't. It just creates the transaction necessary for it. To establish the trustline, it has be signed, and then sent. Maybe before the code piece, a sentence can be inserted, something along the lines: here is how to create such a transaction, that should later be signed and broadcasted to the network.

If the approach and wording suits, I can gladly open a PR.

[ozgunozerk]

Btw, I tend to overthink these things to maximize the comfort of the reader, and I am inclined to overkill it. If you think the docs are good as is regarding this, feel free to close this issue :)

This was only a nitpick 👍

[anataliocs]

No I totally appreciate the fresh eyes. I support anything to help folx navigate the docs b/c I quickly scan docs and can agree contextual clues and specificity does add up and help the DX