diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 00000000..0be02629 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,19 @@ +FROM mcr.microsoft.com/devcontainers/rust:1.0.9-1 + +ENV DEBIAN_FRONTEND=noninteractive \ + PKG_CONFIG_PATH='/usr/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/share/pkgconfig' \ + CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse \ + CARGO_INCREMENTAL=0 \ + SCCACHE_DIR=/home/vscode/.cache/sccache \ + SCCACHE_CONF=/home/vscode/.config/sccache/config \ + SCCACHE_DIRECT=true \ + RUSTC_WRAPPER=sccache \ + SCCACHE_CACHE_SIZE=5G \ + RUST_VERSION=1.81 + +RUN apt-get update && apt-get install -y \ + libdbus-1-dev \ + libudev-dev \ + pkg-config \ + openssl && apt-get clean && \ + rm -rf /var/lib/apt/lists/* diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..60a0970b --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,86 @@ +{ + "name": "Soroban Examples Devcontainer", + "dockerFile": "Dockerfile", + "context": "..", + "build": { + "args": { + "BUILDKIT_INLINE_CACHE": "1" + } + }, + "hostRequirements": { + "cpus": 4, + "memory": "16", + "storage": "32" + }, + "forwardPorts": [ + 4226 + ], + "portsAttributes": { + "4226": { + "label": "sccache" + } + }, + "features": { + "ghcr.io/devcontainers/features/common-utils:2.5.3": { + "configureZshAsDefaultShell": true + }, + "ghcr.io/devcontainers/features/rust:1.3.1": { + "targets": "wasm32-unknown-unknown", + "profile": "default", + "version": "1.81" + }, + "ghcr.io/devcontainers-extra/features/gh-release:1.0.25": { + "repo": "stellar/stellar-cli", + "binaryNames": "stellar", + "version": "22.6.0" + }, + "ghcr.io/rapidsai/devcontainers/features/sccache:25.6.1": { + "repository": "mozilla/sccache", + "version": "0.10.0" + } + }, + "customizations": { + "codespaces": { + "openFiles": [ + "README.md", + "FULL_HELP_DOCS.md", + "increment/src/lib.rs", + "increment/src/test.rs" + ] + }, + "vscode": { + "extensions": [ + "rust-lang.rust-analyzer", + "vadimcn.vscode-lldb", + "tamasfe.even-better-toml" + ], + "settings": { + "workbench.settings.editor": "json", + "workbench.settings.useSplitJSON": true, + "npm.autoDetect": "off", + "telemetry.feedback.enabled": false, + "workbench.tips.enabled": false, + "editor.codeLens": false, + "editor.minimap.enabled": false, + "terminal.integrated.useWslProfiles": false, + "terminal.integrated.sendKeybindingsToShell": true, + "terminal.integrated.allowChords": true, + "rust-analyzer.check.allTargets": false, + "rust-analyzer.cargo.allTargets": false, + "rust-analyzer.procMacro.attributes.enable": false, + "rust-analyzer.lens.enable": false, + "files.readonlyInclude": { + "**/.cargo/registry/src/**/*.rs": true, + "**/.cargo/git/checkouts/**/*.rs": true, + "**/lib/rustlib/src/rust/library/**/*.rs": true + } + } + } + }, + "initializeCommand": "", + "onCreateCommand": "chmod +x .devcontainer/post_start_cli_autocomplete.sh && chmod +x .devcontainer/post_attach_welcome_text.sh", + "updateContentCommand": "", + "postCreateCommand": "", + "postStartCommand": ".devcontainer/post_start_cli_autocomplete.sh", + "postAttachCommand": ".devcontainer/post_attach_welcome_text.sh" +} diff --git a/.devcontainer/post_attach_welcome_text.sh b/.devcontainer/post_attach_welcome_text.sh new file mode 100755 index 00000000..3fc31bc2 --- /dev/null +++ b/.devcontainer/post_attach_welcome_text.sh @@ -0,0 +1,25 @@ +#!/bin/bash +set -e + +clear + +echo " βš™οΈ Setup testnet:" +echo " stellar network use testnet" +echo "" +echo " πŸ†” Configure an Identity:" +echo " stellar keys generate --global alice --network testnet --fund" +echo " stellar keys address alice" +echo " stellar keys use alice" +echo "" +echo " πŸ› οΈ Build a contract(Replace 'alloc' with desired project):" +echo " stellar contract build --manifest-path $CODESPACE_VSCODE_FOLDER/alloc/Cargo.toml" +echo "" +echo " πŸ§ͺ Run tests | πŸ”¨Build Projects" +echo " ⚠️ make all in the root directory will fill up a 32GB storage instance" +echo " cd [Project] e.g. cd account" +echo " cargo test ⭐️ make all" +echo "" +echo " πŸ“– Stellar CLI Manual(cmd+click) πŸ”— https://developers.stellar.org/docs/tools/cli/stellar-cli" +echo " πŸ‘©β€πŸ”¬ Stellar Lab(cmd+click) πŸ”— https://lab.stellar.org/" + + diff --git a/.devcontainer/post_start_cli_autocomplete.sh b/.devcontainer/post_start_cli_autocomplete.sh new file mode 100644 index 00000000..c81d650e --- /dev/null +++ b/.devcontainer/post_start_cli_autocomplete.sh @@ -0,0 +1,22 @@ +#!/bin/bash +set -euxo pipefail + +# Add Stellar CLI to $PATH +chmod 644 ~/.bashrc && chmod 644 ~/.zshrc + +test -d /usr/local/bin/ && echo "/usr/local/bin/" >> ~/.zshrc +test -d /usr/local/bin/ && echo "/usr/local/bin/" >> ~/.bashrc + +export PATH="/usr/local/bin/":$PATH +echo "export PATH='/usr/local/bin/:$PATH'" >> ~/.zshrc +echo "export PATH='/usr/local/bin/:$PATH'" >> ~/.bashrc + +# Stellar CLI Auto-Complete +chmod 644 ~/.bashrc +echo "source <(stellar completion --shell bash)" >>~/.bashrc +chmod 644 ~/.zshrc +echo "source <(stellar completion --shell zsh)" >>~/.zshrc +echo "Enabled Stellar CLI auto-completion" + +echo " βœ… postStartCliAutocomplete.sh executed successfully" + diff --git a/.devcontainer/post_start_cli_autocomplete_test.bats b/.devcontainer/post_start_cli_autocomplete_test.bats new file mode 100644 index 00000000..76947e85 --- /dev/null +++ b/.devcontainer/post_start_cli_autocomplete_test.bats @@ -0,0 +1,42 @@ +#!/usr/bin/env bats + +setup() { + load 'test_helper.bats' + _tests_helper + _create_dir_file +} + +# executed after each test +teardown() { + _delete_dir_file +} + +@test "script executes successfully and configures PATH and autocompletion" { + # Copy the script to the temporary directory + cp "$(dirname "$BATS_TEST_FILENAME")/post_start_cli_autocomplete.sh" "${BATS_TMPDIR}/" + chmod +x "${BATS_TMPDIR}/post_start_cli_autocomplete.sh" + + # Set HOME to BATS_TMPDIR for the test + export HOME="${BATS_TMPDIR}" + + # Run the script and capture its output + run "${BATS_TMPDIR}/post_start_cli_autocomplete.sh" + + # Verify /usr/local/bin/ is appended to .bashrc and .zshrc files + assert_file_contains "${BATS_TMPDIR}/.bashrc" "/usr/local/bin/" + assert_file_contains "${BATS_TMPDIR}/.zshrc" "/usr/local/bin/" + + # Verify env PATH export in .bashrc and .zshrc + assert_file_contains "${BATS_TMPDIR}/.bashrc" $'export PATH=\'/usr/local/bin/' + assert_file_contains "${BATS_TMPDIR}/.zshrc" $'export PATH=\'/usr/local/bin/' + + # Verify stellar CLI completion is included in .bashrc and .zshrc + assert_file_contains "${BATS_TMPDIR}/.bashrc" "source <(stellar completion --shell bash)" + assert_file_contains "${BATS_TMPDIR}/.zshrc" "source <(stellar completion --shell zsh)" + + # Check script execution status is successful + assert_success + + # Check for success message on script execution + assert_output --partial "βœ… postStartCliAutocomplete.sh executed successfully" +} diff --git a/.devcontainer/test_helper.bats b/.devcontainer/test_helper.bats new file mode 100755 index 00000000..f5f92c69 --- /dev/null +++ b/.devcontainer/test_helper.bats @@ -0,0 +1,24 @@ +_tests_helper() { + echo "BATS LIB PATH: ${BATS_LIB_PATH}" + bats_load_library bats-support + bats_load_library bats-assert + bats_load_library bats-file +} + +_create_dir_file() { + temp_make + assert_dir_exist "${BATS_TMPDIR}" + echo "Temp: ${BATS_TMPDIR}" + + # Create empty bash and zsh config files in the temporary directory + touch "${BATS_TMPDIR}/.bashrc" + touch "${BATS_TMPDIR}/.zshrc" + + assert_file_exists "${BATS_TMPDIR}/.bashrc" + assert_file_exists "${BATS_TMPDIR}/.zshrc" +} + +_delete_dir_file() { + # Remove the files created during the test + rm -f "${BATS_TMPDIR}/.bashrc" "${BATS_TMPDIR}/.zshrc" +} diff --git a/.devcontainer/tests/build_devcontainer_ci.sh b/.devcontainer/tests/build_devcontainer_ci.sh new file mode 100755 index 00000000..6c05ff9c --- /dev/null +++ b/.devcontainer/tests/build_devcontainer_ci.sh @@ -0,0 +1,15 @@ +#!/bin/bash +set -e +# Define devcontainer configuration directory +devcontainer_dir=".devcontainer" + +# Define configuration file path +config_file="devcontainer.json" + +# Build the devcontainer +devcontainer build \ + --workspace-folder . \ + --config $devcontainer_dir/$config_file + + + diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..20eb78ac --- /dev/null +++ b/.dockerignore @@ -0,0 +1,50 @@ +# Basic ignores +**/target/* +**/build/* +**/.git +**/.github +**/.vscode +**/.DS_Store +**/node_modules +**/dist +**/pnpm-lock.yaml + +# Editor specific +.idea/ + +Dockerfile +.dockerignore +node_modules +npm-debug.log +dist +.git +.gitignore +.github + +# Logs +*.log + +# Temporary files +*.tmp +*.temp +*.swp +*.swo +*.bak +*.old + +# Editor directories and files +.vscode/ +*.code-workspace + +# OS-specific files +.DS_Store +Thumbs.db + +.env +.devpod-internal +build-devcontainer.sh +z-dc-build-info/* +devcontainer.md +assets/ +.run/ +.zshrc \ No newline at end of file diff --git a/.github/workflows/build-and-test-devcontainer.yml b/.github/workflows/build-and-test-devcontainer.yml new file mode 100644 index 00000000..0c1509f2 --- /dev/null +++ b/.github/workflows/build-and-test-devcontainer.yml @@ -0,0 +1,88 @@ +name: Build and Test DevContainer + +on: + push: + paths: + - '.devcontainer/' + pull_request: + paths: + - '.devcontainer/' + workflow_dispatch: + +jobs: + shellcheck-and-test: + + name: Shellcheck linting + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup PATH + run: | + echo ::notice title={Setup Permissions}::{Add permissions to .devcontainers/} + chmod -R +rwx .devcontainer + + echo ::notice title={Setup Workspace}::{Add .devcontainers/ to PATH} + echo "${{github.workspace}}/.devcontainer" >> "$GITHUB_PATH" + echo "${{github.workspace}}/.devcontainer/tests" >> "$GITHUB_PATH" + + - name: Run ShellCheck + uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 + env: + SHELLCHECK_OPTS: -s bash + with: + format: tty + severity: error + additional_files: post_start_cli_autocomplete.sh + scandir: "${{github.workspace}}/.devcontainer" + continue-on-error: true + + - name: Setup Bats and bats libs + id: setup-bats + uses: bats-core/bats-action@42fcc8700f773c075a16a90eb11674c0318ad507 + + - name: Test Devcontainer scripts + shell: bash + env: + BATS_LIB_PATH: ${{ steps.setup-bats.outputs.lib-path }} + run: bats .devcontainer/post_start_cli_autocomplete_test.bats + + build-with-devcontainer-cli: + name: Devcontainer CLI Build and Push Cache + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup PATH + run: | + echo ::notice title={Setup Permissions}::{Add permissions to .devcontainers/} + chmod -R +rwx .devcontainer + + echo ::notice title={Setup Workspace}::{Add .devcontainers/ to PATH} + echo "${{github.workspace}}/.devcontainer" >> "$GITHUB_PATH" + echo "${{github.workspace}}/.devcontainer/tests" >> "$GITHUB_PATH" + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20.x' + - run: npm install -g @devcontainers/cli + working-directory: ${{ github.workspace }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + with: + buildkitd-flags: true + cache-binary: 'true' + + - name: Test Devcontainer CLI Build + run: | + echo ::notice title={Building with Devcontainer CLI}::{Building Devcontainer} + + chmod +x ${{github.workspace}}/.devcontainer/tests/build_devcontainer_ci.sh + ${{github.workspace}}/.devcontainer/tests/build_devcontainer_ci.sh + + echo "### Devcontainer CLI Build Successful!!! :rocket:" >> $GITHUB_STEP_SUMMARY + env: + BUILDKIT_INLINE_CACHE: 1 + working-directory: ${{github.workspace}} diff --git a/.github/workflows/gitpod.yml b/.github/workflows/gitpod.yml deleted file mode 100644 index fede175a..00000000 --- a/.github/workflows/gitpod.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: Gitpod - -on: - push: - branches: [main, dev] - pull_request: - -concurrency: - group: ${{ github.workflow }}-${{ github.ref_protected == 'true' && github.sha || github.ref }} - cancel-in-progress: true - -jobs: - - complete: - if: always() - needs: [build-image] - runs-on: ubuntu-latest - steps: - - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') - run: exit 1 - - build-image: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - run: docker build -f .gitpod.Dockerfile . diff --git a/.github/workflows/validate-devcontainer-json.yml b/.github/workflows/validate-devcontainer-json.yml new file mode 100644 index 00000000..6aa841e4 --- /dev/null +++ b/.github/workflows/validate-devcontainer-json.yml @@ -0,0 +1,130 @@ +name: Validate Devcontainer Config and Validate JSON Schema + +on: + push: + paths: + - '.devcontainer/' + pull_request: + paths: + - '.devcontainer/' + workflow_dispatch: + +jobs: + validate-devcontainer-json: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup PATH + run: | + echo ::notice title={Setup Permissions}::{Add permissions to .devcontainers/} + chmod -R +rwx .devcontainer + + echo ::notice title={Setup Workspace}::{Add .devcontainers/ to PATH} + echo "${{github.workspace}}/.devcontainer" >> "$GITHUB_PATH" + echo "${{github.workspace}}/.devcontainer/tests" >> "$GITHUB_PATH" + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20.x' + - run: | + npm install ajv + npm install json-merge-patch --save + npm install ajv-keywords + npm install ajv-merge-patch --save + npm install ajv-formats + npm install ajv-errors + + - name: Stage JSON Schema Testing Area + run: | + mkdir -p schemas/ + cp "${{github.workspace}}/.devcontainer/devcontainer.json" schemas/ + + - name: Download DevContainer JSON Schemas + env: + DEVCONTAINER_BASE_SCHEMA: https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json + DEVCONTAINER_SCHEMA: https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json + DEVCONTAINER_FEATURE_SCHEMA: https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainerFeature.schema.json + DEVCONTAINER_CODESPACES_SCHEMA: https://raw.githubusercontent.com/microsoft/vscode/main/extensions/configuration-editing/schemas/devContainer.codespaces.schema.json + DEVCONTAINER_VSCODE_SCHEMA: https://raw.githubusercontent.com/microsoft/vscode/main/extensions/configuration-editing/schemas/devContainer.vscode.schema.json + VSCODE_MACHINE_SCHEMA: https://raw.githubusercontent.com/microsoft/vscode/refs/heads/main/extensions/configuration-editing/schemas/devContainer.vscode.schema.json + VSCODE_MACHINE_SCHEMA_REF: vscode://schemas/settings/machine + run: | + curl ${{env.DEVCONTAINER_BASE_SCHEMA}} | jq ". + {\"\$id\": \"${{env.DEVCONTAINER_BASE_SCHEMA}}\"}" > devContainer.base.schema.json + curl ${{env.DEVCONTAINER_SCHEMA}} | jq ". + {\"\$id\": \"${{env.DEVCONTAINER_SCHEMA}}\"}" > devContainer.schema.json + curl ${{env.DEVCONTAINER_FEATURE_SCHEMA}} | jq ". + {\"\$id\": \"${{env.DEVCONTAINER_FEATURE_SCHEMA}}\"}" > devContainerFeature.schema.json + curl ${{env.DEVCONTAINER_CODESPACES_SCHEMA}} | jq ". + {\"\$id\": \"${{env.DEVCONTAINER_CODESPACES_SCHEMA}}\"}" > devContainer.codespaces.schema.json + curl ${{env.DEVCONTAINER_VSCODE_SCHEMA}} | jq ". + {\"\$id\": \"${{env.DEVCONTAINER_VSCODE_SCHEMA}}\"}" > devContainer.vscode.schema.json + curl ${{env.VSCODE_MACHINE_SCHEMA}} | jq ". + {\"\$id\": \"${{env.VSCODE_MACHINE_SCHEMA_REF}}\"}" > devContainer.vscode.machine.schema.json + + jq '.allOf[0] = {"$ref" : "${{env.DEVCONTAINER_SCHEMA}}"}' devContainer.schema.json > devContainer.complete.schema.json + sed -i -e 's|json-schema.org/draft/2020-12/schema|json-schema.org/draft/2019-09/schema|g' devContainer.base.schema.json + sed -i -e 's|json-schema.org/draft-07/schema|json-schema.org/draft/2019-09/schema|g' devContainerFeature.schema.json + sed -i -e 's|json-schema.org/draft-07/schema|json-schema.org/draft/2019-09/schema|g' devContainer.codespaces.schema.json + sed -i -e 's|json-schema.org/draft-07/schema|json-schema.org/draft/2019-09/schema|g' devContainer.vscode.schema.json + sed -i -e 's|json-schema.org/draft-07/schema|json-schema.org/draft/2019-09/schema|g' devContainer.vscode.machine.schema.json + working-directory: schemas/ + + - name: Validate Devcontainer JSON Schema + uses: actions/github-script@v7 + with: + script: | + const Ajv2019 = require("ajv/dist/2019"); + const meta = require("ajv/dist/refs/json-schema-2019-09/meta/core"); + const metaSchema = require("ajv/dist/refs/json-schema-2019-09/schema"); + const metaValidation = require("ajv/dist/refs/json-schema-2019-09/meta/validation"); + const metaMetaData = require("ajv/dist/refs/json-schema-2019-09/meta/meta-data"); + const metaFormat = require("ajv/dist/refs/json-schema-2019-09/meta/format"); + const metaContent = require("ajv/dist/refs/json-schema-2019-09/meta/content"); + const metaApplicator = require("ajv/dist/refs/json-schema-2019-09/meta/applicator"); + + const path = require("path"); + const fs = require('fs'); + const addFormats = require("ajv-formats"); + var ajv = new Ajv2019({ + strict: "None", + strictRequired: "log", + strictTuples: "log", + strictTypes: "log", + strictSchema: "log", + allowUnionTypes: true, + allowMatchingProperties: true, + allowAdditionalProperties: true, + allowAdditionalItems: true, + allowEmptyObject: true, + allowMultipleTypes: true, + inlineRefs: true, + useDefaults: "empty", + coerceTypes: true, + verbose: true, + $data: true, + validateSchema: "log", + removeAdditional: "failing" + }); + let addKeywords = require("ajv-keywords/dist/definitions"); + addFormats(ajv); + addKeywords(ajv); + ajv.addMetaSchema(meta, "http://json-schema.org/draft/2019-09/schema#", false); + + ajv.addSchema(require("./schemas/devContainer.complete.schema.json"), ${{env.DEVCONTAINER_SCHEMA}}); + ajv.addSchema(require("./schemas/devContainerFeature.schema.json"), ${{env.DEVCONTAINER_FEATURE_SCHEMA}}); + ajv.addSchema(require("./schemas/devContainer.codespaces.schema.json"), ${{env.DEVCONTAINER_CODESPACES_SCHEMA}}); + ajv.addSchema(require("./schemas/devContainer.vscode.schema.json"), ${{env.DEVCONTAINER_VSCODE_SCHEMA}}); + ajv.addSchema(require("./schemas/devContainer.vscode.machine.schema.json"), "vscode://schemas/settings/machine"); + let validator = ajv.compile(require("./schemas/devContainer.base.schema.json"), ${{env.DEVCONTAINER_BASE_SCHEMA}}); + + const data = JSON.parse(fs.readFileSync(path.join(".", "schemas/devcontainer.json"))); + + if (validator(data)) { + console.log("devcontainer.json is fully validated"); + } else { + let error = validator.errors[0]; + console.error("Msg: " + error.message); + console.error("Keyword: " + error.keyword); + console.error("Error Schema: " + error.schema); + console.error("Schema name: " + error.parentSchema.$id); + } + + continue-on-error: true diff --git a/.gitignore b/.gitignore index 019e1a35..175ad1d7 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,8 @@ target/ .DS_Store .soroban test_snapshots +z-dc-build-info/* +**1pass.tmp** +.idea +.run/ +.zshrc diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile deleted file mode 100644 index 0f611f10..00000000 --- a/.gitpod.Dockerfile +++ /dev/null @@ -1,26 +0,0 @@ -FROM gitpod/workspace-full:latest - -# Remove the existing rustup installation before updating due to: -# https://github.com/gitpod-io/workspace-images/issues/933#issuecomment-1272616892 -RUN rustup self uninstall -y || true -RUN rm -rf .rustup -RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain none -y - -RUN rustup install 1.81 -RUN rustup target add --toolchain 1.81 wasm32-unknown-unknown -RUN rustup component add --toolchain 1.81 rust-src -RUN rustup default 1.81 - -RUN sudo apt-get update && sudo apt-get install -y binaryen - -# Enable sparse registry support, which will cause cargo to download only what -# it needs from crates.io, rather than the entire registry. -ENV CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse - -# Install tools -RUN /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -RUN brew install stellar-cli sccache cargo-watch - -ENV RUSTC_WRAPPER=sccache -ENV SCCACHE_CACHE_SIZE=5G -ENV SCCACHE_DIR=/workspace/.sccache diff --git a/.gitpod.yml b/.gitpod.yml deleted file mode 100644 index 5f37ace1..00000000 --- a/.gitpod.yml +++ /dev/null @@ -1,34 +0,0 @@ -image: - file: .gitpod.Dockerfile - -tasks: - # This "CLI - Testnet" task opens a terminal for you to interact with the - # testnet network. - - name: CLI - Testnet - # We specify some required environment variables for use on the testnet. - env: - # This can be set by the user, but this terminal is dedicated to testnet so set for convenience. - SOROBAN_RPC_URL: "https://soroban-testnet.stellar.org" - SOROBAN_NETWORK_PASSPHRASE: "Test SDF Network ; September 2015" - # To keep things tidy, we clear the terminal from the previous output. - command: | - clear - - name: CLI - Sandbox - init: | - make all - command: | - gp open README.md - gp open increment/src/lib.rs - gp open increment/src/test.rs - gp open README.md - stellar version -vscode: - extensions: - - rust-lang.rust-analyzer - - vadimcn.vscode-lldb - -ports: - # This port is open for "Something with cargo test I think"?? - - port: 4226 - visibility: private - onOpen: ignore diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 57650c39..00000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - // These settings exist to support the gitpod configuration. - "workbench.startupEditor": "none", - "rust-analyzer.cargo.buildScripts.useRustcWrapper": false, -} diff --git a/FULL_HELP_DOCS.md b/FULL_HELP_DOCS.md new file mode 100644 index 00000000..ee140f8e --- /dev/null +++ b/FULL_HELP_DOCS.md @@ -0,0 +1,2623 @@ +# Stellar CLI Manual + +This document contains the help content for the `stellar` command-line program. + +## `stellar` + +Work seamlessly with Stellar accounts, contracts, and assets from the command line. + +- Generate and manage keys and accounts +- Build, deploy, and interact with contracts +- Deploy asset contracts +- Stream events +- Start local testnets +- Decode, encode XDR +- More! + +For additional information see: + +- Stellar Docs: https://developers.stellar.org +- Smart Contract Docs: https://developers.stellar.org/docs/build/smart-contracts/overview +- CLI Docs: https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli + +To get started generate a new identity: + + stellar keys generate alice + +Use keys with the `--source` flag in other commands. + +Commands that work with contracts are organized under the `contract` subcommand. List them: + + stellar contract --help + +Use contracts like a CLI: + + stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- --help + +Anything after the `--` double dash (the "slop") is parsed as arguments to the contract-specific CLI, generated on-the-fly from the contract schema. For the hello world example, with a function called `hello` that takes one string argument `to`, here's how you invoke it: + + stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- hello --to world + + +**Usage:** `stellar [OPTIONS] ` + +###### **Subcommands:** + +* `contract` β€” Tools for smart contract developers +* `events` β€” Watch the network for contract events +* `env` β€” Prints the environment variables +* `keys` β€” Create and manage identities including keys and addresses +* `network` β€” Configure connection to networks +* `container` β€” Start local networks in containers +* `snapshot` β€” Download a snapshot of a ledger from an archive +* `tx` β€” Sign, Simulate, and Send transactions +* `xdr` β€” Decode and encode XDR +* `completion` β€” Print shell completion code for the specified shell +* `cache` β€” Cache for transactions and contract specs +* `version` β€” Print version information + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `-f`, `--filter-logs ` β€” Filter logs output. To turn on `stellar_cli::log::footprint=debug` or off `=off`. Can also use env var `RUST_LOG` +* `-q`, `--quiet` β€” Do not write logs to stderr including `INFO` +* `-v`, `--verbose` β€” Log DEBUG events +* `--very-verbose` β€” Log DEBUG and TRACE events +* `--list` β€” List installed plugins. E.g. `stellar-hello` +* `--no-cache` β€” Do not cache your simulations and transactions + + + +## `stellar contract` + +Tools for smart contract developers + +**Usage:** `stellar contract ` + +###### **Subcommands:** + +* `asset` β€” Utilities to deploy a Stellar Asset Contract or get its id +* `alias` β€” Utilities to manage contract aliases +* `bindings` β€” Generate code client bindings for a contract +* `build` β€” Build a contract from source +* `extend` β€” Extend the time to live ledger of a contract-data ledger entry +* `deploy` β€” Deploy a wasm contract +* `fetch` β€” Fetch a contract's Wasm binary +* `id` β€” Generate the contract id for a given contract or asset +* `info` β€” Access info about contracts +* `init` β€” Initialize a Soroban contract project +* `inspect` β€” (Deprecated in favor of `contract info` subcommand) Inspect a WASM file listing contract functions, meta, etc +* `upload` β€” Install a WASM file to the ledger without creating a contract instance +* `install` β€” (Deprecated in favor of `contract upload` subcommand) Install a WASM file to the ledger without creating a contract instance +* `invoke` β€” Invoke a contract function +* `optimize` β€” Optimize a WASM file +* `read` β€” Print the current value of a contract-data ledger entry +* `restore` β€” Restore an evicted value for a contract-data legder entry + + + +## `stellar contract asset` + +Utilities to deploy a Stellar Asset Contract or get its id + +**Usage:** `stellar contract asset ` + +###### **Subcommands:** + +* `id` β€” Get Id of builtin Soroban Asset Contract. Deprecated, use `stellar contract id asset` instead +* `deploy` β€” Deploy builtin Soroban Asset Contract + + + +## `stellar contract asset id` + +Get Id of builtin Soroban Asset Contract. Deprecated, use `stellar contract id asset` instead + +**Usage:** `stellar contract asset id [OPTIONS] --asset ` + +###### **Options:** + +* `--asset ` β€” ID of the Stellar classic asset to wrap, e.g. "USDC:G...5" +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract asset deploy` + +Deploy builtin Soroban Asset Contract + +**Usage:** `stellar contract asset deploy [OPTIONS] --asset --source-account ` + +###### **Options:** + +* `--asset ` β€” ID of the Stellar classic asset to wrap, e.g. "USDC:G...5" +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--alias ` β€” The alias that will be used to save the assets's id. Whenever used, `--alias` will always overwrite the existing contract id configuration without asking for confirmation + + + +## `stellar contract alias` + +Utilities to manage contract aliases + +**Usage:** `stellar contract alias ` + +###### **Subcommands:** + +* `remove` β€” Remove contract alias +* `add` β€” Add contract alias +* `show` β€” Show the contract id associated with a given alias +* `ls` β€” List all aliases + + + +## `stellar contract alias remove` + +Remove contract alias + +**Usage:** `stellar contract alias remove [OPTIONS] ` + +###### **Arguments:** + +* `` β€” The contract alias that will be removed + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config + + + +## `stellar contract alias add` + +Add contract alias + +**Usage:** `stellar contract alias add [OPTIONS] --id ` + +###### **Arguments:** + +* `` β€” The contract alias that will be used + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--overwrite` β€” Overwrite the contract alias if it already exists +* `--id ` β€” The contract id that will be associated with the alias + + + +## `stellar contract alias show` + +Show the contract id associated with a given alias + +**Usage:** `stellar contract alias show [OPTIONS] ` + +###### **Arguments:** + +* `` β€” The contract alias that will be displayed + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config + + + +## `stellar contract alias ls` + +List all aliases + +**Usage:** `stellar contract alias ls [OPTIONS]` + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract bindings` + +Generate code client bindings for a contract + +**Usage:** `stellar contract bindings ` + +###### **Subcommands:** + +* `json` β€” Generate Json Bindings +* `rust` β€” Generate Rust bindings +* `typescript` β€” Generate a TypeScript / JavaScript package +* `python` β€” Generate Python bindings +* `java` β€” Generate Java bindings + + + +## `stellar contract bindings json` + +Generate Json Bindings + +**Usage:** `stellar contract bindings json --wasm ` + +###### **Options:** + +* `--wasm ` β€” Path to wasm binary + + + +## `stellar contract bindings rust` + +Generate Rust bindings + +**Usage:** `stellar contract bindings rust --wasm ` + +###### **Options:** + +* `--wasm ` β€” Path to wasm binary + + + +## `stellar contract bindings typescript` + +Generate a TypeScript / JavaScript package + +**Usage:** `stellar contract bindings typescript [OPTIONS] --output-dir <--wasm |--wasm-hash |--contract-id >` + +###### **Options:** + +* `--wasm ` β€” Wasm file path on local filesystem. Provide this OR `--wasm-hash` OR `--contract-id` +* `--wasm-hash ` β€” Hash of Wasm blob on a network. Provide this OR `--wasm` OR `--contract-id` +* `--contract-id ` β€” Contract ID/alias on a network. Provide this OR `--wasm-hash` OR `--wasm` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--output-dir ` β€” Where to place generated project +* `--overwrite` β€” Whether to overwrite output directory if it already exists + + + +## `stellar contract bindings python` + +Generate Python bindings + +**Usage:** `stellar contract bindings python` + + + +## `stellar contract bindings java` + +Generate Java bindings + +**Usage:** `stellar contract bindings java` + + + +## `stellar contract build` + +Build a contract from source + +Builds all crates that are referenced by the cargo manifest (Cargo.toml) that have cdylib as their crate-type. Crates are built for the wasm32 target. Unless configured otherwise, crates are built with their default features and with their release profile. + +In workspaces builds all crates unless a package name is specified, or the command is executed from the sub-directory of a workspace crate. + +To view the commands that will be executed, without executing them, use the --print-commands-only option. + +**Usage:** `stellar contract build [OPTIONS]` + +###### **Options:** + +* `--manifest-path ` β€” Path to Cargo.toml +* `--package ` β€” Package to build + + If omitted, all packages that build for crate-type cdylib are built. +* `--profile ` β€” Build with the specified profile + + Default value: `release` +* `--features ` β€” Build with the list of features activated, space or comma separated +* `--all-features` β€” Build with the all features activated +* `--no-default-features` β€” Build with the default feature not activated +* `--out-dir ` β€” Directory to copy wasm files to + + If provided, wasm files can be found in the cargo target directory, and the specified directory. + + If ommitted, wasm files are written only to the cargo target directory. +* `--print-commands-only` β€” Print commands to build without executing them +* `--meta ` β€” Add key-value to contract meta (adds the meta to the `contractmetav0` custom section) + + + +## `stellar contract extend` + +Extend the time to live ledger of a contract-data ledger entry. + +If no keys are specified the contract itself is extended. + +**Usage:** `stellar contract extend [OPTIONS] --ledgers-to-extend --source-account ` + +###### **Options:** + +* `--ledgers-to-extend ` β€” Number of ledgers to extend the entries +* `--ttl-ledger-only` β€” Only print the new Time To Live ledger +* `--id ` β€” Contract ID to which owns the data entries. If no keys provided the Contract's instance will be extended +* `--key ` β€” Storage key (symbols only) +* `--key-xdr ` β€” Storage key (base64-encoded XDR) +* `--wasm ` β€” Path to Wasm file of contract code to extend +* `--wasm-hash ` β€” Path to Wasm file of contract code to extend +* `--durability ` β€” Storage entry durability + + Default value: `persistent` + + Possible values: + - `persistent`: + Persistent + - `temporary`: + Temporary + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout + + + +## `stellar contract deploy` + +Deploy a wasm contract + +**Usage:** `stellar contract deploy [OPTIONS] --source-account <--wasm |--wasm-hash > [-- ...]` + +###### **Arguments:** + +* `` β€” If provided, will be passed to the contract's `__constructor` function with provided arguments for that function as `--arg-name value` + +###### **Options:** + +* `--wasm ` β€” WASM file to deploy +* `--wasm-hash ` β€” Hash of the already installed/deployed WASM file +* `--salt ` β€” Custom salt 32-byte salt for the token id +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `-i`, `--ignore-checks` β€” Whether to ignore safety checks when deploying contracts + + Default value: `false` +* `--alias ` β€” The alias that will be used to save the contract's id. Whenever used, `--alias` will always overwrite the existing contract id configuration without asking for confirmation + + + +## `stellar contract fetch` + +Fetch a contract's Wasm binary + +**Usage:** `stellar contract fetch [OPTIONS] --id ` + +###### **Options:** + +* `--id ` β€” Contract ID to fetch +* `-o`, `--out-file ` β€” Where to write output otherwise stdout is used +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config + + + +## `stellar contract id` + +Generate the contract id for a given contract or asset + +**Usage:** `stellar contract id ` + +###### **Subcommands:** + +* `asset` β€” Deploy builtin Soroban Asset Contract +* `wasm` β€” Deploy normal Wasm Contract + + + +## `stellar contract id asset` + +Deploy builtin Soroban Asset Contract + +**Usage:** `stellar contract id asset [OPTIONS] --asset ` + +###### **Options:** + +* `--asset ` β€” ID of the Stellar classic asset to wrap, e.g. "USDC:G...5" +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract id wasm` + +Deploy normal Wasm Contract + +**Usage:** `stellar contract id wasm [OPTIONS] --salt --source-account ` + +###### **Options:** + +* `--salt ` β€” ID of the Soroban contract +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract info` + +Access info about contracts + +**Usage:** `stellar contract info ` + +###### **Subcommands:** + +* `interface` β€” Output the interface of a contract +* `meta` β€” Output the metadata stored in a contract +* `env-meta` β€” Output the env required metadata stored in a contract +* `build` β€” Output the contract build information, if available + + + +## `stellar contract info interface` + +Output the interface of a contract. + +A contract's interface describes the functions, parameters, and types that the contract makes accessible to be called. + +The data outputted by this command is a stream of `SCSpecEntry` XDR values. See the type definitions in [stellar-xdr](https://github.com/stellar/stellar-xdr). [See also XDR data format](https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr). + +Outputs no data when no data is present in the contract. + +**Usage:** `stellar contract info interface [OPTIONS] <--wasm |--wasm-hash |--contract-id >` + +###### **Options:** + +* `--wasm ` β€” Wasm file path on local filesystem. Provide this OR `--wasm-hash` OR `--contract-id` +* `--wasm-hash ` β€” Hash of Wasm blob on a network. Provide this OR `--wasm` OR `--contract-id` +* `--contract-id ` β€” Contract ID/alias on a network. Provide this OR `--wasm-hash` OR `--wasm` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--output ` β€” Format of the output + + Default value: `rust` + + Possible values: + - `rust`: + Rust code output of the contract interface + - `xdr-base64`: + XDR output of the info entry + - `json`: + JSON output of the info entry (one line, not formatted) + - `json-formatted`: + Formatted (multiline) JSON output of the info entry + + + + +## `stellar contract info meta` + +Output the metadata stored in a contract. + +A contract's meta is a series of key-value pairs that the contract developer can set with any values to provided metadata about the contract. The meta also contains some information like the version of Rust SDK, and Rust compiler version. + +The data outputted by this command is a stream of `SCMetaEntry` XDR values. See the type definitions in [stellar-xdr](https://github.com/stellar/stellar-xdr). [See also XDR data format](https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr). + +Outputs no data when no data is present in the contract. + +**Usage:** `stellar contract info meta [OPTIONS] <--wasm |--wasm-hash |--contract-id >` + +###### **Options:** + +* `--wasm ` β€” Wasm file path on local filesystem. Provide this OR `--wasm-hash` OR `--contract-id` +* `--wasm-hash ` β€” Hash of Wasm blob on a network. Provide this OR `--wasm` OR `--contract-id` +* `--contract-id ` β€” Contract ID/alias on a network. Provide this OR `--wasm-hash` OR `--wasm` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--output ` β€” Format of the output + + Default value: `text` + + Possible values: + - `text`: + Text output of the meta info entry + - `xdr-base64`: + XDR output of the info entry + - `json`: + JSON output of the info entry (one line, not formatted) + - `json-formatted`: + Formatted (multiline) JSON output of the info entry + + + + +## `stellar contract info env-meta` + +Output the env required metadata stored in a contract. + +Env-meta is information stored in all contracts, in the `contractenvmetav0` WASM custom section, about the environment that the contract was built for. Env-meta allows the Soroban Env to know whether the contract is compatibility with the network in its current configuration. + +The data outputted by this command is a stream of `SCEnvMetaEntry` XDR values. See the type definitions in [stellar-xdr](https://github.com/stellar/stellar-xdr). [See also XDR data format](https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr). + +Outputs no data when no data is present in the contract. + +**Usage:** `stellar contract info env-meta [OPTIONS] <--wasm |--wasm-hash |--contract-id >` + +###### **Options:** + +* `--wasm ` β€” Wasm file path on local filesystem. Provide this OR `--wasm-hash` OR `--contract-id` +* `--wasm-hash ` β€” Hash of Wasm blob on a network. Provide this OR `--wasm` OR `--contract-id` +* `--contract-id ` β€” Contract ID/alias on a network. Provide this OR `--wasm-hash` OR `--wasm` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--output ` β€” Format of the output + + Default value: `text` + + Possible values: + - `text`: + Text output of the meta info entry + - `xdr-base64`: + XDR output of the info entry + - `json`: + JSON output of the info entry (one line, not formatted) + - `json-formatted`: + Formatted (multiline) JSON output of the info entry + + + + +## `stellar contract info build` + +Output the contract build information, if available. + +If the contract has a meta entry like `source_repo=github:user/repo`, this command will try to fetch the attestation information for the WASM file. + +**Usage:** `stellar contract info build [OPTIONS] <--wasm |--wasm-hash |--contract-id >` + +###### **Options:** + +* `--wasm ` β€” Wasm file path on local filesystem. Provide this OR `--wasm-hash` OR `--contract-id` +* `--wasm-hash ` β€” Hash of Wasm blob on a network. Provide this OR `--wasm` OR `--contract-id` +* `--contract-id ` β€” Contract ID/alias on a network. Provide this OR `--wasm-hash` OR `--wasm` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract init` + +Initialize a Soroban contract project. + +This command will create a Cargo workspace project and add a sample Stellar contract. The name of the contract can be specified by `--name`. It can be run multiple times with different names in order to generate multiple contracts, and files won't be overwritten unless `--overwrite` is passed. + +**Usage:** `stellar contract init [OPTIONS] ` + +###### **Arguments:** + +* `` + +###### **Options:** + +* `--name ` β€” An optional flag to specify a new contract's name. + + Default value: `hello-world` +* `--overwrite` β€” Overwrite all existing files. + + + +## `stellar contract inspect` + +(Deprecated in favor of `contract info` subcommand) Inspect a WASM file listing contract functions, meta, etc + +**Usage:** `stellar contract inspect [OPTIONS] --wasm ` + +###### **Options:** + +* `--wasm ` β€” Path to wasm binary +* `--output ` β€” Output just XDR in base64 + + Default value: `docs` + + Possible values: + - `xdr-base64`: + XDR of array of contract spec entries + - `xdr-base64-array`: + Array of xdr of contract spec entries + - `docs`: + Pretty print of contract spec entries + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract upload` + +Install a WASM file to the ledger without creating a contract instance + +**Usage:** `stellar contract upload [OPTIONS] --source-account --wasm ` + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--wasm ` β€” Path to wasm binary +* `-i`, `--ignore-checks` β€” Whether to ignore safety checks when deploying contracts + + Default value: `false` + + + +## `stellar contract install` + +(Deprecated in favor of `contract upload` subcommand) Install a WASM file to the ledger without creating a contract instance + +**Usage:** `stellar contract install [OPTIONS] --source-account --wasm ` + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--wasm ` β€” Path to wasm binary +* `-i`, `--ignore-checks` β€” Whether to ignore safety checks when deploying contracts + + Default value: `false` + + + +## `stellar contract invoke` + +Invoke a contract function + +Generates an "implicit CLI" for the specified contract on-the-fly using the contract's schema, which gets embedded into every Soroban contract. The "slop" in this command, everything after the `--`, gets passed to this implicit CLI. Get in-depth help for a given contract: + +stellar contract invoke ... -- --help + +**Usage:** `stellar contract invoke [OPTIONS] --id --source-account [-- ...]` + +###### **Arguments:** + +* `` β€” Function name as subcommand, then arguments for that function as `--arg-name value` + +###### **Options:** + +* `--id ` β€” Contract ID to invoke +* `--is-view` β€” View the result simulating and do not sign and submit transaction. Deprecated use `--send=no` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--send ` β€” Whether or not to send a transaction + + Default value: `default` + + Possible values: + - `default`: + Send transaction if simulation indicates there are ledger writes, published events, or auth required, otherwise return simulation result + - `no`: + Do not send transaction, return simulation result + - `yes`: + Always send transaction + + + + +## `stellar contract optimize` + +Optimize a WASM file + +**Usage:** `stellar contract optimize [OPTIONS] --wasm ` + +###### **Options:** + +* `--wasm ` β€” Path to wasm binary +* `--wasm-out ` β€” Path to write the optimized WASM file to (defaults to same location as --wasm with .optimized.wasm suffix) + + + +## `stellar contract read` + +Print the current value of a contract-data ledger entry + +**Usage:** `stellar contract read [OPTIONS]` + +###### **Options:** + +* `--output ` β€” Type of output to generate + + Default value: `string` + + Possible values: + - `string`: + String + - `json`: + Json + - `xdr`: + XDR + +* `--id ` β€” Contract ID to which owns the data entries. If no keys provided the Contract's instance will be extended +* `--key ` β€” Storage key (symbols only) +* `--key-xdr ` β€” Storage key (base64-encoded XDR) +* `--wasm ` β€” Path to Wasm file of contract code to extend +* `--wasm-hash ` β€” Path to Wasm file of contract code to extend +* `--durability ` β€” Storage entry durability + + Default value: `persistent` + + Possible values: + - `persistent`: + Persistent + - `temporary`: + Temporary + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar contract restore` + +Restore an evicted value for a contract-data legder entry. + +If no keys are specificed the contract itself is restored. + +**Usage:** `stellar contract restore [OPTIONS] --source-account ` + +###### **Options:** + +* `--id ` β€” Contract ID to which owns the data entries. If no keys provided the Contract's instance will be extended +* `--key ` β€” Storage key (symbols only) +* `--key-xdr ` β€” Storage key (base64-encoded XDR) +* `--wasm ` β€” Path to Wasm file of contract code to extend +* `--wasm-hash ` β€” Path to Wasm file of contract code to extend +* `--durability ` β€” Storage entry durability + + Default value: `persistent` + + Possible values: + - `persistent`: + Persistent + - `temporary`: + Temporary + +* `--ledgers-to-extend ` β€” Number of ledgers to extend the entry +* `--ttl-ledger-only` β€” Only print the new Time To Live ledger +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout + + + +## `stellar events` + +Watch the network for contract events + +**Usage:** `stellar events [OPTIONS]` + +###### **Options:** + +* `--start-ledger ` β€” The first ledger sequence number in the range to pull events https://developers.stellar.org/docs/learn/encyclopedia/network-configuration/ledger-headers#ledger-sequence +* `--cursor ` β€” The cursor corresponding to the start of the event range +* `--output ` β€” Output formatting options for event stream + + Default value: `pretty` + + Possible values: + - `pretty`: + Colorful, human-oriented console output + - `plain`: + Human-oriented console output without colors + - `json`: + JSON formatted console output + +* `-c`, `--count ` β€” The maximum number of events to display (defer to the server-defined limit) + + Default value: `10` +* `--id ` β€” A set of (up to 5) contract IDs to filter events on. This parameter can be passed multiple times, e.g. `--id C123.. --id C456..`, or passed with multiple parameters, e.g. `--id C123 C456`. + + Though the specification supports multiple filter objects (i.e. combinations of type, IDs, and topics), only one set can be specified on the command-line today, though that set can have multiple IDs/topics. +* `--topic ` β€” A set of (up to 4) topic filters to filter event topics on. A single topic filter can contain 1-4 different segment filters, separated by commas, with an asterisk (`*` character) indicating a wildcard segment. + + **Example:** topic filter with two segments: `--topic "AAAABQAAAAdDT1VOVEVSAA==,*"` + + **Example:** two topic filters with one and two segments each: `--topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'` + + Note that all of these topic filters are combined with the contract IDs into a single filter (i.e. combination of type, IDs, and topics). +* `--type ` β€” Specifies which type of contract events to display + + Default value: `all` + + Possible values: `all`, `contract`, `system` + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config + + + +## `stellar env` + +Prints the environment variables + +Prints to stdout in a format that can be used as .env file. Environment variables have precedence over defaults. + +Pass a name to get the value of a single environment variable. + +If there are no environment variables in use, prints the defaults. + +**Usage:** `stellar env [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Env variable name to get the value of. + + E.g.: $ stellar env STELLAR_ACCOUNT + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar keys` + +Create and manage identities including keys and addresses + +**Usage:** `stellar keys ` + +###### **Subcommands:** + +* `add` β€” Add a new identity (keypair, ledger, OS specific secure store) +* `public-key` β€” Given an identity return its address (public key) +* `fund` β€” Fund an identity on a test network +* `generate` β€” Generate a new identity using a 24-word seed phrase The seed phrase can be stored in a config file (default) or in an OS-specific secure store +* `ls` β€” List identities +* `rm` β€” Remove an identity +* `secret` β€” Output an identity's secret key +* `use` β€” Set the default identity that will be used on all commands. This allows you to skip `--source-account` or setting a environment variable, while reusing this value in all commands that require it + + + +## `stellar keys add` + +Add a new identity (keypair, ledger, OS specific secure store) + +**Usage:** `stellar keys add [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Name of identity + +###### **Options:** + +* `--secret-key` β€” (deprecated) Enter secret (S) key when prompted +* `--seed-phrase` β€” (deprecated) Enter key using 12-24 word seed phrase +* `--secure-store` β€” Save the new key in secure store. This only supports seed phrases for now +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--public-key ` β€” Add a public key, ed25519, or muxed account, e.g. G1.., M2.. + + + +## `stellar keys public-key` + +Given an identity return its address (public key) + +**Usage:** `stellar keys public-key [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Name of identity to lookup, default test identity used if not provided + +###### **Options:** + +* `--hd-path ` β€” If identity is a seed phrase use this hd path, default is 0 +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar keys fund` + +Fund an identity on a test network + +**Usage:** `stellar keys fund [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Name of identity to lookup, default test identity used if not provided + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--hd-path ` β€” If identity is a seed phrase use this hd path, default is 0 +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar keys generate` + +Generate a new identity using a 24-word seed phrase The seed phrase can be stored in a config file (default) or in an OS-specific secure store + +**Usage:** `stellar keys generate [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Name of identity + +###### **Options:** + +* `--no-fund` β€” Do not fund address +* `--seed ` β€” Optional seed to use when generating seed phrase. Random otherwise +* `-s`, `--as-secret` β€” Output the generated identity as a secret key +* `--secure-store` β€” Save in OS-specific secure store +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--hd-path ` β€” When generating a secret key, which `hd_path` should be used from the original `seed_phrase` +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--fund` β€” Fund generated key pair + + Default value: `false` +* `--overwrite` β€” Overwrite existing identity if it already exists + + + +## `stellar keys ls` + +List identities + +**Usage:** `stellar keys ls [OPTIONS]` + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `-l`, `--long` + + + +## `stellar keys rm` + +Remove an identity + +**Usage:** `stellar keys rm [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Identity to remove + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar keys secret` + +Output an identity's secret key + +**Usage:** `stellar keys secret [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Name of identity to lookup, default is test identity + +###### **Options:** + +* `--phrase` β€” Output seed phrase instead of private key +* `--hd-path ` β€” If identity is a seed phrase use this hd path, default is 0 +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar keys use` + +Set the default identity that will be used on all commands. This allows you to skip `--source-account` or setting a environment variable, while reusing this value in all commands that require it + +**Usage:** `stellar keys use [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Set the default network name + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar network` + +Configure connection to networks + +**Usage:** `stellar network ` + +###### **Subcommands:** + +* `add` β€” Add a new network +* `rm` β€” Remove a network +* `ls` β€” List networks +* `start` β€” ⚠️ Deprecated: use `stellar container start` instead +* `stop` β€” ⚠️ Deprecated: use `stellar container stop` instead +* `use` β€” Set the default network that will be used on all commands. This allows you to skip `--network` or setting a environment variable, while reusing this value in all commands that require it +* `container` β€” ⚠️ Deprecated: use `stellar container` instead +* `health` β€” Checks the health of the configured RPC + + + +## `stellar network add` + +Add a new network + +**Usage:** `stellar network add [OPTIONS] --rpc-url --network-passphrase ` + +###### **Arguments:** + +* `` β€” Name of network + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” Optional header (e.g. API Key) to include in requests to the RPC +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar network rm` + +Remove a network + +**Usage:** `stellar network rm [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Network to remove + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar network ls` + +List networks + +**Usage:** `stellar network ls [OPTIONS]` + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `-l`, `--long` β€” Get more info about the networks + + + +## `stellar network start` + +⚠️ Deprecated: use `stellar container start` instead + +Start network + +Start a container running a Stellar node, RPC, API, and friendbot (faucet). + +`stellar network start NETWORK [OPTIONS]` + +By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: + +`docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable rpc,horizon` + +**Usage:** `stellar network start [OPTIONS] [NETWORK]` + +###### **Arguments:** + +* `` β€” Network to start. Default is `local` + + Possible values: `local`, `testnet`, `futurenet`, `pubnet` + + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock +* `--name ` β€” Optional argument to specify the container name +* `-l`, `--limits ` β€” Optional argument to specify the limits for the local network only +* `-p`, `--ports-mapping ` β€” Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping + + Default value: `8000:8000` +* `-t`, `--image-tag-override ` β€” Optional argument to override the default docker image tag for the given network +* `--protocol-version ` β€” Optional argument to specify the protocol version for the local network only + + + +## `stellar network stop` + +⚠️ Deprecated: use `stellar container stop` instead + +Stop a network started with `network start`. For example, if you ran `stellar network start local`, you can use `stellar network stop local` to stop it. + +**Usage:** `stellar network stop [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Container to stop + + Default value: `local` + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock + + + +## `stellar network use` + +Set the default network that will be used on all commands. This allows you to skip `--network` or setting a environment variable, while reusing this value in all commands that require it + +**Usage:** `stellar network use [OPTIONS] ` + +###### **Arguments:** + +* `` β€” Set the default network name + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar network container` + +⚠️ Deprecated: use `stellar container` instead + +Commands to start, stop and get logs for a quickstart container + +**Usage:** `stellar network container ` + +###### **Subcommands:** + +* `logs` β€” Get logs from a running network container +* `start` β€” Start a container running a Stellar node, RPC, API, and friendbot (faucet) +* `stop` β€” Stop a network container started with `stellar container start` + + + +## `stellar network container logs` + +Get logs from a running network container + +**Usage:** `stellar network container logs [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Container to get logs from + + Default value: `local` + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock + + + +## `stellar network container start` + +Start a container running a Stellar node, RPC, API, and friendbot (faucet). + +`stellar container start NETWORK [OPTIONS]` + +By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: + +`docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable rpc,horizon` + +**Usage:** `stellar network container start [OPTIONS] [NETWORK]` + +###### **Arguments:** + +* `` β€” Network to start. Default is `local` + + Possible values: `local`, `testnet`, `futurenet`, `pubnet` + + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock +* `--name ` β€” Optional argument to specify the container name +* `-l`, `--limits ` β€” Optional argument to specify the limits for the local network only +* `-p`, `--ports-mapping ` β€” Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping + + Default value: `8000:8000` +* `-t`, `--image-tag-override ` β€” Optional argument to override the default docker image tag for the given network +* `--protocol-version ` β€” Optional argument to specify the protocol version for the local network only + + + +## `stellar network container stop` + +Stop a network container started with `stellar container start` + +**Usage:** `stellar network container stop [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Container to stop + + Default value: `local` + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock + + + +## `stellar network health` + +Checks the health of the configured RPC + +**Usage:** `stellar network health [OPTIONS]` + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--output ` β€” Format of the output + + Default value: `text` + + Possible values: + - `text`: + Text output of network health status + - `json`: + JSON result of the RPC request + - `json-formatted`: + Formatted (multiline) JSON output of the RPC request + + + + +## `stellar container` + +Start local networks in containers + +**Usage:** `stellar container ` + +###### **Subcommands:** + +* `logs` β€” Get logs from a running network container +* `start` β€” Start a container running a Stellar node, RPC, API, and friendbot (faucet) +* `stop` β€” Stop a network container started with `stellar container start` + + + +## `stellar container logs` + +Get logs from a running network container + +**Usage:** `stellar container logs [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Container to get logs from + + Default value: `local` + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock + + + +## `stellar container start` + +Start a container running a Stellar node, RPC, API, and friendbot (faucet). + +`stellar container start NETWORK [OPTIONS]` + +By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: + +`docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable rpc,horizon` + +**Usage:** `stellar container start [OPTIONS] [NETWORK]` + +###### **Arguments:** + +* `` β€” Network to start. Default is `local` + + Possible values: `local`, `testnet`, `futurenet`, `pubnet` + + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock +* `--name ` β€” Optional argument to specify the container name +* `-l`, `--limits ` β€” Optional argument to specify the limits for the local network only +* `-p`, `--ports-mapping ` β€” Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping + + Default value: `8000:8000` +* `-t`, `--image-tag-override ` β€” Optional argument to override the default docker image tag for the given network +* `--protocol-version ` β€” Optional argument to specify the protocol version for the local network only + + + +## `stellar container stop` + +Stop a network container started with `stellar container start` + +**Usage:** `stellar container stop [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` β€” Container to stop + + Default value: `local` + +###### **Options:** + +* `-d`, `--docker-host ` β€” Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock + + + +## `stellar snapshot` + +Download a snapshot of a ledger from an archive + +**Usage:** `stellar snapshot ` + +###### **Subcommands:** + +* `create` β€” Create a ledger snapshot using a history archive + + + +## `stellar snapshot create` + +Create a ledger snapshot using a history archive. + +Filters (address, wasm-hash) specify what ledger entries to include. + +Account addresses include the account, and trustlines. + +Contract addresses include the related wasm, contract data. + +If a contract is a Stellar asset contract, it includes the asset issuer's account and trust lines, but does not include all the trust lines of other accounts holding the asset. To include them specify the addresses of relevant accounts. + +Any invalid contract id passed as `--address` will be ignored. + +**Usage:** `stellar snapshot create [OPTIONS] --output ` + +###### **Options:** + +* `--ledger ` β€” The ledger sequence number to snapshot. Defaults to latest history archived ledger +* `--address
` β€” Account or contract address/alias to include in the snapshot +* `--wasm-hash ` β€” WASM hashes to include in the snapshot +* `--output ` β€” Format of the out file + + Possible values: `json` + +* `--out ` β€” Out path that the snapshot is written to + + Default value: `snapshot.json` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--archive-url ` β€” Archive URL + + + +## `stellar tx` + +Sign, Simulate, and Send transactions + +**Usage:** `stellar tx ` + +###### **Subcommands:** + +* `edit` β€” Edit a transaction envelope from stdin. This command respects the environment variables `STELLAR_EDITOR`, `EDITOR` and `VISUAL`, in that order +* `hash` β€” Calculate the hash of a transaction envelope +* `new` β€” Create a new transaction +* `operation` β€” Manipulate the operations in a transaction, including adding new operations +* `send` β€” Send a transaction envelope to the network +* `sign` β€” Sign a transaction envelope appending the signature to the envelope +* `simulate` β€” Simulate a transaction envelope from stdin + + + +## `stellar tx edit` + +Edit a transaction envelope from stdin. This command respects the environment variables `STELLAR_EDITOR`, `EDITOR` and `VISUAL`, in that order. + +Example: Start a new edit session + +$ stellar tx edit + +Example: Pipe an XDR transaction envelope + +$ stellar tx new manage-data --data-name hello --build-only | stellar tx edit + +**Usage:** `stellar tx edit` + + + +## `stellar tx hash` + +Calculate the hash of a transaction envelope + +**Usage:** `stellar tx hash [OPTIONS] [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config + + + +## `stellar tx new` + +Create a new transaction + +**Usage:** `stellar tx new ` + +###### **Subcommands:** + +* `account-merge` β€” Transfers the XLM balance of an account to another account and removes the source account from the ledger +* `bump-sequence` β€” Bumps forward the sequence number of the source account to the given sequence number, invalidating any transaction with a smaller sequence number +* `change-trust` β€” Creates, updates, or deletes a trustline +Learn more about trustlines +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines +* `create-account` β€” Creates and funds a new account with the specified starting balance +* `manage-data` β€” Sets, modifies, or deletes a data entry (name/value pair) that is attached to an account +Learn more about entries and subentries: +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries +* `payment` β€” Sends an amount in a specific asset to a destination account +* `set-options` β€” Set option for an account such as flags, inflation destination, signers, home domain, and master key weight +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags +Learn more about the home domain: +https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md +Learn more about signers operations and key weight: +https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `set-trustline-flags` β€” Allows issuing account to configure authorization and trustline flags to an asset +The Asset parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a Code:Issuer format), this is equivalent to the Asset type. +If you are modifying a trustline to a pool share, however, this is composed of the liquidity pool's unique ID. +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags + + + +## `stellar tx new account-merge` + +Transfers the XLM balance of an account to another account and removes the source account from the ledger + +**Usage:** `stellar tx new account-merge [OPTIONS] --source-account --account ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--account ` β€” Muxed Account to merge with, e.g. `GBX...`, 'MBX...' + + + +## `stellar tx new bump-sequence` + +Bumps forward the sequence number of the source account to the given sequence number, invalidating any transaction with a smaller sequence number + +**Usage:** `stellar tx new bump-sequence [OPTIONS] --source-account --bump-to ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--bump-to ` β€” Sequence number to bump to + + + +## `stellar tx new change-trust` + +Creates, updates, or deletes a trustline +Learn more about trustlines +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines + +**Usage:** `stellar tx new change-trust [OPTIONS] --source-account --line ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--line ` +* `--limit ` β€” Limit for the trust line, 0 to remove the trust line + + Default value: `9223372036854775807` + + + +## `stellar tx new create-account` + +Creates and funds a new account with the specified starting balance + +**Usage:** `stellar tx new create-account [OPTIONS] --source-account --destination ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--destination ` β€” Account Id to create, e.g. `GBX...` +* `--starting-balance ` β€” Initial balance in stroops of the account, default 1 XLM + + Default value: `10_000_000` + + + +## `stellar tx new manage-data` + +Sets, modifies, or deletes a data entry (name/value pair) that is attached to an account +Learn more about entries and subentries: +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries + +**Usage:** `stellar tx new manage-data [OPTIONS] --source-account --data-name ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--data-name ` β€” String up to 64 bytes long. If this is a new Name it will add the given name/value pair to the account. If this Name is already present then the associated value will be modified +* `--data-value ` β€” Up to 64 bytes long hex string If not present then the existing Name will be deleted. If present then this value will be set in the `DataEntry` + + + +## `stellar tx new payment` + +Sends an amount in a specific asset to a destination account + +**Usage:** `stellar tx new payment [OPTIONS] --source-account --destination --amount ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--destination ` β€” Account to send to, e.g. `GBX...` +* `--asset ` β€” Asset to send, default native, e.i. XLM + + Default value: `native` +* `--amount ` β€” Amount of the aforementioned asset to send. e.g. `10_000_000` (1 XLM) + + + +## `stellar tx new set-options` + +Set option for an account such as flags, inflation destination, signers, home domain, and master key weight +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags +Learn more about the home domain: +https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md +Learn more about signers operations and key weight: +https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig + +**Usage:** `stellar tx new set-options [OPTIONS] --source-account ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--inflation-dest ` β€” Account of the inflation destination +* `--master-weight ` β€” A number from 0-255 (inclusive) representing the weight of the master key. If the weight of the master key is updated to 0, it is effectively disabled +* `--low-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a low threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--med-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a medium threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--high-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a high threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--home-domain ` β€” Sets the home domain of an account. See https://developers.stellar.org/docs/learn/encyclopedia/network-configuration/federation +* `--signer ` β€” Add, update, or remove a signer from an account +* `--signer-weight ` β€” Signer weight is a number from 0-255 (inclusive). The signer is deleted if the weight is 0 +* `--set-required` β€” When enabled, an issuer must approve an account before that account can hold its asset. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-required-0x1 +* `--set-revocable` β€” When enabled, an issuer can revoke an existing trustline's authorization, thereby freezing the asset held by an account. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-revocable-0x2 +* `--set-clawback-enabled` β€” Enables the issuing account to take back (burning) all of the asset. https://developers.stellar.org/docs/tokens/control-asset-access#clawback-enabled-0x8 +* `--set-immutable` β€” With this setting, none of the other authorization flags (`AUTH_REQUIRED_FLAG`, `AUTH_REVOCABLE_FLAG`) can be set, and the issuing account can't be merged. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-immutable-0x4 +* `--clear-required` +* `--clear-revocable` +* `--clear-immutable` +* `--clear-clawback-enabled` + + + +## `stellar tx new set-trustline-flags` + +Allows issuing account to configure authorization and trustline flags to an asset +The Asset parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a Code:Issuer format), this is equivalent to the Asset type. +If you are modifying a trustline to a pool share, however, this is composed of the liquidity pool's unique ID. +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags + +**Usage:** `stellar tx new set-trustline-flags [OPTIONS] --source-account --trustor --asset ` + +###### **Options:** + +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--trustor ` β€” Account to set trustline flags for, e.g. `GBX...`, or alias, or muxed account, `M123...`` +* `--asset ` β€” Asset to set trustline flags for +* `--set-authorize` β€” Signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders +* `--set-authorize-to-maintain-liabilities` β€” Denotes limited authorization that allows an account to maintain current orders but not to otherwise transact with the asset +* `--set-trustline-clawback-enabled` β€” Enables the issuing account to take back (burning) all of the asset. See our section on Clawbacks: https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/clawbacks +* `--clear-authorize` +* `--clear-authorize-to-maintain-liabilities` +* `--clear-trustline-clawback-enabled` + + + +## `stellar tx operation` + +Manipulate the operations in a transaction, including adding new operations + +**Usage:** `stellar tx operation ` + +###### **Subcommands:** + +* `add` β€” Add Operation to a transaction + + + +## `stellar tx operation add` + +Add Operation to a transaction + +**Usage:** `stellar tx operation add ` + +###### **Subcommands:** + +* `account-merge` β€” Transfers the XLM balance of an account to another account and removes the source account from the ledger +* `bump-sequence` β€” Bumps forward the sequence number of the source account to the given sequence number, invalidating any transaction with a smaller sequence number +* `change-trust` β€” Creates, updates, or deletes a trustline +Learn more about trustlines +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines +* `create-account` β€” Creates and funds a new account with the specified starting balance +* `manage-data` β€” Sets, modifies, or deletes a data entry (name/value pair) that is attached to an account +Learn more about entries and subentries: +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries +* `payment` β€” Sends an amount in a specific asset to a destination account +* `set-options` β€” Set option for an account such as flags, inflation destination, signers, home domain, and master key weight +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags +Learn more about the home domain: +https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md +Learn more about signers operations and key weight: +https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `set-trustline-flags` β€” Allows issuing account to configure authorization and trustline flags to an asset +The Asset parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a Code:Issuer format), this is equivalent to the Asset type. +If you are modifying a trustline to a pool share, however, this is composed of the liquidity pool's unique ID. +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags + + + +## `stellar tx operation add account-merge` + +Transfers the XLM balance of an account to another account and removes the source account from the ledger + +**Usage:** `stellar tx operation add account-merge [OPTIONS] --source-account --account [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--account ` β€” Muxed Account to merge with, e.g. `GBX...`, 'MBX...' + + + +## `stellar tx operation add bump-sequence` + +Bumps forward the sequence number of the source account to the given sequence number, invalidating any transaction with a smaller sequence number + +**Usage:** `stellar tx operation add bump-sequence [OPTIONS] --source-account --bump-to [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--bump-to ` β€” Sequence number to bump to + + + +## `stellar tx operation add change-trust` + +Creates, updates, or deletes a trustline +Learn more about trustlines +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines + +**Usage:** `stellar tx operation add change-trust [OPTIONS] --source-account --line [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--line ` +* `--limit ` β€” Limit for the trust line, 0 to remove the trust line + + Default value: `9223372036854775807` + + + +## `stellar tx operation add create-account` + +Creates and funds a new account with the specified starting balance + +**Usage:** `stellar tx operation add create-account [OPTIONS] --source-account --destination [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--destination ` β€” Account Id to create, e.g. `GBX...` +* `--starting-balance ` β€” Initial balance in stroops of the account, default 1 XLM + + Default value: `10_000_000` + + + +## `stellar tx operation add manage-data` + +Sets, modifies, or deletes a data entry (name/value pair) that is attached to an account +Learn more about entries and subentries: +https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries + +**Usage:** `stellar tx operation add manage-data [OPTIONS] --source-account --data-name [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--data-name ` β€” String up to 64 bytes long. If this is a new Name it will add the given name/value pair to the account. If this Name is already present then the associated value will be modified +* `--data-value ` β€” Up to 64 bytes long hex string If not present then the existing Name will be deleted. If present then this value will be set in the `DataEntry` + + + +## `stellar tx operation add payment` + +Sends an amount in a specific asset to a destination account + +**Usage:** `stellar tx operation add payment [OPTIONS] --source-account --destination --amount [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--destination ` β€” Account to send to, e.g. `GBX...` +* `--asset ` β€” Asset to send, default native, e.i. XLM + + Default value: `native` +* `--amount ` β€” Amount of the aforementioned asset to send. e.g. `10_000_000` (1 XLM) + + + +## `stellar tx operation add set-options` + +Set option for an account such as flags, inflation destination, signers, home domain, and master key weight +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags +Learn more about the home domain: +https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md +Learn more about signers operations and key weight: +https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig + +**Usage:** `stellar tx operation add set-options [OPTIONS] --source-account [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--inflation-dest ` β€” Account of the inflation destination +* `--master-weight ` β€” A number from 0-255 (inclusive) representing the weight of the master key. If the weight of the master key is updated to 0, it is effectively disabled +* `--low-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a low threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--med-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a medium threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--high-threshold ` β€” A number from 0-255 (inclusive) representing the threshold this account sets on all operations it performs that have a high threshold. https://developers.stellar.org/docs/learn/encyclopedia/security/signatures-multisig#multisig +* `--home-domain ` β€” Sets the home domain of an account. See https://developers.stellar.org/docs/learn/encyclopedia/network-configuration/federation +* `--signer ` β€” Add, update, or remove a signer from an account +* `--signer-weight ` β€” Signer weight is a number from 0-255 (inclusive). The signer is deleted if the weight is 0 +* `--set-required` β€” When enabled, an issuer must approve an account before that account can hold its asset. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-required-0x1 +* `--set-revocable` β€” When enabled, an issuer can revoke an existing trustline's authorization, thereby freezing the asset held by an account. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-revocable-0x2 +* `--set-clawback-enabled` β€” Enables the issuing account to take back (burning) all of the asset. https://developers.stellar.org/docs/tokens/control-asset-access#clawback-enabled-0x8 +* `--set-immutable` β€” With this setting, none of the other authorization flags (`AUTH_REQUIRED_FLAG`, `AUTH_REVOCABLE_FLAG`) can be set, and the issuing account can't be merged. https://developers.stellar.org/docs/tokens/control-asset-access#authorization-immutable-0x4 +* `--clear-required` +* `--clear-revocable` +* `--clear-immutable` +* `--clear-clawback-enabled` + + + +## `stellar tx operation add set-trustline-flags` + +Allows issuing account to configure authorization and trustline flags to an asset +The Asset parameter is of the `TrustLineAsset` type. If you are modifying a trustline to a regular asset (i.e. one in a Code:Issuer format), this is equivalent to the Asset type. +If you are modifying a trustline to a pool share, however, this is composed of the liquidity pool's unique ID. +Learn more about flags: +https://developers.stellar.org/docs/learn/glossary#flags + +**Usage:** `stellar tx operation add set-trustline-flags [OPTIONS] --source-account --trustor --asset [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--operation-source-account ` β€” Source account used for the operation +* `--fee ` β€” fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm + + Default value: `100` +* `--cost` β€” Output the cost execution to stderr +* `--instructions ` β€” Number of instructions to simulate +* `--build-only` β€” Build the transaction and only write the base64 xdr to stdout +* `--sim-only` β€” (Deprecated) simulate the transaction and only write the base64 xdr to stdout +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `--trustor ` β€” Account to set trustline flags for, e.g. `GBX...`, or alias, or muxed account, `M123...`` +* `--asset ` β€” Asset to set trustline flags for +* `--set-authorize` β€” Signifies complete authorization allowing an account to transact freely with the asset to make and receive payments and place orders +* `--set-authorize-to-maintain-liabilities` β€” Denotes limited authorization that allows an account to maintain current orders but not to otherwise transact with the asset +* `--set-trustline-clawback-enabled` β€” Enables the issuing account to take back (burning) all of the asset. See our section on Clawbacks: https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/clawbacks +* `--clear-authorize` +* `--clear-authorize-to-maintain-liabilities` +* `--clear-trustline-clawback-enabled` + + + +## `stellar tx send` + +Send a transaction envelope to the network + +**Usage:** `stellar tx send [OPTIONS] [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar tx sign` + +Sign a transaction envelope appending the signature to the envelope + +**Usage:** `stellar tx sign [OPTIONS] [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR, or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--sign-with-key ` β€” Sign with a local key or key saved in OS secure storage. Can be an identity (--sign-with-key alice), a secret key (--sign-with-key SC36…), or a seed phrase (--sign-with-key "kite urban…"). If using seed phrase, `--hd-path` defaults to the `0` path +* `--hd-path ` β€” If using a seed phrase to sign, sets which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--sign-with-lab` β€” Sign with https://lab.stellar.org +* `--sign-with-ledger` β€” Sign with a ledger wallet +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar tx simulate` + +Simulate a transaction envelope from stdin + +**Usage:** `stellar tx simulate [OPTIONS] --source-account [TX_XDR]` + +###### **Arguments:** + +* `` β€” Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty + +###### **Options:** + +* `--rpc-url ` β€” RPC server endpoint +* `--rpc-header ` β€” RPC Header(s) to include in requests to the RPC provider +* `--network-passphrase ` β€” Network passphrase to sign the transaction sent to the rpc server +* `-n`, `--network ` β€” Name of network to use from config +* `-s`, `--source-account ` β€” Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail +* `--hd-path ` β€” If using a seed phrase, which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0` +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." + + + +## `stellar xdr` + +Decode and encode XDR + +**Usage:** `stellar xdr [CHANNEL] ` + +###### **Subcommands:** + +* `types` β€” View information about types +* `guess` β€” Guess the XDR type +* `decode` β€” Decode XDR +* `encode` β€” Encode XDR +* `compare` β€” Compare two XDR values with each other +* `version` β€” Print version information + +###### **Arguments:** + +* `` β€” Channel of XDR to operate on + + Default value: `+curr` + + Possible values: `+curr`, `+next` + + + + +## `stellar xdr types` + +View information about types + +**Usage:** `stellar xdr types ` + +###### **Subcommands:** + +* `list` β€” +* `schema` β€” + + + +## `stellar xdr types list` + +**Usage:** `stellar xdr types list [OPTIONS]` + +###### **Options:** + +* `--output ` + + Default value: `plain` + + Possible values: `plain`, `json`, `json-formatted` + + + + +## `stellar xdr types schema` + +**Usage:** `stellar xdr types schema [OPTIONS] --type ` + +###### **Options:** + +* `--type ` β€” XDR type to decode +* `--output ` + + Default value: `json-schema-draft201909` + + Possible values: `json-schema-draft7`, `json-schema-draft201909` + + + + +## `stellar xdr guess` + +Guess the XDR type + +**Usage:** `stellar xdr guess [OPTIONS] [FILE]` + +###### **Arguments:** + +* `` β€” File to decode, or stdin if omitted + +###### **Options:** + +* `--input ` + + Default value: `single-base64` + + Possible values: `single`, `single-base64`, `stream`, `stream-base64`, `stream-framed` + +* `--output ` + + Default value: `list` + + Possible values: `list` + +* `--certainty ` β€” Certainty as an arbitrary value + + Default value: `2` + + + +## `stellar xdr decode` + +Decode XDR + +**Usage:** `stellar xdr decode [OPTIONS] --type [FILES]...` + +###### **Arguments:** + +* `` β€” Files to decode, or stdin if omitted + +###### **Options:** + +* `--type ` β€” XDR type to decode +* `--input ` + + Default value: `stream-base64` + + Possible values: `single`, `single-base64`, `stream`, `stream-base64`, `stream-framed` + +* `--output ` + + Default value: `json` + + Possible values: `json`, `json-formatted`, `rust-debug`, `rust-debug-formatted` + + + + +## `stellar xdr encode` + +Encode XDR + +**Usage:** `stellar xdr encode [OPTIONS] --type [FILES]...` + +###### **Arguments:** + +* `` β€” Files to encode, or stdin if omitted + +###### **Options:** + +* `--type ` β€” XDR type to encode +* `--input ` + + Default value: `json` + + Possible values: `json` + +* `--output ` + + Default value: `single-base64` + + Possible values: `single`, `single-base64`, `stream` + + + + +## `stellar xdr compare` + +Compare two XDR values with each other + +Outputs: `-1` when the left XDR value is less than the right XDR value, `0` when the left XDR value is equal to the right XDR value, `1` when the left XDR value is greater than the right XDR value + +**Usage:** `stellar xdr compare [OPTIONS] --type ` + +###### **Arguments:** + +* `` β€” XDR file to decode and compare with the right value +* `` β€” XDR file to decode and compare with the left value + +###### **Options:** + +* `--type ` β€” XDR type of both inputs +* `--input ` + + Default value: `single-base64` + + Possible values: `single`, `single-base64` + + + + +## `stellar xdr version` + +Print version information + +**Usage:** `stellar xdr version` + + + +## `stellar completion` + +Print shell completion code for the specified shell + +Ensure the completion package for your shell is installed, e.g. bash-completion for bash. + +To enable autocomplete in the current bash shell, run: `source <(stellar completion --shell bash)` + +To enable autocomplete permanently, run: `echo "source <(stellar completion --shell bash)" >> ~/.bashrc` + + +**Usage:** `stellar completion --shell ` + +###### **Options:** + +* `--shell ` β€” The shell type + + Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh` + + + + +## `stellar cache` + +Cache for transactions and contract specs + +**Usage:** `stellar cache ` + +###### **Subcommands:** + +* `clean` β€” Delete the cache +* `path` β€” Show the location of the cache +* `actionlog` β€” Access details about cached actions like transactions, and simulations. (Experimental. May see breaking changes at any time.) + + + +## `stellar cache clean` + +Delete the cache + +**Usage:** `stellar cache clean` + + + +## `stellar cache path` + +Show the location of the cache + +**Usage:** `stellar cache path` + + + +## `stellar cache actionlog` + +Access details about cached actions like transactions, and simulations. (Experimental. May see breaking changes at any time.) + +**Usage:** `stellar cache actionlog ` + +###### **Subcommands:** + +* `ls` β€” List cached actions (transactions, simulations) +* `read` β€” Read cached action + + + +## `stellar cache actionlog ls` + +List cached actions (transactions, simulations) + +**Usage:** `stellar cache actionlog ls [OPTIONS]` + +###### **Options:** + +* `--global` β€” Use global config +* `--config-dir ` β€” Location of config directory, default is "." +* `-l`, `--long` + + + +## `stellar cache actionlog read` + +Read cached action + +**Usage:** `stellar cache actionlog read --id ` + +###### **Options:** + +* `--id ` β€” ID of the cache entry + + + +## `stellar version` + +Print version information + +**Usage:** `stellar version` + + + diff --git a/README.md b/README.md index a79e1ebc..fdcc2d05 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,28 @@ atomic_multiswap**: This contract performs a batch of atomic token swaps between - **workspace**: This contract demonstrates how multiple smart contracts can be developed, tested, and built side-by-side in the same Rust workspace ## Get Started -The easiest way to get started experimenting with the example smart contracts, is to use GitPod. Run the smart contracts directly from the browser, without having to install tools, cloning the repo, building the code and deploying it to testnet. - -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/stellar/soroban-examples) +The easiest way to get started experimenting with the example smart contracts, is to use Devcontainers. Run the smart +contracts directly in a browser-based IDE or using a Devcontainer as your local VSCode backend, without any config +or DevOps overhead. + +
+Devcontainers +

+ +
+ + Open in Codespaces + +
+
+ + Open in Codeanywhere + +
+ +**Learn more about how Devcontainers are used in this repo:** +- Running [Devcontainers Locally](./devcontainer.md) +- Check out the [Devcontainer config](./.devcontainer/devcontainer.json) ## Installation Stellar smart contracts are written in the [Rust](https://www.rust-lang.org/) programming language and can be deployed to the testnet or mainnet. @@ -148,6 +167,5 @@ Contributions are welcome, please create a pull request with the following infor - [Smart Contract Documentation](https://developers.stellar.org/docs/build) - [Getting Started Guide](https://developers.stellar.org/docs/build/smart-contracts/getting-started) - [Example descriptions in the documentation](https://developers.stellar.org/docs/build/smart-contracts/example-contracts) -- [Link to examples in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0) - [Stellar Developers Discord server](https://discord.gg/stellardev) diff --git a/assets/devcontainer-vscode-local.png b/assets/devcontainer-vscode-local.png new file mode 100644 index 00000000..9f887223 Binary files /dev/null and b/assets/devcontainer-vscode-local.png differ diff --git a/build_devcontainer.sh b/build_devcontainer.sh new file mode 100755 index 00000000..d2121576 --- /dev/null +++ b/build_devcontainer.sh @@ -0,0 +1,67 @@ +#!/bin/bash + +# Define devcontainer configuration directory +devcontainer_dir=".devcontainer" + +# Define configuration file path +config_file="devcontainer.json" + +# Pass in values as parameters +# Example: +# ./build_devcontainer.sh stellar/vsc-soroban-examples-prebuild \ +# stellar/vsc-soroban-examples-oci-prebuild ~/cache + +pre_build_image=$1 +oci_pre_build_image=$2 +local_build_cache=$3 + +build_details_dir="z-dc-build-info/" +build_details_file="build-details.json" + +if [ ! -e "${build_details_dir}" ]; then + mkdir -p "${build_details_dir}" +fi + +if [ ! -e "${build_details_dir}${build_details_file}" ]; then + touch "${build_details_dir}${build_details_file}" +fi + +# Build the devcontainer +output=$(devcontainer build \ + --workspace-folder . \ + --config $devcontainer_dir/$config_file \ + --cache-from type=registry,ref="${pre_build_image}" \ + --cache-from type=local,src="${local_build_cache}",mode=max \ + --cache-to type=local,dest="${local_build_cache}",mode=max,oci-mediatypes=true,image-manifest=true \ + --output type=image,name="${pre_build_image}") + +echo " βœ… Devcontainer built" +# Extract imageName from JSON output using jq +image_name=$(echo "$output" | jq -r '.imageName[0]') +echo " πŸ”Ή Image name: ${image_name}" +docker inspect "${image_name}" >> "${build_details_dir}${build_details_file}" + +# Push new pre-build +docker tag "${image_name}":latest "${pre_build_image}":latest +docker push "${pre_build_image}":latest +echo " πŸ› οΈ New prebuild pushed ${pre_build_image}:latest" +echo " βš™οΈ Build info available at ${build_details_dir}${build_details_file}" +echo 'Y' | docker image prune + +# Build the devcontainer again with OCI Output +oci_output=$(devcontainer build \ + --workspace-folder . \ + --config $devcontainer_dir/$config_file \ + --cache-from type=registry,ref="${pre_build_image}" \ + --cache-from type=registry,ref="${oci_pre_build_image}" \ + --cache-to type=registry,ref="${oci_pre_build_image}",mode=max,oci-artifact=true \ + --output type=image,name="${oci_pre_build_image}",mode=max,oci-mediatypes=true,compression=zstd) + +# Extract ociImageName from JSON output using jq +oci_image_name=$(echo "$oci_output" | jq -r '.imageName[0]') + +# Push new OCI pre-build +docker tag "${oci_image_name}":latest "${oci_pre_build_image}":latest +docker push "${oci_pre_build_image}":latest + +echo 'Y' | docker image prune diff --git a/devcontainer.md b/devcontainer.md new file mode 100644 index 00000000..9ca5e1bc --- /dev/null +++ b/devcontainer.md @@ -0,0 +1,206 @@ +## Running Devcontainers + +Building Devcontainers locally. + +### Build image locally + +Requires: +- [Devcontainer CLI](https://github.com/devcontainers/cli) + +Install Devcontainer CLI: +``` +npm install -g @devcontainers/cli +``` + +**Local build script:** +``` +devcontainer build \ + --workspace-folder . \ + --config .devcontainer/devcontainer.json +``` + +### Build and Run Remote Devcontainer on Github Codespaces + +Run in browser. + +**Launch via Link:** +- Run on Codespaces +- Click "Open in Codespaces" button in [ ** README️** ](./README.md) + +**Launch via Github CLI:** + +Requires: +- [Github CLI](https://cli.github.com/) + +Install Github CLI: +https://github.com/cli/cli#installation + +Create new Codespace: +``` +# Create a new Codespace +gh codespace create --repo stellar/soroban-examples -b main --status --web -l WestUs2 +``` + +Delete existing Codespaces: +``` +# Delete all Codespaces (confirmation auto-approved) +echo 'Y' | gh codespace delete --all --force +``` + +View Remote Logs or SSH into Codespaces Devcontainer from local: +``` +gh codespace ssh +gh codespace logs +``` + +### Use Remote Devcontainer on Github Codespaces as Local VS Code IDE backend + +Run in your local VS Code IDE with Codespaces backend with all of your local settings in place. + +- Install [Devcontainers VSCode ext](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +- Install [Codespaces VSCode ext](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) +- Open `Remote Explorer` View +- Select `Github Codespaces` from dropdown +- Click `Create Codespace` button +- Enter name of repository `stellar/soroban-examples` + +![img.png](assets/devcontainer-vscode-local.png) + +## Devcontainer Build Details + +**Base Image:** + +- [mcr.microsoft.com/devcontainers/rust](https://hub.docker.com/r/microsoft/devcontainers-rust) + - Container OS: Debian + +**Features:** + +_All of these features are officially listed on https://containers.dev/features_ + +- [ghcr.io/devcontainers/features/common-utils:2](https://github.com/devcontainers/features/tree/main/src/common-utils) + - Installs CLI utils for zsh + - Sets non-root user and UID + - Upgrades packages + +- [ghcr.io/devcontainers/features/rust:1](https://github.com/devcontainers/features/tree/main/src/rust) + - Sets rustup install profile + - Sets rust targets + - Adds VSCode extensions for Rust dev + - Update containerEnv for: `CARGO_HOME`, `RUSTUP_HOME` and adds Cargo to `PATH` + - Adds `SYS_PTRACE` Capability which enables `LLDB` debugging in Linux + - Adds `seccomp=unconfined` during the build process to allow full range of system calls + +**ENV Vars:** +- `ENV CARGO_INCREMENTAL=0` + - Force disabling of incremental compilation + - Rationale: + - Dependencies unchanged: Layer cache hit (No need for incremental compilation) + - Dependencies changed: Layer cache miss and complete rebuild (No use for incremental compilation) + - Incremental compilation in Devcontainers generates extra artifacts that make caching layers bigger + with no benefit +- `ENV DEBIAN_FRONTEND=noninteractive` + - Accepts the default answer for all questions for apt-get installs +- `PKG_CONFIG_PATH='/usr/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/share/pkgconfig'` + - Specifies additional paths in which pkg-config will search for its .pc files +- `CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse` + - Protocol which uses HTTPS to download only necessary crates + +## Multi-Layer Caching Strategy + +These caching layers are powered by Docker [BuildKit](https://docs.docker.com/build/buildkit/). + +**Cache Layer 1** + +Build Kit inline cache. Enabled by a simple env var: `BUILDKIT_INLINE_CACHE=1` + +Inline cache embeds cache metadata into the image config. + +[Inline Embedded Cache](https://github.com/moby/buildkit?tab=readme-ov-file#inline-push-image-and-cache-together) + +**Cache Layer 2** + +[Local file caching](https://docs.docker.com/build/cache/backends/local/). The local cache store is simple and +relatively effectively and can be used with other caching layers. + +Info on [OCI image layout](https://docs.docker.com/build/exporters/oci-docker/). + +Example data cache: +```json +{ + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "config": { + "mediaType": "application/vnd.buildkit.cacheconfig.v0", + "digest": "sha256:0c14d3e9278b63f9d4ce9ac93a01037db185bba8ab7765bb1921c70a92b0cdea", + "size": 5007 + }, + "layers": [ + { + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "digest": "sha256:0289a1845fafa2e548c7bfc34e2dfcc10ac9b80d7f31620de9b37125572c7c08", + "size": 233 + } + ] +} +``` + +**Cache Layer 3** + +Images with embedded caching and metadata to registries such as OCI artifacts and manifests. + +[Registry Cache](https://docs.docker.com/build/exporters/image-registry/) + +**Cache Layer 4** + +Github Prebuilds. Github prebuild are definitely the most effective caching layer and greatly +speed up Github Codespaces. + +```text +# Generate manifest +/.codespaces/agent/bin/codespaces prebuild manifest --config-id $CONFIGURATION_ID --image-version Raw +``` + +Other caching options: +- AWS S3 buckets +- Github Action caches + +Ultimately though, we just want the end-user developer to have a good experience and for the coding environment to +load up quickly and be responsive. + +## Devcontainer GH Actions + +`validate-devcontainer-json.yml`: Validates Devcontainer JSON Schema + +`build-and-test-devcontainer.yml` Validates bash scripts and builds devcontainer with CLI + +**Run GH Actions Locally to test build** + +Requires: + +- [act - Locall GH Action runner](https://github.com/nektos/act) +- [Github CLI](https://cli.github.com/) + +Install act: + +``` +brew install act +``` + +Setup act: + +``` +gh act -W '.github/workflows/' +``` + +List and run GH Workflows + +``` +gh act --list +gh act --job shellcheck-and-test +``` + +## Learn about Devcontainers + +- [Devcontainers Briefing](https://github.com/anataliocs/comprehensive-devcontainer/blob/main/briefing.md) +- [Devcontainers Properties Reference](https://github.com/anataliocs/comprehensive-devcontainer/blob/main/README.md) +- [Devcontainers devcontainer.json Reference](https://containers.dev/implementors/json_reference/) +- [Available Features](https://containers.dev/features)