xdrpp / stc

Stellar transaction compiler

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.

stc's Issues

Add support for providing arbitrary network passphrases at the command line rather than through ini files

What problem does your feature solve?

Use stc to build transactions for networks that are not the Stellar testnet or pubnet in scripts without writing files to disk.

What would you like to see?

stc -net take values other than test or pub that can be interpreted as the network passphrase for signing.

What alternatives are there?

The ability to pass a config file location at the command line so that config files do not need to be stored in arbitrary locations that a script may not have access to for creating temporary network configs.

cc @JakeUrban

txrep for ACCOUNT_MERGE operation leaves off 'accountMergeOp' in body.

I was doing test cases for the JavaScript implementation of Txrep and was comparing to the txrep generated from this to mine and I found one that didn't match.

It's a simple account merge operation (I just used the same source as destination but I don't think it matters).

XDR:

AAAAAKjbIbAJn+ysBWgp/jsZEx4ccbB3oicFelkopFq7rB38AAAAZAAE4pgAAAABAAAAAAAAAAAAAAABAAAAAQAAAACo2yGwCZ/srAVoKf47GRMeHHGwd6InBXpZKKRau6wd/AAAAAgAAAAAqNshsAmf7KwFaCn+OxkTHhxxsHeiJwV6WSikWrusHfwAAAAAAAAAAA==

Generated txrep:

tx.sourceAccount: GCUNWINQBGP6ZLAFNAU74OYZCMPBY4NQO6RCOBL2LEUKIWV3VQO7YOBF
tx.fee: 100
tx.seqNum: 1375042369748993
tx.timeBounds._present: false
tx.memo.type: MEMO_NONE
tx.operations.len: 1
tx.operations[0].sourceAccount._present: true
tx.operations[0].sourceAccount: GCUNWINQBGP6ZLAFNAU74OYZCMPBY4NQO6RCOBL2LEUKIWV3VQO7YOBF
tx.operations[0].body.type: ACCOUNT_MERGE
tx.operations[0].body.destination: GCUNWINQBGP6ZLAFNAU74OYZCMPBY4NQO6RCOBL2LEUKIWV3VQO7YOBF
tx.ext.v: 0
signatures.len: 0

Where I expected it to be body.accountMergeOp.destination, it actually is body.destination. Is that correct and ACCOUNT_MERGE is an outlier where it leaves off the name of the operation?

Signatures for custom networks don't round trip

I'm having trouble getting a custom network passphrase to be used as verified successfully. If I sign a transaction using stc with a custom network and then parse that transaction with stc, the signature has a comment in parenthesis saying it is invalid. When I attempt to verify the transaction myself it appears to be invalid.

$ export STCDIR=$(mktemp -d)
$ export STCNET=sidenet 

$ echo '[net "sidenet"]
network-id = "Sidenet"
native-asset = USD' > $STCDIR/$STCNET.net

$ account1=$(stc -nopass -keygen account1 | head -n1)
$ account2=$(stc -nopass -keygen account2 | head -n1)
$ signer=$(stc -nopass -keygen signer | head -n1)

$ echo -n "type: ENVELOPE_TYPE_TX
tx.sourceAccount: $account1
tx.seqNum: 1
tx.operations.len: 1
tx.operations[0].sourceAccount._present: false
tx.operations[0].body.type: PAYMENT
tx.operations[0].body.paymentOp.destination: $account2
tx.operations[0].body.paymentOp.asset: XLM
tx.operations[0].body.paymentOp.amount: 2" | stc -c -key signer -
AAAAAgAAAACRvmF5v6x7nFm74hWvLFeuDlX19dGiG1V5FPnIxT3BbgAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAMKllbWMqkk4QRxkT9UBYBlTAc6HQ/BWETHi2IgzvMi9AAAAAAAAAAAAAAACAAAAAAAAAAEsRDafAAAAQMoiXGJlIEHZhxbCDT6eGyDHjHifw9sBwz2325ddLBh9wJw47ez/q5KyjnW1qo/tD91asxXXP0IcuLLQ0wV6Gws=

Take the output and pipe it back in and I see this:

$ echo -n 'AAAAAgAAAACRvmF5v6x7nFm74hWvLFeuDlX19dGiG1V5FPnIxT3BbgAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAMKllbWMqkk4QRxkT9UBYBlTAc6HQ/BWETHi2IgzvMi9AAAAAAAAAAAAAAACAAAAAAAAAAEsRDafAAAAQMoiXGJlIEHZhxbCDT6eGyDHjHifw9sBwz2325ddLBh9wJw47ez/q5KyjnW1qo/tD91asxXXP0IcuLLQ0wV6Gws=' | stc -
type: ENVELOPE_TYPE_TX
tx.sourceAccount: GCI34YLZX6WHXHCZXPRBLLZMK6XA4VPV6XI2EG2VPEKPTSGFHXAW5BKN
tx.fee: 0
tx.seqNum: 1
tx.timeBounds._present: false
tx.memo.type: MEMO_NONE
tx.operations.len: 0
tx.ext.v: 0
signatures.len: 1
signatures[0].hint: 2c44369f (bad signature/unknown key/sidenet is wrong network)
signatures[0].signature: 83e5a0aceb3c15be1eff154a02300d567acbedf5c8e4a9d96c3a8069fa681761ae07fd299feb8b8a4facbc2a3f9ec3326c372d58ea908eda2685bc3357da010c

Error loading module requirements: unknown revision b257d8ace4e0

Building a project that uses the following version of Stellar Go SDK (and probably many others before it) fails due to unknown revision: https://github.com/stellar/go/blob/f7c9e85f25a8e998eca1e046121a229de412d9ff/go.sum#L244

go: github.com/xdrpp/[email protected]: unknown revision b257d8ace4e0

As you can see from the above modfile, it freezes github.com/xdrpp/stc at commit b257d8ace4e0. However, it appears this commit no longer exists in this repo?

Was the entire repository force-pushed over with new commit history?

Is there a way to get access to commit b257d8ace4e0 so I can diff it against the current head?

go get gets stc that does not support new muxed account format

When I run the go get install instructions below I get a version of stc that does not have muxed accounts implemented.

go get -u github.com/xdrpp/stc/cmd/stc

I can see that there is a commit on master that has muxed accounts, but it seems like that change hasn't been propagated to the go1 branch which is where go get is pulling from.

As a side note, the go1 branch setup is pretty unique and not intuitive. I haven't seen any other Go project serve different code on master and go1.

Tests that don't run because of i < i

There are two tests in stc that don't look like they execute. They are inside for loops with i < i, and so will never run.

stc/stc_test.go

Lines 20 to 55 in 2d03e9b

	func TestShortStrKey(t *testing.T) {
	mykey := "GDFR4HZMNZCNHFEIBWDQCC4JZVFQUGXUQ473EJ4SUPFOJ3XBG5DUCS2G"
	for i := 1; i < i; i++ {
	var pk PublicKey
	var sgk SignerKey
	if n, err := fmt.Sscan(mykey[:len(mykey)-i], &pk); err == nil ||
	n >= 1 {
	t.Errorf("incorrectly accepted PubKey strkey of length %d",
	len(mykey)-1)
	}
	if n, err := fmt.Sscan(mykey[:len(mykey)-i], &sgk); err == nil ||
	n >= 1 {
	t.Errorf("incorrectly accepted SignerKey strkey of length %d",
	len(mykey)-1)
	}
	}
	}
	func TestLongStrKey(t *testing.T) {
	mykey := "GDFR4HZMNZCNHFEIBWDQCC4JZVFQUGXUQ473EJ4SUPFOJ3XBG5DUCS2G"
	mykey += mykey
	for i := 1; i < i; i++ {
	var pk PublicKey
	var sgk SignerKey
	if n, err := fmt.Sscan(mykey[:len(mykey)-i], &pk); err == nil ||
	n >= 1 {
	t.Errorf("incorrectly accepted PubKey strkey of length %d",
	len(mykey)-1)
	}
	if n, err := fmt.Sscan(mykey[:len(mykey)-i], &sgk); err == nil ||
	n >= 1 {
	t.Errorf("incorrectly accepted SignerKey strkey of length %d",
	len(mykey)-1)
	}
	}
	}

Add support for protocol 19 and P strkey

Now that CAP-21 and CAP-40 are being implemented we should add the new xdr, which should be trivial, and add support for the new SEP-23 strkey for the CAP-40 signer.

The new xdr is available at the branch below. I gave it a quick try and it appears to work fine:
stellar/stellar-core#3377
https://github.com/sisuresh/stellar-core branch cap21-40-2

The one thing that needs coding is the new P strkey, that is documented here:
stellar/stellar-protocol#1014