go-monero

go-monero

A multi-platform Go library (and command line interface) for interacting with Monero servers either on clearnet or not (see Tor support), supporting daemon and wallet RPC, p2p commands and ZeroMQ.

Quick start

Command Line Interface

Under cmd/monero you'll find a command line interface that exposes most of the functionality that the library provides.

You can either install it by using Go building from scratch

$ GO111MODULE=on go get github.com/cirocosta/go-monero/cmd/monero

or fetching the binary for your distribution from the releases page. See INSTALL.md for details and examples.

Example

$ monero daemon get-transaction --txn 53c1ef0cff73d12294e3055400826905efc397814aacd7208921a9abfd1f6328
Hash:                   53c1ef0cff73d12294e3055400826905efc397814aacd7208921a9abfd1f6328
Fee (µɱ):               9.13
Fee per kB (µɱ):        6.416691832532602
In/Out:                 1/2
Size:                   1.4 KiB
Public Key:             fbc0ac2c62514f68134f543ce5c4efe51ec55a0952eb188dadf22dccc3c5ffdf
Age:                    20 minutes ago
Block:                  2406735
Confirmations:          4

Outputs

        STEALTH ADDR                                                        AMOUNT IDX
0       574e3a3dda7cde249a81c0a0637ce78999e114dd478479e3e04680ffdcd34c97    35307867
1       7d3e93ecfa2bd8c27f7a2bbd57488c1121924e58591b32e99be42da6ae249e9c    35307868


Input Key Image:        2cd588cbc9214e1b683a8c3f0d7c25b8e61779806051356dee1fac6cf42c0c7e

        RING MEMBER              TXID              BLK        AGE
0       ef729a26d047508fb1       1ed88a49d533e     2342514    2 months ago
1       33351ad5aed5df1c4b       e0782b630670d     2382635    1 month ago
2       df5b27b873dc93e423       a96889571eab7     2397359    1 week ago
3       f30b7e8a36b38d95dc       a3eede407f106     2401095    1 week ago
4       f684f88cd52ef0c39b       de3a7e7b8ced8     2401120    1 week ago
5       96b6addb19dfa8ea78       13c9063f09e05     2402375    6 days ago
6       cd573966c650555377       4639ecf7293c8     2403122    5 days ago
7       b9c6c95c0994266249       04800ff34ee29     2404029    3 days ago
8       c4b4d2549c9a731157       6ebad604e6d81     2405504    1 day ago
9       36516e699ceffb665b       e996d5b951ed1     2406458    9 hours ago
10      91ab8220d7d87e465f       9dd40e49611f1     2406541    6 hours ago

(^ ring member and txid shortened just in this README for brevity sake)

$ monero --help
Daemon, Wallet, and p2p command line monero CLI

Usage:
  monero [command]

Available Commands:
  completion  generate the autocompletion script for the specified shell
  daemon      execute remote procedure calls against a monero node
  help        Help about any command
  p2p         execute p2p commands against a monero node
  wallet      execute remote procedure calls against a monero wallet rpc server

Flags:
  -h, --help   help for monero

Use "monero [command] --help" for more information about a command.

$ monero daemon --help
execute remote procedure calls against a monero node

Usage:
  monero daemon [command]

Available Commands:
  generate-blocks            generate blocks when in regtest mode
  get-alternate-chains       display alternative chains as seen by the node
  get-bans                   all the nodes that have been banned by our node
  get-block                  full block information by either block height or hash
  get-block-count            look up how many blocks are in the longest chain known to the node
  get-block-header           retrieve block(s) header(s) by hash
  get-block-headers-range    retrieve a range of block headers
  get-block-template         generate a block template for mining a new block
  get-coinbase-tx-sum        compute the coinbase amount and the fees amount for n last blocks starting at particular height
  get-connections            information about incoming and outgoing connections.
  get-fee-estimate           estimate fees in atomic units per kB
  get-height                 node's current chain height
  get-info                   general information about the node and the network
  get-last-block-header      header of the last block.
  get-net-stats              networking statistics.
  get-outs                   output details
  get-peer-list              peers lists (white and gray)
  get-public-nodes           all known peers advertising as public nodes
  get-transaction            lookup a transaction, in the pool or not
  get-transaction-pool       information about valid transactions seen by the node but not yet mined into a block, including spent key image info for the txpool
  get-transaction-pool-stats statistics about the transaction pool
  get-version                version of the monero daemon
  hardfork-info              information regarding hard fork voting and readiness.
  mining-status              information about this daemon's mining activity
  on-get-block-hash          find out block's hash by height
  relay-tx                   relay a list of transaction ids
  rpc-access-tracking        statistics about rpc access
  set-bans                   ban another nodes
  start-mining               start mining on the daemon
  stop-mining                stop mining on the daemon
  sync-info                  daemon's chain synchronization info
  zmq                        listen for zmq notifications

Flags:
  -a, --address string             full address of the monero node to reach out to [MONERO_ADDRESS] (default "http://localhost:18081")
  -h, --help                       help for daemon
  -p, --password string            password to supply for rpc auth
      --request-timeout duration   max wait time until considering the request a failure (default 1m0s)
      --shorten-addresses          whether addresses should be shortened when displaying pretty results (default true)
      --tls-ca-cert string         certificate authority to load
      --tls-client-cert string     tls client certificate to use when connecting
      --tls-client-key string      tls client key to use when connecting
  -k, --tls-skip-verify            skip verification of certificate chain and host name
  -u, --username string            name of the user to use during rpc auth
  -v, --verbose                    dump http requests and responses to stderr

Use "monero daemon [command] --help" for more information about a command.

Tor support

Nodes reachable only through the Tor network (hidden services) or proxying traffic through Tor to clearnet is supported despite the lack of a specific flag for specifying the proxy address.

For instance:

$ export HTTP_PROXY="socks5://127.0.0.1:9050" 
$ export MONERO_ADDR=http://rbpgdckle3h3vi4wwwrh75usqtoc5r3alohy7yyx57isynvay63nacyd.onion:18089

$ monero daemon --verbose -a $MONERO_ADDR  get-version --verbose
GET /json_rpc HTTP/1.1
Host: rbpgdckle3h3vi4wwwrh75usqtoc5r3alohy7yyx57isynvay63nacyd.onion:18089
User-Agent: Go-http-client/1.1
Content-Length: 49
Content-Type: application/json
Accept-Encoding: gzip

{"id":"0","jsonrpc":"2.0","method":"get_version"}

HTTP/1.1 200 Ok
Content-Length: 150
Accept-Ranges: bytes
Content-Type: application/json
Last-Modified: Sun, 18 Jul 2021 21:10:57 GMT
Server: Epee-based

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "release": true,
    "status": "OK",
    "untrusted": false,
    "version": 196613
  }
}

Release:        true
Major:          3
Minor:          5

Library

To consume go-monero as a library for your Go project:

$ go get -u -v github.com/cirocosta/go-monero

go-monero exposes two high-level packages: levin and rpc.

The first (levin) is used for interacting with the p2p network via plain TCP (optionally, Tor and I2P can also be used via socks5 proxy - see options).

For instance, to reach out to a node (of a particular address addr) and grab its list of connected peers (information that comes out of the initial handshake):

import (
	"context"
	"fmt"

	"github.com/cirocosta/go-monero/pkg/levin"
)

func ListNodePeers(ctx context.Context, addr string) error {
	// start a client - this will actually establish a TCP `connect()`ion
	// with the other node.
	//
	client, err := levin.NewClient(ctx, addr)
	if err != nil {
		return fmt.Errorf("new client '%s': %w", addr, err)
	}

	// close the connection when done
	//
	defer client.Close()

	// perform the handshake
	//
	pl, err := client.Handshake(ctx)
	if err != nil {
		return fmt.Errorf("handshake: %w", err)
	}

	// list the peers reported back (250 max per monero's implementation)
	//
	for addr := range pl.Peers {
		fmt.Println(addr)
	}

	return nil
}

The second (rpc), is used to communicate with monerod via its HTTP endpoints. Note that not all endpoints/fields are exposed on a given port - if it's being served in a restricted manner, you'll have access to less endpoints than you see in the documentation (https://www.getmonero.org/resources/developer-guides/daemon-rpc.html)

rpc itself is subdivided in two other packages: wallet and daemon, exposing monero-wallet-rpc and monerod RPCs accordingly.

For instance, to get the the height of the main chain:

package daemon_test

import (
	"context"
	"fmt"

	"github.com/cirocosta/go-monero/pkg/rpc"
	"github.com/cirocosta/go-monero/pkg/rpc/daemon"
)

func ExampleGetHeight() {
	ctx := context.Background()
	addr := "http://localhost:18081"

	// instantiate a generic RPC client
	//
	client, err := rpc.NewClient(addr)
	if err != nil {
		panic(fmt.Errorf("new client for '%s': %w", addr, err))
	}

	// instantiate a daemon-specific client and call the `get_height`
	// remote procedure.
	//
	height, err := daemon.NewClient(client).GetHeight(ctx)
	if err != nil {
		panic(fmt.Errorf("get height: %w", err))
	}

	fmt.Printf("height=%d hash=%s\n", height.Height, height.Hash)
}

License

See LICENSE.

Thanks

Big thanks to the Monero community and other projects around cryptonote:

• #monero-dev (https://matrix.to/#/#freenode_#monero-dev:matrix.org)
• https://reddit.com/r/Monero
• https://github.com/cdiv1e12/py-levin
• https://github.com/cryptonotefoundation/cryptonote
• https://github.com/LeTurt/turtlegod

Donate

891B5keCnwXN14hA9FoAzGFtaWmcuLjTDT5aRTp65juBLkbNpEhLNfgcBn6aWdGuBqBnSThqMPsGRjWVQadCrhoAT6CnSL3