Skip to content

docs: mintlify nits - #2891

Open
ElliotFriend wants to merge 2 commits into
stellar:mainfrom
ElliotFriend:docs/mintlify-nits
Open

ElliotFriend wants to merge 2 commits into
stellar:mainfrom
ElliotFriend:docs/mintlify-nits

Conversation

@ElliotFriend

Copy link
Copy Markdown
Contributor

What

Follow-up to #2888 that brings cookbook/ in line with stellar-docs conventions:

  • Points links at current page paths: root-relative links, plus the guide pages renamed in Drop the language from guide page names stellar-docs#3113.
  • Starts every page at ##, labels output blocks as text, and drops "Note:" prefixes inside callouts.
  • Uses <Steps> in contract-lifecycle and payments-and-assets.
  • Gives each page its own description and fixes copy errors.
  • Fixes content:
    • The network's max_entry_ttl caps TTL extensions, not the CLI.
    • Payments step 5 sends 100 stroops, not 100 XLM.
    • Drops the obsolete --inflation-dest from the set-options example.
    • Fixes an undefined variable in tx-op-add.

No runnable bash block changed. Only two blocks marked cookbooktest.ignore were edited.

Why

stellar-docs copies cookbook/ onto developers.stellar.org as is, so anything that differs from the docs conventions shows up on the site and undoes fixes made there. Refs stellar/stellar-docs#3121.

Known limitations

  • The cookbook integration tests weren't run locally, because they need a local network.
  • The claimable-balance examples still use 2024 timestamps, while the page says timestamps must be in the future. Those blocks run as tests, so this is left for a follow-up.

- Use root-relative links and current page paths
- Start pages at h2, label output blocks as text, drop "Note:" callout prefixes
- Give each page its own description and fix copy errors
- Correct the TTL cap explanation and drop the obsolete --inflation-dest

Refs stellar/stellar-docs#3121
```

This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times).
This example extends the TTL by 535,679 ledgers, roughly 30 days at an average ledger close time of 5 seconds. The network's `max_entry_ttl` setting caps this value, and the CLI returns an error if you ask for more.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--ledgers-to-extend is an extend-to target counted from the current ledger, not an amount added to the remaining TTL. If the entry already has 400,000 ledgers left, this brings it to current + 535,679 (not ~935k), and if it already has more than 535,679 left, nothing changes. The previous wording ("as the new archival TTL") was accurate, and contract-lifecycle.mdx in this PR already describes it correctly ("to at least … from the current ledger").

Something like "This example extends the TTL to 535,679 ledgers from the current ledger, …" would fix it. The same sentence is in extend-contract-storage.mdx:18 and extend-contract-wasm.mdx:17.

```

This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times).
This example extends the TTL by 535,679 ledgers, roughly 30 days at an average ledger close time of 5 seconds. The network's `max_entry_ttl` setting caps this value, and the CLI returns an error if you ask for more.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the CLI returns an error if you ask for more" is only partly true. The CLI rejects --ledgers-to-extend > max_entry_ttl (extend.rs:181), but the network rejects extendTo > max_entry_ttl - 1. So a request of exactly max_entry_ttl passes the CLI check and then fails on the network as a malformed transaction instead of returning LedgersToExtendTooLarge. That's why the old docs gave 535,679 (the old max of 535,680 minus 1) as the maximum allowed value.

We could fix the docs to say the maximum is max_entry_ttl - 1, or I can change the CLI check to >= in a separate PR so this sentence becomes accurate.

Comment thread cookbook/tx-op-add.mdx
@@ -25,7 +24,7 @@ ASSET="USDC:$ISSUER_PK"

# first the issuer sets the options for being able to clawback and revoke the asset
stellar tx new set-options --inclusion-fee 1000 --source issuer --set-clawback-enabled --set-revocable --build-only \

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not new in this PR, but since these comments are being edited: a # comment line right after a \ continuation breaks the pipeline. The backslash-newline joins the comment onto the command line, the comment swallows the rest of it, and the next line starts with a bare |. Pasting this into bash or zsh gives syntax error near unexpected token '|'. The same applies to the sandwich example below.

Moving the comments into a list above the command block (or into prose) would make both examples runnable.

Comment thread cookbook/stellar-keys.mdx

```
```text
✅ Key saved with alias carol in ".config/soroban/identity/carol.toml"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not new in this PR, but this output (and cd .config/soroban/identity in step 2) still uses the legacy path. The CLI writes to ~/.config/stellar unless a legacy soroban directory already exists, so on a fresh install step 2 fails with "No such file or directory" and this output won't match. Worth switching both to .config/stellar/identity.

Comment thread cookbook/tx-new.mdx
So far, the examples of the CLI interacting with the network have used the `contract` command: uploading, deploying, and invoking contracts. Each of these is a different type of transaction, which must be signed and submitted to the network (and, for contract transactions, simulated first).

Technically these three are different operations, of which a transaction can contain up to 100 operations. However, in the case of contract related operations a transaction is limited to just one.
Technically, these are three different operations. A transaction can contain up to 100 operations, but a transaction with a contract operation can contain only that one.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this paragraph is being reworded: upload, deploy, and invoke aren't three different operations. They're all the same InvokeHostFunction operation with different host functions. Maybe something like "Technically, these all use the same operation, InvokeHostFunction, with different host functions."

Comment thread cookbook/tx-new.mdx
@@ -122,7 +122,6 @@ Configure account settings:
```sh
stellar tx new set-options \

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not new in this PR, but since this example is being edited: it sets --set-immutable on alice (line 135). That can't be undone. The account's auth flags can never change again, and the account can never be merged (ACCOUNT_MERGE_IMMUTABLE_SET). Someone copying this onto a real account would be stuck. I'd drop --set-immutable from the example, or add a warning callout.

Comment thread cookbook/stellar-keys.mdx
This guide walks you through generating, inspecting, and removing a Stellar identity using the CLI.

### 1. Generate a New Identity
## 1. Generate a New Identity

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: contract-lifecycle.mdx and payments-and-assets.mdx were converted to <Steps>, but this page uses hand-numbered ## 1. … ## 7. headings. Should it use <Steps> too, for consistency?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog (Not Ready)

Development

Successfully merging this pull request may close these issues.

2 participants