@0xsingularity/cli

The Singularity command line app — a guided terminal experience for the Singularity chain.

                                      .····::::::::·····
                           .          .···::::--:::::···.
                    .··················:::--------:::····
                 .·····::::--=++*+=--:-=*oo*++===---::···
              ..····::::--=+#@@@o+-····:=o@@@@o*+=--::···
             .·····:::--=+o@@@%*-·.     ·-*@@@@%*+=-::··.

    ▄▀▀▀▀ ▀▀█▀▀ █▄  █ ▄▀▀▀▄ █   █ █     ▄▀▀▀▄ █▀▀▀▄ ▀▀█▀▀ ▀▀█▀▀ █   █
    ▀▄▄▄    █   █ █ █ █  ▄▄ █   █ █     █▄▄▄█ █▄▄▄▀   █     █    ▀▄▀
    ▄▄▄▄▀ ▄▄█▄▄ █  ▀█ ▀▄▄▄▀ ▀▄▄▄▀ █▄▄▄▄ █   █ █  ▀▄ ▄▄█▄▄   █     █

         .············.. .·:----:::····::::-==:··
         ..········..      ·:=o%%%%#####%%%#*-:··..
         ...····..         .·:=o@@@@@@@@@@%*=-:·······...............
          .......           ··:-=*o%@@@#o*+=--:::················....
           ....             .··::-==++++===---:::::··············...
                             .··:::----==-----::::::·············..

  entropy to order   ·   v0.2.0

That is one frame of many. It fills the whole terminal, and the eye moves.

npm install -g @0xsingularity/cli
singularity

That is the whole setup. Node.js 18 or later is the only prerequisite. There is no toolchain to install, no config file to write, and no endpoint to look up.

What you see on launch

Run singularity. Three things happen, in order.

1. The eye turns. The Singularity gravity well fills the whole terminal and spins, sixty frames a second. The core stays dark. The ring around it burns white. Spiral arms sweep out of the ring and fade into the dark.

2. The wordmark resolves. After about a second and a half the letters of SINGULARITY appear out of the dark core. The field opens around them. The tagline and the version settle underneath.

3. Setup begins. The intro hands over to the guided screens.

Press any key to skip to the end of that.

Why it looks like this

The field is not decoration invented for a terminal. well() — the gravity well, with its void core at radius 0.12, its glowing ring at 0.30, and arms driven by time — is ported straight from the Singularity ASCII art engine. The terminal and the marketing surfaces draw the same shape from the same maths, down to the density ramp.

It is monochrome, because the brand is. Bright white is the signal register. Depth comes from ASCII density, never from hue. Sparse glyphs sit back in gray, dense glyphs burn white.

When it does not animate

NO_COLOR, SINGULARITY_NO_ANIMATION, and any output that is not a terminal all get one static frame of the eye with the wordmark already resolved, and no timer at all. The intro can never spin against a log file, and it can never hold a pipe open.

What you get

Run singularity with no arguments and it opens the guided app.

On a fresh machine it walks you through three screens: create a wallet, back it up, and get funds from the faucet. Then it drops you at the main menu.

On a machine that already has a wallet it opens straight to the main menu, with your address and your live balance at the top.

 ◆ SINGULARITY  ·  Main menu  ·  25aHPB…b3PM

 ╭──────────────────────────────────────────────────────────────╮
 │                                                              │
 │  Your address                                                │
 │  25aHPBn9kToSxe7fKSj5rnwTdMjnFFGBjH13ThfQb3PM                │
 │                                                              │
 │  Balance   2 SING                                            │
 │                                                              │
 │  ──────────────────────────────────────────────────────────  │
 │                                                              │
 │  ▸ Balance                                                   │
 │    Fund                                                      │
 │    Send                                                      │
 │    Look up an account                                        │
 │    Chain stats                                               │
 │    Recent transaction                                        │
 │    Deploy a program                                          │
 │    Settings                                                  │
 │    Quit                                                      │
 │                                                              │
 │  What you hold right now.                                    │
 │                                                              │
 ╰──────────────────────────────────────────────────────────────╯
 ↑ ↓  move      enter  select      esc  quit

Arrow keys move, enter selects, escape goes back.

Scripting

Give it a subcommand and it runs that command, prints the result, and exits. No screen, no prompt, no terminal required.

singularity wallet new
singularity fund 2
singularity balance
singularity transfer <TO> 1.5
singularity account <ADDRESS>
singularity stats
singularity tx <SIGNATURE>
singularity check-program target/deploy/my_program.so
singularity deploy target/deploy/my_program.so --yes
singularity doctor

Every command exits non-zero on failure and writes the reason to stderr.

| Option | Effect | |---|---| | --endpoint <URL> | use another endpoint for this run | | --wallet <FILE> | use another wallet file for this run | | --force, -f | overwrite something that already exists | | --yes, -y | answer every confirmation with yes |

To change the endpoint or the wallet file for every run, open Settings in the app. It saves them to ~/.config/singularity/settings.json.

Your wallet

One file, at ~/.config/singularity/id.json, written with owner-only permissions.

That file is the only copy of your key. The app says so in a screen you cannot skip past without acknowledging it. Nobody can restore it for you.

@0xsingularity/web3.js reads and writes the same file, so a wallet created here works in a script and the other way round.

Deploying a program

singularity deploy <file.so> runs three gates, in order:

1. The program check. This is the most valuable thing in the package. See below.
2. The build tools. Missing tools are installed once, on your confirmation, into ~/.config/singularity/toolchain. Nothing outside that directory changes and no shell profile is edited.
3. The deploy, driven through those managed tools over plain RPC.

The program check

The loader accepts ELF e_flags of 0x0 (SBPF v1) or the legacy 0x20 marker. It rejects the plain version encodings (1, 2, 3) that current build tools emit by default.

A program built with default settings deploys successfully and then never executes. There is no error at deploy time. Every instruction against it simply fails, later, for reasons that look like anything but the real cause.

singularity check-program target/deploy/my_program.so

The check runs automatically before every deploy and aborts before anything reaches the chain. This is chain issue #763.

Build so the program carries e_flags 0x0:

cargo build-sbf --arch v0

--arch v0 writes 0x0. The other arch values (v1/v2/v3) write 0x1/0x2/0x3, which the chain rejects. (Older toolchains spelled this --arch sbfv1; current cargo build-sbf rejects that and wants --arch v0.)

Other things worth knowing

• The token is SING. Every amount this app prints is in SING.
• Finality is one hop and under a second. Do not build logic on the difference between commitment levels.
• A deploy goes over plain RPC. This chain has no faster submission path for one, and the app already passes the right flag.
• 1 MiB transaction cap.
• Request caps — 100 addresses per multiple-account call, 256 calls per batch.

Develop

npm install
npm run typecheck
npm test          # 274 tests, none of them touch the network
npm run build

The logic lives in plain TypeScript modules under src/core and src/commands. The screens under src/ui are presentation only, built with ink. That split is why the wallet, the amounts, the faucet errors, the program check and the deploy path are all covered by tests that need neither a terminal nor a network.

Licence

MIT.