README
¶
Stellar Go
This repo is the home for all of the public go code produced by SDF. In addition to various tools and services, this repository is the SDK from which you may develop your own applications that integrate with the stellar network.
Dependencies
NOTE: this repo presently uses a fork of govalidator that incorporates https://github.com/asaskevich/govalidator/pull/165. Vendored dependencies must be restored (using glide install) to get proper behaviour. In other words, this repo is not currently "go gettable"
This repository depends upon a number of external dependencies, and we use Glide to manage them. Glide is used to populate the vendor directory, ensuring that builds are reproducible even as upstream dependencies are changed. Please see the Glide website for installation instructions.
You can use Glide yourself in your project and add stellar go as a vendor'd dependency, or you can just drop this repos as $GOPATH/src/github.com/stellar/go to import it the canonical way (you still need to run glide install).
When creating this project, we had to decide whether or not we committed our external dependencies to the repo. We decided that we would not, by default, do so. This lets us avoid the diff churn associated with updating dependencies while allowing an acceptable path to get reproducible builds. To do so, simply install glide and run glide install in your checkout of the code. We realize this is a judgement call; Please feel free to open an issue if you would like to make a case that we change this policy.
Directory Layout
In addition to the other top-level packages, there are a few special directories that contain specific types of packages:
- clients contains packages that provide client packages to the various Stellar services.
- exp contains experimental packages. Use at your own risk.
- handlers contains packages that provide pluggable implementors of
http.Handlerthat make it easier to incorporate portions of the Stellar protocol into your own http server. - support contains packages that are not intended for consumption outside of Stellar's other packages. Packages that provide common infrastructure for use in our services and tools should go here, such as
dborlog. - support/scripts contains single-file go programs and bash scripts used to support the development of this repo.
- services contains packages that compile to applications that are long-running processes (such as API servers).
- tools contains packages that compile to command line applications.
Each of these directories have their own README file that explain further the nature of their contents.
Other packages
In addition to the packages described above, this repository contains various packages related to working with the Stellar network from a go program. It's recommended that you use godoc to browse the documentation for each.
Package source layout
While much of the code in individual packages is organized based upon different developers' personal preferences, many of the packages follow a simple convention for organizing the declarations inside of a package that aim to aid in your ability to find code.
In each package, there may be one or more of a set of common files:
- main.go: Every package should have a
main.gofile. This file contains the package documentation (unless a separatedoc.gofile is used), all of the exported vars, consts, types and funcs for the package. - internal.go: This file should contain unexported vars, consts, types, and funcs. Conceptually, it should be considered the private counterpart to the
main.gofile of a package - errors.go: This file should contains declarations (both types and vars) for errors that are used by the package.
- example_test.go: This file should contains example tests, as described at https://blog.golang.org/examples.
In addition to the above files, a package often has files that contains code that is specific to one declared type. This file uses the snake case form of the type name (for example loggly_hook.go would correspond to the type LogglyHook). This file should contain method declarations, interface implementation assertions and any other declarations that are tied solely to to that type.
Each non-test file can have a test counterpart like normal, whose name ends with _test.go. The common files described above also have their own test counterparts... for example internal_test.go should contains tests that test unexported behavior and more commonly test helpers that are unexported.
Generally, file contents are sorted by exported/unexported, then declaration type (ordered as consts, vars, types, then funcs), then finally alphabetically.
Test helpers
Often, we provide test packages that aid in the creation of tests that interact with our other packages. For example, the support/db package has the support/db/dbtest package underneath it that contains elements that make it easier to test code that accesses a SQL database. We've found that this pattern of having a separate test package maximizes flexibility and simplifies package dependencies.
Coding conventions
- Always document exported package elements: vars, consts, funcs, types, etc.
- Tests are better than no tests.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package address provides utility functions for working with stellar addresses.
|
Package address provides utility functions for working with stellar addresses. |
|
Package amount provides utilities for converting numbers to/from the format used internally to stellar-core.
|
Package amount provides utilities for converting numbers to/from the format used internally to stellar-core. |
|
Package build implements a builder system for constructing various xdr structures used by the stellar network, most importanly transactions.
|
Package build implements a builder system for constructing various xdr structures used by the stellar network, most importanly transactions. |
|
Package clients contains sub-packages that provide client access to the various stellar services.
|
Package clients contains sub-packages that provide client access to the various stellar services. |
|
horizon
Package horizon provides client access to a horizon server, allowing an application to post transactions and lookup ledger information.
|
Package horizon provides client access to a horizon server, allowing an application to post transactions and lookup ledger information. |
|
stellarcore
Package stellarcore is a client library for communicating with an instance of stellar-core using through the server's HTTP port.
|
Package stellarcore is a client library for communicating with an instance of stellar-core using through the server's HTTP port. |
|
Package crc16 is implementation according to CCITT standards.
|
Package crc16 is implementation according to CCITT standards. |
|
examples
|
|
|
Package exp houses experimental packages related to Stellar developement
|
Package exp houses experimental packages related to Stellar developement |
|
crypto/derivation
Package derivation provides functions for ed25519 key derivation as described in: https://github.com/satoshilabs/slips/blob/master/slip-0010.md
|
Package derivation provides functions for ed25519 key derivation as described in: https://github.com/satoshilabs/slips/blob/master/slip-0010.md |
|
handlers
|
|
|
federation
Package federation provides a pluggable handler that satisfies the Stellar federation protocol.
|
Package federation provides a pluggable handler that satisfies the Stellar federation protocol. |
|
Package meta provides helpers for processing the metadata that is produced by stellar-core while processing transactions.
|
Package meta provides helpers for processing the metadata that is produced by stellar-core while processing transactions. |
|
Package network contains functions that deal with stellar network passphrases and IDs.
|
Package network contains functions that deal with stellar network passphrases and IDs. |
|
Package price implements functions to ease working with stellar price values.
|
Package price implements functions to ease working with stellar price values. |
|
protocols
|
|
|
Package services contains sub-packages that provide long-running applications such as API servers.
|
Package services contains sub-packages that provide long-running applications such as API servers. |
|
bifrost/stress
Structs and functions used in stress tests
|
Structs and functions used in stress tests |
|
horizon/internal/actions
Package actions provides the infrastructure for defining and executing actions (code that is triggered in response to an client request) on horizon.
|
Package actions provides the infrastructure for defining and executing actions (code that is triggered in response to an client request) on horizon. |
|
horizon/internal/assets
Package assets is a simple helper package to help convert to/from xdr.AssetType values
|
Package assets is a simple helper package to help convert to/from xdr.AssetType values |
|
horizon/internal/codes
Package codes is a helper package to help convert to transaction and operation result codes to strings used in horizon.
|
Package codes is a helper package to help convert to transaction and operation result codes to strings used in horizon. |
|
horizon/internal/context/requestid
Package requestid provides functions to support embedded and retrieving a request id from a go context tree
|
Package requestid provides functions to support embedded and retrieving a request id from a go context tree |
|
horizon/internal/db2
Package db2 is the replacement for db.
|
Package db2 is the replacement for db. |
|
horizon/internal/db2/core
Package core contains database record definitions useable for reading rows from a Stellar Core db
|
Package core contains database record definitions useable for reading rows from a Stellar Core db |
|
horizon/internal/db2/history
Package history contains database record definitions useable for reading rows from a the history portion of horizon's database
|
Package history contains database record definitions useable for reading rows from a the history portion of horizon's database |
|
horizon/internal/db2/sqx
Package sqx contains utilities and extensions for the squirrel package which is used by horizon to generate sql statements.
|
Package sqx contains utilities and extensions for the squirrel package which is used by horizon to generate sql statements. |
|
horizon/internal/ingest
Package ingest contains the ingestion system for horizon.
|
Package ingest contains the ingestion system for horizon. |
|
horizon/internal/ingest/participants
Package participants contains functions to derive a set of "participant" addresses for various data structures in the Stellar network's ledger.
|
Package participants contains functions to derive a set of "participant" addresses for various data structures in the Stellar network's ledger. |
|
horizon/internal/ledger
Package ledger provides useful utilities concerning ledgers within stellar, specifically as a central location to store a cached snapshot of the state of both horizon's and stellar-core's views of the ledger.
|
Package ledger provides useful utilities concerning ledgers within stellar, specifically as a central location to store a cached snapshot of the state of both horizon's and stellar-core's views of the ledger. |
|
horizon/internal/log
Package log provides the logging facilities used for horizon.
|
Package log provides the logging facilities used for horizon. |
|
horizon/internal/paths
Package paths provides utilities and facilities for payment paths as needed by horizon.
|
Package paths provides utilities and facilities for payment paths as needed by horizon. |
|
horizon/internal/reap
Package reap contains the history reaping subsystem for horizon.
|
Package reap contains the history reaping subsystem for horizon. |
|
horizon/internal/render/sse
This package contains the Server Sent Events implementation used by horizon.
|
This package contains the Server Sent Events implementation used by horizon. |
|
horizon/internal/resource
Package resource contains the type definitions for all of horizons response resources.
|
Package resource contains the type definitions for all of horizons response resources. |
|
horizon/internal/simplepath
Package simplepath provides an implementation of paths.Finder that performs a breadth first search for paths against a stellar-core's database
|
Package simplepath provides an implementation of paths.Finder that performs a breadth first search for paths against a stellar-core's database |
|
horizon/internal/test
Package test contains simple test helpers that should not have any dependencies on horizon's packages.
|
Package test contains simple test helpers that should not have any dependencies on horizon's packages. |
|
horizon/internal/test/db
Package db provides helpers to connect to test databases.
|
Package db provides helpers to connect to test databases. |
|
horizon/internal/test/trades
Common infrastructure for testing Trades
|
Common infrastructure for testing Trades |
|
horizon/internal/txsub
Package txsub provides the machinery that horizon uses to submit transactions to the stellar network and track their progress.
|
Package txsub provides the machinery that horizon uses to submit transactions to the stellar network and track their progress. |
|
horizon/internal/txsub/results/db
Package results provides an implementation of the txsub.ResultProvider interface backed using the SQL databases used by both stellar core and horizon
|
Package results provides an implementation of the txsub.ResultProvider interface backed using the SQL databases used by both stellar core and horizon |
|
horizon/internal/txsub/sequence
Package sequence providers helpers to manage sequence numbers on behalf of horizon clients.
|
Package sequence providers helpers to manage sequence numbers on behalf of horizon clients. |
|
horizon/internal/utf8
Package utf8 contains utilities for working with utf8 data.
|
Package utf8 contains utilities for working with utf8 data. |
|
Package strkey is an implementation of StrKey, the address scheme for the StellarNetwork.
|
Package strkey is an implementation of StrKey, the address scheme for the StellarNetwork. |
|
support
|
|
|
app
Package app provides vars that can be populated via "-X" linker flags to provide global application metadata, such as build time or version.
|
Package app provides vars that can be populated via "-X" linker flags to provide global application metadata, such as build time or version. |
|
config
Package config provides a common infrastructure for reading configuration data stored in local TOML files.
|
Package config provides a common infrastructure for reading configuration data stored in local TOML files. |
|
db
Package db is the base package for database access at stellar.
|
Package db is the base package for database access at stellar. |
|
db/dbtest
Package dbtest is a package to ease the pain of developing test code that works against external databases.
|
Package dbtest is a package to ease the pain of developing test code that works against external databases. |
|
db/sqlutils
Package sqlutils contains utility functions for manipulating strings of SQL
|
Package sqlutils contains utility functions for manipulating strings of SQL |
|
errors
Package errors provides the common infrastructure for managing errors.
|
Package errors provides the common infrastructure for managing errors. |
|
http
Package http provides easy access to Stellar's best practices for building http servers.
|
Package http provides easy access to Stellar's best practices for building http servers. |
|
http/httptest
Package httptest enhances the stdlib net/http/httptest package by integrating it with gopkg.in/gavv/httpexpect.v1, reducing the boilerplate needed for http tests.
|
Package httptest enhances the stdlib net/http/httptest package by integrating it with gopkg.in/gavv/httpexpect.v1, reducing the boilerplate needed for http tests. |
|
http/mutil
Package mutil contains various functions that are helpful when writing http middleware.
|
Package mutil contains various functions that are helpful when writing http middleware. |
|
log
Package log provides the common logging facilities used by the Stellar Development foundation.
|
Package log provides the common logging facilities used by the Stellar Development foundation. |
|
test
Package test contains simple test helpers that should not have any service-specific dependencies.
|
Package test contains simple test helpers that should not have any service-specific dependencies. |
|
tools
|
|
|
stellar-sign
stellar-sign is a small interactive utility to help you contribute a signature to a transaction envelope.
|
stellar-sign is a small interactive utility to help you contribute a signature to a transaction envelope. |
|
Package xdr contains the generated code for parsing the xdr structures used for stellar.
|
Package xdr contains the generated code for parsing the xdr structures used for stellar. |