Skip to content

docs: replace stale cashout script with swarm-cli in "Managing uncashed cheques" #836

Description

@yjkellyjoo

Problem

The "Managing uncashed cheques" section of Cashing Out (docs/bee/working-with-bee/cashing-out.md, lines 220–261) is stale in two ways:

  1. It instructs users to wget an unaudited third-party gist, chmod +x it, and run it. The script dates from 2020 and only works on Linux/macOS.
  2. It closes with an :::info callout asking Windows users to contribute a cashout script, pointing at ethersphere/bee#1092.

bee#1092 was closed in July 2021. In this comment, @agazso resolved the request: swarm-cli already cashes out cheques and runs on Windows, with Bee Dashboard as a GUI alternative. @acud closed the issue on those grounds. We are still soliciting a contribution that was answered five years ago.

This also contradicts our own docs. docs/bee/working-with-bee/introduction.md:23 already tells users they can "use the swarm-cli command line tool to … cash out your cheques", and docs/bee/working-with-bee/swarm-cli.md:10 calls swarm-cli "the recommended method for interaction with your Bee node from the command line" — yet no page in docs/ contains a single swarm-cli cheque command.

Proposed fix

Rewrite only the "Managing uncashed cheques" section of docs/bee/working-with-bee/cashing-out.md. The curl-based "Cashing out Cheques (SWAP)" section above it documents the raw Bee API and should stay as-is.

Keep lines 209–218 verbatim — the two paragraphs explaining what a cheque is and why holding an uncashed one is risky are conceptual and still accurate.

Keep the closing :::info about swap-swear-and-swindle (lines 263–267).

Replace lines 220–261 with swarm-cli guidance covering:

  • A lead sentence recommending swarm-cli, linking to the existing ./swarm-cli.md page, noting it works on Linux, macOS and Windows — this replaces the Windows callout rather than leaving a hole where it was.
  • Install: npm install --global @ethersphere/swarm-cli
  • List uncashed cheques: swarm-cli cheque list — note that No uncashed cheques found. means there is nothing to cash (carries over the intent of the existing :::info at line 247).
  • Cash out all: swarm-cli cheque cashout --all
  • Cash out all above a threshold: swarm-cli cheque cashout --all --minimum <PLUR>
  • Cash out a single peer: swarm-cli cheque cashout --peer <peer-address>
  • A note that swarm-cli targets http://localhost:1633 by default, retargetable via --bee-api-url or the BEE_API_URL env var.
  • One line pointing at Bee Dashboard as the GUI option — still actively maintained, and its repo description is literally "helps users to setup their Bee node and do actions like cash out cheques".

The existing :::important at lines 52–56 ("do not cash out too regularly") already covers cadence — don't repeat it.

Verified command surface

Checked against ethersphere/swarm-cli@master source rather than the 2021 comment (the flags there are still correct, but it never mentions cheque list or the PLUR unit):

Command Source Options
swarm-cli cheque list (alias ls) src/command/cheque/list.ts -m, --minimum <PLUR> (default 0)
swarm-cli cheque cashout (alias co) src/command/cheque/cashout.ts -a, --all / -p, --peer <address> (mutually exclusive, one required); -m, --minimum <PLUR> (default 1); --gas-limit, --gas-price (wei)
global src/config.ts --bee-api-url (default http://localhost:1633, env BEE_API_URL)

Two things to get right:

  • -m/--minimum is in PLUR, not xBZZ (1 PLUR = 1e-16 xBZZ). Consistent with cashing-out.md:34 and docs/references/tokens.md:21.
  • -m only filters on the --all path — cashout.ts ignores it when --peer is given. Don't imply otherwise.

Out of scope

  • static/llms.txt:41 needs no change — its description ("Withdraw earnings from SWAP cheques") stays accurate, and no page is added, renamed, or removed.
  • sidebars.js / docusaurus.config.mjs — no structural change.
  • docs/bee/working-with-bee/swarm-cli.md:16 has an unrelated pre-existing defect (a dangling * Add stake: bullet with no command after the colon). Worth a separate issue.

Acceptance criteria

  • grep -n "1092\|ralph-pichler\|cashout.sh" docs/bee/working-with-bee/cashing-out.md returns nothing.
  • The section documents swarm-cli cheque list and swarm-cli cheque cashout with correct flags and the PLUR unit.
  • The ## Managing uncashed cheques heading is unchanged, so the existing #managing-uncashed-cheques anchor still resolves.
  • npm run build:check passes — MDX parses, no unclosed admonition, new links resolve, the removed gist link is gone.
  • Follows CODING.md: one sentence per line, no unrelated reflowing outside the replaced range.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions