Stellar transaction compiler

stc is a library and command-line tool for creating, editing, and manipulating transactions for the Stellar blockchain. It supports translating back and forth between human-readable txrep format and Stellar's native binary XDR representation, as well submitting transactions to the network, querying account status, and more. The library makes it easy to build and submit transactions programmatically from go applications.

Installing stc for non-developers

To install or upgrade this software if you don't plan to hack on it, run the following:

GOPROXY=direct go install github.com/xdrpp/stc/...@latest

The GOPROXY environment variable requests the latest version of the software from github, instead of calling home to Google's module proxy and allowing Google to supply an incorrect or stale version of the software (which unfortunately happened to the author).

Once this command completes, put the ~/go/bin directory on your path and you should be able to run stc.

For most purposes you can simply depend on the latest release. However, if you wish to install the latest development version from within a go module (a directory with a go.mod file), you will need to specify the go1 branch to get autogenerated files that are not available on the master branch. Do so by running:

rm -rf ~/go/src/github.com/xdrpp/stc
GOPROXY=direct go get github.com/xdrpp/stc/...@go1

Assuming your GOPATH is in the default location of ~/go, the rm command is necessary when upgrading because some go get limitation leaves your tree in a detached state, so that go get -u cannot pull from the remote go1 branch.

Using Docker

To use stc within a containerised environment it is possible to run stc using our Docker image. All transactions are generated inside the container and are made available to the host system through volume mounts.

docker run -it --rm -v /etc/ssl/certs/:/etc/ssl/certs/ -v /tmp:/tmp -v $HOME/.config/stc:/root/.config/stc xdrpp-stc

Shell Alias

To make containerised usage seamless you can also create a shell alias.

# Stellar Transaction Compiler
alias stc='docker run -it --rm -v /etc/ssl/certs/:/etc/ssl/certs/ -v /tmp:/tmp -v $HOME/.config/stc:/root/.config/stc xdrpp-stc'

Once the alias is setup you will be able to interact with stc directly from the host system or within Kubernetes.

stc transaction.xdr

Using stc

See the stc(1) man page for the command-line tool. There's also a video of a presentation and demo of stc at the 2020 Stellar Meridian conference.

See pkg.go.dev for documentation of the go library.

Building stc for developers

Because stc requires autogenerated files, the master branch is not meant to be compiled under $GOPATH, but rather in a standalone directory with make.

Furthermore, to build stc from the master branch, you also need to have the goxdr compiler. Because stc is codeveloped with goxdr, you may want to use a development version of goxdr, which you can do by placing a the goxdr source tree (or a symbolic link to it) in cmd/goxdr. If you don't want to do this, but are okay just using a snapshot of goxdr, you can run:

make depend

Once you have goxdr, you can build stc by running:

make

To install stc, you will also need pandoc to format the man page.

Documentation for unreleased versions

When new features are added, the latest godoc documentation is available here.

Building stc for experimental protocol versions

To build a version of stc supporting changes to the transaction format that have not yet been merged into stellar-core, you can fetch alternate XDR files with either of the commands:

./make-xdr BRANCH

./make-xdr REPO BRANCH

Here REPO is the git repository from which to pull the non-standard version of stellar-core (default https://github.com/stellar/stellar-core.git), and BRANCH is either a branch name in the remote repository or a github pull request number. To revert to the standard XDR, simply run ./make-xdr with no arguments.

Disclaimer

There is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who modifies and/or conveys the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.