Categorygithub.com/xdrpp/stc
modulepackage
0.2.0
Repository: https://github.com/xdrpp/stc.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
26
Dependents
1
Files
1.9k SLOC

# README

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 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 the godoc documentation for the library. Because stc contains auto-generated source files that are not on the master branch in git, you may wish to view the documentation locally, rather than through on-line godoc viewers that may not show you the correct branch. To view godoc, after installing stc with go get as described above, start a local godoc server and open it in your browser as follows:

godoc -index -http localhost:6060 &
xdg-open http://localhost:6060/pkg/github.com/xdrpp/stc

On MacOS computers, run open instead of xdg-open, or just paste the URL into your browser.

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.

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.

# Packages

No description provided by the author
Ini file parser library.
Internal functions for the stc library.
The stx package provides a compiled go representation of Stellar's XDR data structures.

# Functions

Return the path to a file under the user's configuration directory.
Load a network from under the ConfigPath() ($STCDIR) directory.
Break a MuxedAccount into its consituent parts.
Reads a private key from standard input.
Try to determine whether a request to Horizon indicates the operation is worth retrying.
Reads a private key from a file, prompting for a passphrase if the key is in ASCII-armored symmetrically-encrypted GPG format.
Load a Stellar network from an INI files.
Helper function for initializing a Memo with Type == MEMO_HASH.
Helper function for initializing a Memo with Type == MEMO_ID.
Helper function for initializing a Memo with Type == MEMO_NONE.
Helper function for initializing a Memo with Type == MEMO_RETURN.
Helper function for initializing a Memo with Type == MEMO_TEXT.
No description provided by the author
No description provided by the author
Created a MuxedAccount from its consituent parts.
No description provided by the author
Return a pointer to an account ID.
Allocate an int64 when initializing types that take an XDR hyper*.
Generates a new Stellar keypair and returns the PrivateKey.
Create a signer that requires the hash pre-image of some hash value x.
Create a signer for a particular public key and weight.
Allocate a string when initializing types that take an XDR *string<>.
No description provided by the author
Allocate a uint64 when initializing types that take an XDR unsigned hyper*.
Allocate a uint32 when initializing types that take an XDR int*.
Parse a series of INI configuration files specified by paths, followed by the global or built-in stc.conf file.
Assign a set of values to successive fields of an XDR structure in a type-safe way, flattening out nested structures.
Parse a TransactionEnvelope from base64-encoded binary XDR format.
Parse a transaction in human-readable Txrep format into a TransactionEnvelope.
Convert a TransactionEnvelope to base64-encoded binary XDR format.
No description provided by the author

# Constants

Largest 64-bit signed integer (9223372036854775807).

# Variables

When a user does not have an stc.conf configuration file, the library searches for one in $STCDIR/stc.conf, then /etc/stc.conf, then ../share/stc.conf (relative to the executable path).
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Structs

EndSponsoringFutureReserves is an empty type that can be passed to TransactionEnvelope.Append() to append a new Operation with Body.Type == END_SPONSORING_FUTURE_RESERVES.
Distribution of offered or charged fees.
No description provided by the author
Go representation of the Horizon Fee Stats structure response.
Structure into which you can unmarshal JSON returned by a query to horizon for an account endpoint.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Inflation is an empty type that can be passed to TransactionEnvelope.Append() to append a new Operation with Body.Type == INFLATION.
Abstract type representing a Stellar private key.
An annotated SignerKey that can be used to authenticate transactions.
Ledger entries changed by a transaction.
No description provided by the author
This is a wrapper around the XDR TransactionEnvelope structure.
An error representing the failure of a transaction submitted to the Stellar network, and from which you can extract the full TransactionResult.

# Interfaces

Interface for placeholder types that are named by camel-cased versions of the OperationType enum and can be transformed into the body of an Operation.

# Type aliases

Set of annotations to show as comments when showing Stellar AccountID values.
No description provided by the author
AccountMerge is a type with the same fields as stx.MuxedAccount that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == ACCOUNT_MERGE and *Body.Destination() initialized from the fields of the AccountMerge.
AllowTrust is a type with the same fields as stx.AllowTrustOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == ALLOW_TRUST and *Body.AllowTrustOp() initialized from the fields of the AllowTrust.
BeginSponsoringFutureReserves is a type with the same fields as stx.BeginSponsoringFutureReservesOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == BEGIN_SPONSORING_FUTURE_RESERVES and *Body.BeginSponsoringFutureReservesOp() initialized from the fields of the BeginSponsoringFutureReserves.
BumpSequence is a type with the same fields as stx.BumpSequenceOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == BUMP_SEQUENCE and *Body.BumpSequenceOp() initialized from the fields of the BumpSequence.
ChangeTrust is a type with the same fields as stx.ChangeTrustOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CHANGE_TRUST and *Body.ChangeTrustOp() initialized from the fields of the ChangeTrust.
ClaimClaimableBalance is a type with the same fields as stx.ClaimClaimableBalanceOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CLAIM_CLAIMABLE_BALANCE and *Body.ClaimClaimableBalanceOp() initialized from the fields of the ClaimClaimableBalance.
Clawback is a type with the same fields as stx.ClawbackOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CLAWBACK and *Body.ClawbackOp() initialized from the fields of the Clawback.
ClawbackClaimableBalance is a type with the same fields as stx.ClawbackClaimableBalanceOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CLAWBACK_CLAIMABLE_BALANCE and *Body.ClawbackClaimableBalanceOp() initialized from the fields of the ClawbackClaimableBalance.
CreateAccount is a type with the same fields as stx.CreateAccountOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CREATE_ACCOUNT and *Body.CreateAccountOp() initialized from the fields of the CreateAccount.
CreateClaimableBalance is a type with the same fields as stx.CreateClaimableBalanceOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CREATE_CLAIMABLE_BALANCE and *Body.CreateClaimableBalanceOp() initialized from the fields of the CreateClaimableBalance.
CreatePassiveSellOffer is a type with the same fields as stx.CreatePassiveSellOfferOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == CREATE_PASSIVE_SELL_OFFER and *Body.CreatePassiveSellOfferOp() initialized from the fields of the CreatePassiveSellOffer.
No description provided by the author
A Fee Value is currently 32 bits, but could become 64 bits if CAP-0015 is adopted.
No description provided by the author
LiquidityPoolDeposit is a type with the same fields as stx.LiquidityPoolDepositOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == LIQUIDITY_POOL_DEPOSIT and *Body.LiquidityPoolDepositOp() initialized from the fields of the LiquidityPoolDeposit.
LiquidityPoolWithdraw is a type with the same fields as stx.LiquidityPoolWithdrawOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == LIQUIDITY_POOL_WITHDRAW and *Body.LiquidityPoolWithdrawOp() initialized from the fields of the LiquidityPoolWithdraw.
ManageBuyOffer is a type with the same fields as stx.ManageBuyOfferOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == MANAGE_BUY_OFFER and *Body.ManageBuyOfferOp() initialized from the fields of the ManageBuyOffer.
ManageData is a type with the same fields as stx.ManageDataOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == MANAGE_DATA and *Body.ManageDataOp() initialized from the fields of the ManageData.
ManageSellOffer is a type with the same fields as stx.ManageSellOfferOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == MANAGE_SELL_OFFER and *Body.ManageSellOfferOp() initialized from the fields of the ManageSellOffer.
No description provided by the author
PathPaymentStrictReceive is a type with the same fields as stx.PathPaymentStrictReceiveOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == PATH_PAYMENT_STRICT_RECEIVE and *Body.PathPaymentStrictReceiveOp() initialized from the fields of the PathPaymentStrictReceive.
PathPaymentStrictSend is a type with the same fields as stx.PathPaymentStrictSendOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == PATH_PAYMENT_STRICT_SEND and *Body.PathPaymentStrictSendOp() initialized from the fields of the PathPaymentStrictSend.
Payment is a type with the same fields as stx.PaymentOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == PAYMENT and *Body.PaymentOp() initialized from the fields of the Payment.
No description provided by the author
RevokeSponsorship is a type with the same fields as stx.RevokeSponsorshipOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == REVOKE_SPONSORSHIP and *Body.RevokeSponsorshipOp() initialized from the fields of the RevokeSponsorship.
SetOptions is a type with the same fields as stx.SetOptionsOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == SET_OPTIONS and *Body.SetOptionsOp() initialized from the fields of the SetOptions.
SetTrustLineFlags is a type with the same fields as stx.SetTrustLineFlagsOp that can be passed to TransactionEnvelope.Append() to append a new operation with Body.Type == SET_TRUST_LINE_FLAGS and *Body.SetTrustLineFlagsOp() initialized from the fields of the SetTrustLineFlags.
No description provided by the author
A SignerCache contains a set of possible Stellar signers.
No description provided by the author
No description provided by the author