Cardano Transaction Submission API
A simple HTTP API which accepts a CBOR encoded Cardano transaction as a payload body and submits it to a Cardano full node using the Ouroboros LocalTxSubmission Node-to-Client (NtC) protocol.
The recommended method of using this application is via the published container images, coupled with Blink Labs container images for the Cardano Node.
docker run -p 8090:8090 ghcr.io/blinklabs-io/tx-submit-api
Binaries can be executed directly and are available from Releases.
./tx-submit-api
Configuration can be done using either a config.yaml
file or setting
environment variables. Our recommendation is environment variables to adhere
to the 12-factor application philisophy.
Configuration via environment variables can be broken into two sets of variables. The first set controls the behavior of the application, while the second set controls the connection to the Cardano node instance.
Application configuration:
API_LISTEN_ADDRESS
- Address to bind for API calls, all addresses if empty (default: empty)API_LISTEN_PORT
- Port to bind for API calls (default: 8090)DEBUG_ADDRESS
- Address to bind for pprof debugging (default: localhost)DEBUG_PORT
- Port to bind for pprof debugging, disabled if 0 (default: 0)LOGGING_HEALTHCHECKS
- Log requests to/healthcheck
endpoint (default: false)LOGGING_LEVEL
- Logging level for log output (default: info)METRICS_LISTEN_ADDRESS
- Address to bind for Prometheus format metrics, all addresses if empty (default: empty)METRICS_LISTEN_PORT
- Port to bind for metrics (default: 8081)
Connection to the Cardano node can be performed using specific named network shortcuts for known network magic configurations. Supported named networks are:
- mainnet
- preprod
- preview
- testnet
You can set the network to an empty value and provide your own network magic to connect to unlisted networks.
TCP connection to a Cardano node without using an intermediary like SOCAT is possible using the node address and port. It is up to you to expose the node's NtC communication socket over TCP. TCP connections are preferred over socket within the application.
Cardano node configuration:
CARDANO_NETWORK
- Use a named Cardano network (default: mainnet)CARDANO_NODE_NETWORK_MAGIC
- Cardano network magic (default: automatically determined from named network)CARDANO_NODE_SKIP_CHECK
- Skip the connection test to Cardano Node on start (default: false)CARDANO_NODE_SOCKET_PATH
- Socket path to Cardano node NtC via UNIX socket (default: /node-ipc/node.socket)CARDANO_NODE_SOCKET_TCP_HOST
- Address to Cardano node NtC via TCP (default: unset)CARDANO_NODE_SOCKET_TCP_PORT
- Port to Cardano node NtC via TCP (default: unset)CARDANO_NODE_SOCKET_TIMEOUT
- Sets a timeout in seconds for waiting on requests to the Cardano node (default: 30)
You can connect to either a cardano-node running locally on the host or a
container running either inputoutput/cardano-node
or
blinklabs-io/cardano-node
by mapping in the correct paths and setting the
environment variables or configuration options to match.
Use Docker to run both cardano-node and tx-submit-api with Docker volumes for blockchain storage and node-ipc.
# Start node
docker run --detach \
--name cardano-node \
-v node-data:/opt/cardano/data \
-v node-ipc:/opt/cardano/ipc \
-p 3001:3001 \
ghcr.io/blinklabs-io/cardano-node run
# Start submit-api
docker run --detach \
--name tx-submit-api
-v node-ipc:/node-ipc \
-p 8090:8090 \
ghcr.io/blinklabs-io/tx-submit-api
Use the local path when mapping the node-ipc volume into the container to use a local cardano-node.
# Start submit-api
docker run --detach \
--name tx-submit-api \
-v /opt/cardano/ipc:/node-ipc \
-p 8090:8090 \
ghcr.io/blinklabs-io/tx-submit-api
This implementation shares an API spec with IOHK's Haskell implementation. The same instructions apply. Follow the steps to build and submit a transaction
# Submit a binary tx.signed.cbor signed CBOR encoded transaction binary file
curl -X POST \
--header "Content-Type: application/cbor" \
--data-binary @tx.signed.cbor \
http://localhost:8090/api/submit/tx
There is a Makefile to provide some simple helpers.
Run from checkout:
go run .
Create a binary:
make
Create a docker image:
make image