Skip to content

About

Magit-style Emacs interface for the Stellar CLI: transient menus, transaction and multisig buffers, Soroban contract calls, and a tutorial checked against the CLI

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

stellar-mode

https://github.com/hpmaxi/stellar-mode/actions/workflows/ci.yml/badge.svg

An Emacs interface for the Stellar CLI (stellar), in the style of Magit. Transient menus build the command, the CLI runs it, and every call is logged, so you learn the CLI while you use Emacs.

It includes a tutorial that goes from a funded testnet account to a Soroban contract with state and a payment signed by two keys. Each step can be done from the menus or typed in a shell; the tutorial asks the CLI whether the step is really done.

Features

  • Tutorial checked against the CLI (M-x stellar-walkthrough). Fifteen steps: tools, network, identities, Friendbot, a Soroban project, build, deploy, a contract call, a counter contract with a constructor and state, a 2-of-2 account and a payment signed by both keys. v (“I did it”) asks the CLI or the ledger whether the step is done, and the tutorial resumes at the first step that is not.
  • Transaction buffer. Decodes an envelope, shows each operation with its fields and the threshold it needs, and each signature with the identity that made it. Signs, simulates, bumps the sequence number and sends.
  • Multisig view. Thresholds, master weight and signers of an account. Each change builds a set-options transaction for you to sign with enough keys and send. A change that leaves a threshold out of reach is refused.
  • Contract calls from the spec. stellar contract info interface tells the package the type of each argument, and each type gets its own prompt. Integers stay strings, so i128 values are exact. A call built for signing is simulated first; the transaction buffer shows its resource fee and each address that still has to authorize it.
  • Contract development. stellar contract init, build in a compilation buffer, deploy with an alias and constructor arguments.
  • Mainnet guard. Every command that signs or submits goes through one check that identifies the network by its passphrase, including aliases, environment variables and .env files. Mainnet needs a typed “yes” for each command, and the menus and buffers show its name in upper case, in red.
  • Log. Each CLI call with its exit code, stdout and stderr in *stellar-log*, with secret keys and seed phrases redacted.
  • Thing at point. Accounts, contracts, muxed accounts, signer keys and secret keys (with their checksum), transaction hashes and envelope XDR.

Requirements

  • Emacs 29.1 or newer and transient 0.7 or newer.
  • stellar-cli 27 or newer.
  • For the contract steps: Rust with the wasm32v1-none target.

The Nix flake provides all of them on macOS.

Try it

git clone https://github.com/hpmaxi/stellar-mode.git
cd stellar-mode
nix run .#demo

Without a clone, nix run github:hpmaxi/stellar-mode runs the same demo from the Nix store.

The demo starts Emacs 30 with a small base config: Zenburn, Vertico, Marginalia, Orderless, Consult, Embark, Magit, Eglot with rust-analyzer, and agent-shell with Claude Code. C-c a starts Claude Code in the tutorial directory with the Stellar agent skills linked into .claude/skills.

To keep your own keys out of it, point the CLI at a throwaway config directory first. STELLAR_CONFIG_HOME changes only where the CLI keeps its identities and networks; XDG_CONFIG_HOME would also hide your Nix and Git settings.

export STELLAR_CONFIG_HOME=/tmp/stellar-play
nix run .#demo

See docs/manual-testing.md for a walk through every feature.

Installation

With package-vc (Emacs 29.1+):

(package-vc-install "https://github.com/hpmaxi/stellar-mode")

With use-package and a local checkout:

(use-package stellar-mode
  :load-path "/path/to/stellar-mode"
  :bind (("C-c s" . stellar-dispatch)
         ("C-c W" . stellar-walkthrough)
         ("C-c S" . stellar-at-point-menu)))

The package does not bind any key by itself. M-x stellar (an alias of stellar-dispatch) opens the main menu, which reaches every other command.

Menus and keys

Main menu (stellar-dispatch)

The heading shows the network and source identity that commands use. Commands use them without asking, and ask for an identity only when there is no source. Press C-u before a command’s key to choose another network or identity for that call.

KeyCommand
-nSession network (press again for the CLI default)
-sSession source identity (press again for the CLI default)
cContracts: init, build, deploy, invoke, read storage
iCall a contract function
tOpen a transaction envelope
mMultisig view of an account
kIdentities: list, generate (C-u also funds), fund
nNetworks: session network, health, local container
lLog of CLI calls
xStop a running command (only while one runs)
gForget cached data and read the CLI settings again
WTutorial
eStellar Expert: account, contract, transaction
.Actions for the thing at point

The local container menu (n c) starts a Stellar quickstart container for the local network, or with C-u for testnet, futurenet or pubnet. -n names the container and -p maps its ports; k stops a container by name.

Identities (stellar-keys-mode)

k l in the main menu lists the identities of the CLI config.

KeyAction
fFund the identity at point with Friendbot
c wCopy its address
m RETOpen its multisig view
gRead the identities again

Transaction buffer (stellar-tx-mode)

The network is chosen when the buffer opens (call stellar-tx-open with C-u to pick it), and N changes it. Opening the same envelope on the same network again shows its buffer. b refuses an envelope that the network already applied, since the copy would run the same operations again. Killing the buffer, or quitting Emacs, while it holds signatures that were not copied, saved or sent asks first.

KeyAction
sSign with an identity
xSimulate a contract call and keep the assembled envelope
bSet the next sequence number and remove the signatures
uGo back to the envelope before the last sign or change
PSend
eOpen the sent transaction in Stellar Expert
wCopy the XDR
WSave the XDR to a file, asking before replacing one
NUse another network for this transaction
gDecode again
?Menu of these commands

Multisig view (stellar-multisig-mode)

KeyAction
aAdd a signer with a weight
RETChange the weight of the signer at point
dRemove the signer at point
wCopy the address of the signer at point
tSet the low, medium and high thresholds
MSet the master key weight
gRead the account again
?Menu of these commands

Each change opens a transaction buffer: sign it with keys whose weights reach the current high threshold, then press P. The buffer shows the weight signed so far. C-u overrides the lockout check, after a typed confirmation. P reads the account once more and asks before sending a change that would lock it, since other changes may have been sent in the meantime.

Tutorial (stellar-walkthrough-mode)

KeyAction
RETMenu of the step at point
xDo the step with stellar-mode, then check it
oOpen the stellar-mode menu where the step lives
v“I did it”: ask the CLI whether the step is done
cCopy the CLI commands of the step
n pNext and previous step
gCheck every step again from the first
HRecord the hash of a payment sent from a shell
lLog of CLI calls
?Menu of these commands

Progress is saved per network and identity in stellar-walkthrough-state-file. The counter contract that the tutorial deploys is in tutorial/counter/.

Tables

In the identities, transaction and multisig tables, S sorts by the column at point, and { and } make that column narrower or wider. g reads the data again and keeps the order and the widths.

Development

nix develop -c make compile   # byte-compile, warnings are errors; keeps no .elc
nix develop -c make test      # ERT tests against the fake CLI
nix develop -c make check-cli # run the tests' CLI calls through the real CLI
nix develop -c make lint      # checkdoc and package-lint
nix develop -c make demo      # the demo, from the devshell
nix develop -c gitleaks dir . # look for secret keys and seed phrases

CI scans the whole history with gitleaks. .pre-commit-config.yaml scans staged changes; install it with prek install or pre-commit install.

The tests run against test/fixtures/fake-stellar, which accepts the argument syntax of stellar-cli 27 and answers with output captured from the real CLI. An argument the real CLI rejects makes it exit with code 2. The tutorial tests use test/fixtures/fake-stellar-tutorial, which keeps ledger state between calls.

make check-cli runs the tests, then runs each argument list they gave the fake through the real stellar on PATH, with an empty configuration, a network that does not exist and no Docker. It fails when the real CLI and the fake disagree on whether the arguments are valid.

CI also runs make compile test outside the devshell on Emacs 29.1 and 30.2. When Emacs has a transient older than 0.7, the Makefile installs the current one from GNU ELPA into .elpa/.

Donate

If stellar-mode is useful to you, you can send XLM or any Stellar asset to:

GAFSIUY5C5K7TSJO3ECCXXXE7EFQ7AZCHZGBKTDMLHGSP6QROPGVGRCQ

Check the address before you send: it is a public account key, so it starts with G and its checksum is valid. With the package loaded, put point on it and press M-x stellar-at-point-menu to open it in Stellar Expert.

License

MIT. See LICENSE.

About

Magit-style Emacs interface for the Stellar CLI: transient menus, transaction and multisig buffers, Soroban contract calls, and a tutorial checked against the CLI

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages