cl-kuthirgal / cl-monero-tools

Common Lisp toolbox to work with the Monero cryptocurrency

Monero tools

This is a Common Lisp toolbox to work with the Monero cryptocurrency.

There are several systems:

• monero-utils: Basic utility functions (integer/bytes conversion, base58 encoding, etc…).
• monero-tools: Tools that can be used offline (crypto functions, address generation, etc…).
• monero-rpc: HTTP RPCs to communicate with a running monerod or monero-wallet-rpc daemon.
• monero-binary-rpc: Binary RPCs to communicate with a running monerod daemon.
• monero-zmq-rpc: ZeroMQ RPCs to communicate with a running monerod daemon.
• monero-custom-rpc: Some custom RPCs to communicate with a running monerod daemon.
• monero-p2p: Tools to communicate with remote Monero nodes.

This library is in alpha quality stage, so the API might change.

Installation

To load the monero-tools library, put it in a directory where your Common Lisp implementation can see it, and use the usual:

(asdf:load-system "monero-tools")

or

(ql:quickload "monero-tools")

monero-utils

Dependencies

monero-utils requires the following libraries:

• alexandria
• babel
• cffi
• cl-json
• ironclad

API

After loading the monero-utils system, the following functions and variables are in the monero-utils package.

• +base58-checksum-size+
• base58-decode
• base58-decoded-length
• base58-encode
• base58-encoded-length
• bytes->hex-string
• bytes->integer
• bytes->string
• bytes->utf-8-string
• c-array->lisp-array
• decode-json-from-string
• encode-json-to-string
• format-float
• geta
• get-unix-time
• hex-string->bytes
• integer->bytes
• join-bytes
• json-name->lisp-name
• lisp-array->c-array
• lisp-name->json-name
• octet-vector
• read-float
• split-bytes
• string->bytes
• utf-8-string->bytes

monero-tools

Dependencies

monero-tools requires the following libraries:

• alexandria
• babel
• bordeaux-threads
• cffi
• cl-json
• cl-octet-streams
• cl-ppcre
• cl-qrencode
• dexador
• ieee-floats
• iterate
• ironclad
• monero-utils
• png-read
• split-sequence

Optional:

• a running randomx-service daemon (to compute RandomX hashes)
• the unbound C library (to resolve OpenAlias names)
• the zbar C library (to read QR codes)

If the optional C libraries are not available, the system should load successfully but some functions will not work.

API

After loading the monero-tools system, the following functions and variables are in the monero-tools package.

Blockchain

• acceptable-hash-p
• compute-block-hash
• compute-block-hash-from-data
• compute-miner-transaction-hash
• compute-miner-transaction-hash-from-data
• compute-transaction-hash
• compute-transaction-hash-from-data
• compute-transaction-tree-hash

Cryptography

• *randomx-service-host*
• *randomx-service-port*
• *slow-hash-height*
• *slow-hash-seed*
• *slow-hash-variant*
• chacha8
• chacha20
• compute-key-image
• compute-multisig-blinded-secret
• compute-multisig-keys-m/n
• compute-multisig-keys-n/n
• compute-multisig-public-keys
• compute-multisig-public-spend-key
• compute-multisig-secret-spend-key
• compute-multisig-secret-view-key
• compute-subaddress-indexes-table
• derive-key
• derive-output-public-key
• derive-output-secret-key
• derive-output-secret-subkey
• derive-public-spend-subkey
• derive-secret-spend-subkey
• derive-subkey-secret
• fast-hash
• generate-chacha-key
• generate-keys
• generate-secret-key
• generate-ring-signature
• generate-signature
• output-public-key->public-spend-subkey
• public-spend-subkey->public-view-subkey
• randomx-seed-height
• randomx-service-hash
• randomx-service-hash-batch
• randomx-service-info
• randomx-service-reseed
• recover-keys
• secret-key->public-key
• secret-spend-key->secret-view-key
• slow-hash
• tree-hash
• valid-ring-signature-p
• valid-signature-p

Mining

• miner
• mining-profitability
• modify-block-template

Mnemonic seed

• available-mnemonic-seed-languages
• decrypt-mnemonic-seed
• encrypt-mnemonic-seed
• mnemonic-seed->secret-key
• secret-key->mnemonic-seed

OpenAlias

• *dns-server*
• *dnssec-trust-anchors*
• get-openalias-info

Serialization

• deserialize-block
• deserialize-block-header
• deserialize-from-binary-storage
• deserialize-transaction
• deserialize-transaction-prefix
• serialize-block
• serialize-block-header
• serialize-to-binary-storage
• serialize-transaction
• serialize-transaction-prefix

Wallet

• +monero-unit+
• bruteforce-wallet-keys
• decode-address
• decode-multisig-extra-info
• decode-multisig-info
• decode-multisig-seed
• decode-qr-code
• decode-uri
• decrypt-amount
• decrypt-payment-id
• decrypt-wallet-keys
• encrypt-payment-id
• get-wallet-keys
• make-integrated-address
• make-multisig-extra-info
• make-multisig-info
• make-multisig-seed
• make-qr-code
• make-uri
• output-destination-address
• output-for-address-p
• prove-inbound-transaction
• prove-outbound-transaction
• prove-payment
• public-keys->address
• public-keys->subaddress
• received-amount
• secret-spend-key->address
• secret-spend-key->subaddress
• sign-file
• sign-message
• spent-key-images
• valid-address-p
• valid-file-signature-p
• valid-inbound-transaction-proof-p
• valid-message-signature-p
• valid-outbound-transaction-proof-p
• valid-payment-proof-p

Tests

The tests require the fiveam library.

(asdf:test-system "monero-tools")

monero-rpc

Dependencies

monero-rpc requires the following libraries:

• cl-base64
• cl-json
• dexador
• ironclad
• monero-tools
• monero-utils
• split-sequence

API

After loading the monero-rpc system, the following functions and variables are available in the monero-rpc package.

• *rpc-client-secret-key*
• *rpc-host*
• *rpc-password*
• *rpc-port*
• *rpc-user*
• compute-digest-authentication-response
• defjsonrpc
• defrawrpc
• defrpc
• generate-rpc-payment-signature
• json-rpc
• parse-digest-authentication-challenge
• rpc

Calling monerod

After loading the monero-rpc system, the following functions and variables are available in the monero-daemon-rpc package.

HTTP JSON RPCs

The following functions are thin wrappers for the HTTP JSON RPCs of monerod. They use alists instead of JSON objects, where a key named some_key in a JSON object becomes :some-key in the alist. The specifications of these RPCs can be found in https://getmonero.org/resources/developer-guides/daemon-rpc.html.

• banned
• flush-cache
• flush-txpool
• generateblocks
• get-alternate-chain
• get-bans
• get-block
• get-block-count
• get-block-hash
• get-block-header-by-hash
• get-block-header-by-height
• get-block-headers-range
• get-block-template
• get-coinbase-tx-sum
• get-connections
• get-fee-estimate
• get-info
• get-last-block-header
• get-output-distribution
• get-output-histogram
• get-txpool-backlog
• get-version
• hard-fork-info
• prune-blockchain
• relay-tx
• rpc-access-account
• rpc-access-data
• rpc-access-info
• rpc-access-pay
• rpc-access-submit-nonce
• rpc-access-tracking
• set-bans
• submit-block
• sync-info

Other HTTP RPCs

The following functions are thin wrappers for the HTTP RPCs of monerod. They use alists instead of JSON objects, where a key named some_key in a JSON object becomes :some-key in the alist. The specifications of these RPCs can be found in https://getmonero.org/resources/developer-guides/daemon-rpc.html.

• get-alt-blocks-hashes
• get-height
• get-limit
• get-net-stats
• get-outs
• get-peer-list
• get-public-nodes
• get-transaction-pool
• get-transaction-pool-hashes
• get-transaction-pool-stats
• get-transactions
• in-peers
• is-key-image-spent
• mining-status
• out-peers
• pop-blocks
• save-bc
• send-raw-transaction
• set-bootstrap-daemon
• set-limit
• set-log-categories
• set-log-hashrate
• set-log-level
• start-mining
• start-save-graph
• stop-daemon
• stop-mining
• stop-save-graph
• update

Calling monero-wallet-rpc

After loading the monero-rpc system, the following functions and variables are available in the monero-wallet-rpc package.

The following functions are thin wrappers for the HTTP JSON RPCs of monero-wallet-rpc. They use alists instead of JSON objects, where a key named some_key in a JSON object becomes :some-key in the alist. The specifications of these RPCs can be found in https://getmonero.org/resources/developer-guides/wallet-rpc.html.

• add-address-book
• auto-refresh
• change-wallet-password
• check-reserve-proof
• check-spend-proof
• check-tx-key
• check-tx-proof
• close-wallet
• create-account
• create-address
• create-wallet
• delete-address-book
• describe-transfer
• exchange-multisig-keys
• export-key-images
• export-multisig-info
• export-outputs
• finalize-multisig
• generate-from-keys
• get-account-tags
• get-accounts
• get-address
• get-address-book
• get-address-index
• get-attribute
• get-balance
• get-bulk-payments
• get-height
• get-languages
• get-payments
• get-reserve-proof
• get-spend-proof
• get-transfer-by-txid
• get-transfers
• get-tx-key
• get-tx-notes
• get-tx-proof
• get-version
• import-key-images
• import-multisig-info
• import-outputs
• incoming_transfers
• is-multisig
• label-account
• label-address
• make-integrated-address
• make-multisig
• make-uri
• open-wallet
• parse-uri
• prepare-multisig
• query-key
• refresh
• relay-tx
• rescan-blockchain
• rescan-spent
• restore-deterministic-wallet
• set-account-tag-description
• set-attribute
• set-daemon
• set-log-categories
• set-log-level
• set-tx-notes
• sign
• sign-multisig
• sign-transfer
• split-integrated-address
• start-mining
• stop-mining
• stop-wallet
• store
• submit-multisig
• submit-transfer
• sweep-all
• sweep-dust
• sweep-single
• tag-accounts
• transfer
• transfer-split
• untag-accounts
• validate-address
• verify

monero-binary-rpc

Dependencies

monero-binary-rpc requires the following libraries:

• dexador
• iterate
• monero-rpc
• monero-tools
• monero-utils

API

After loading the monero-binary-rpc system, the following functions and variables are available in the monero-binary-rpc package.

• binary-rpc
• defbinrpc
• get-blocks.bin
• get-blocks-by-height.bin
• get-hashes.bin
• get-o-indexes.bin
• get-outs.bin
• get-random-outs.bin
• get-random-rctouts.bin
• get-transaction-pool-hashes.bin

monero-zmq-rpc

Dependencies

monero-zmq-rpc requires the following libraries:

• monero-rpc
• monero-utils
• pzmq

API

After loading the monero-zmq-rpc system, the following functions and variables are available in the monero-zmq-rpc package.

• get-block
• get-blocks
• get-info
• get-transactions
• zmq-json-rpc

monero-custom-rpc

Dependencies

monero-custom-rpc requires the following libraries:

• bordeaux-threads
• iterate
• monero-binary-rpc
• monero-rpc
• monero-tools
• monero-utils

API

After loading the monero-custom-rpc system, the following functions and variables are available in the monero-custom-rpc package.

• mine-block
• transaction-history

monero-p2p

Dependencies

monero-p2p requires the following libraries:

• alexandria
• ironclad
• iterate
• monero-tools
• monero-utils
• usocket

API

After loading the monero-p2p system, the following functions and variables are available in the monero-p2p package.

• *network-id*
• *p2p-port*
• *peer-id*
• close-connection
• open-connection