From 403405ab47f0d9a6ecc5c0c74078ac9e63e38788 Mon Sep 17 00:00:00 2001 From: Dave Miner Date: Sun, 11 Jan 2026 22:26:40 -0500 Subject: [PATCH 1/4] ci compatibility with M1 chips --- .github/workflows/ci.yml | 114 ++++++++++++----- README.md | 257 ++++++++++++++++++++------------------- 2 files changed, 221 insertions(+), 150 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98e13dd..9f69d0d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -54,17 +54,75 @@ jobs: - name: Set up Node.js uses: actions/setup-node@v4 with: - node-version: '20.8.0' + node-version: "20.8.0" - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y netcat-openbsd socat - - # Download and install libssl1.1 manually - wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb - sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb || true - sudo apt-get install -f -y + + # Detect architecture + ARCH=$(dpkg --print-architecture) + echo "Detected architecture: $ARCH" + + if [ "$ARCH" = "amd64" ]; then + # Download and install libssl1.1 manually for x86_64 + wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb + sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb || true + sudo apt-get install -f -y + elif [ "$ARCH" = "arm64" ]; then + # For ARM64 (e.g., running with act on Apple Silicon), install x86_64 compatibility + echo "Installing x86_64 compatibility libraries for ARM64" + + # Add amd64 architecture support + sudo dpkg --add-architecture amd64 + + # Handle traditional sources.list format + if [ -f /etc/apt/sources.list ]; then + sudo sed -i 's/^deb /deb [arch=arm64] /' /etc/apt/sources.list + sudo sed -i 's/^deb-src /deb-src [arch=arm64] /' /etc/apt/sources.list + fi + + # Handle DEB822 format (.sources files) used by Ubuntu 24.04+ + # These files use "Architectures:" field instead of inline [arch=] + for f in /etc/apt/sources.list.d/*.sources; do + if [ -f "$f" ]; then + echo "Restricting $f to arm64 architecture" + # Add "Architectures: arm64" after the "Types:" line if not already present + if ! grep -q "^Architectures:" "$f"; then + sudo sed -i '/^Types:/a Architectures: arm64' "$f" + fi + fi + done + + # Also fix traditional .list files that might reference ports.ubuntu.com + for f in /etc/apt/sources.list.d/*.list; do + if [ -f "$f" ] && grep -q "ports.ubuntu.com" "$f"; then + sudo sed -i 's/^deb /deb [arch=arm64] /' "$f" + sudo sed -i 's/^deb-src /deb-src [arch=arm64] /' "$f" + fi + done + + # Add amd64 package sources from archive.ubuntu.com (has amd64 packages) + # Use noble (24.04) to match the container's Ubuntu version + echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ noble main restricted universe multiverse" | sudo tee /etc/apt/sources.list.d/amd64.list + echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ noble-updates main restricted universe multiverse" | sudo tee -a /etc/apt/sources.list.d/amd64.list + + sudo apt-get update + + # Install x86_64 libraries needed to run x86_64 binaries + sudo apt-get install -y libc6:amd64 libstdc++6:amd64 zlib1g:amd64 libgmp10:amd64 + + # Download and install libssl1.1 for amd64 (from focal/20.04 since noble doesn't have it) + wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb + sudo dpkg --force-architecture -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb || true + sudo apt-get install -f -y + + # Also install libssl1.1 for arm64 (needed by Erlang's crypto library) + wget http://ports.ubuntu.com/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_arm64.deb + sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_arm64.deb || true + sudo apt-get install -f -y + fi - name: Cache Cardano CLI and Address uses: actions/cache@v3 @@ -75,9 +133,9 @@ jobs: /usr/local/bin/cardano-cli /usr/local/bin/cardano-node /usr/local/bin/cardano-address - key: ${{ runner.os }}-cardano-tools-10.2.1 + key: ${{ runner.os }}-${{ runner.arch }}-cardano-tools-10.2.1 restore-keys: | - ${{ runner.os }}-cardano-tools- + ${{ runner.os }}-${{ runner.arch }}-cardano-tools- - name: Install Cardano Tools if: steps.cardano-cache.outputs.cache-hit != 'true' @@ -85,56 +143,56 @@ jobs: # Install dependencies sudo apt-get update sudo apt-get install -y build-essential pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev libsodium-dev zlib1g-dev make g++ jq libncursesw6 libtinfo6 - + # Create cache directory mkdir -p ~/.cache/cardano-cli - + # Download and install cardano-cli wget https://github.com/IntersectMBO/cardano-node/releases/download/10.2.1/cardano-node-10.2.1-linux.tar.gz -O ~/.cache/cardano-cli/cardano-node_10.2.1_linux.tar.gz - + # Extract with verbose output to see the structure tar -tvf ~/.cache/cardano-cli/cardano-node_10.2.1_linux.tar.gz - + # Extract the tar file tar -xzf ~/.cache/cardano-cli/cardano-node_10.2.1_linux.tar.gz -C ~/.cache/cardano-cli - + # Download and install cardano-address wget https://github.com/IntersectMBO/cardano-addresses/releases/download/4.0.0/cardano-address-4.0.0-linux.tar.gz -O ~/.cache/cardano-cli/cardano-addresses.tar.gz tar -xzf ~/.cache/cardano-cli/cardano-addresses.tar.gz -C ~/.cache/cardano-cli - + # List the contents to verify echo "Contents of cache directory:" ls -la ~/.cache/cardano-cli - + # Find the executables CARDANO_CLI_PATH=$(find ~/.cache/cardano-cli -name "cardano-cli" -type f | head -n 1) CARDANO_NODE_PATH=$(find ~/.cache/cardano-cli -name "cardano-node" -type f | head -n 1) CARDANO_ADDR_PATH=$(find ~/.cache/cardano-cli -name "cardano-address" -type f | head -n 1) - + if [ -z "$CARDANO_CLI_PATH" ] || [ -z "$CARDANO_NODE_PATH" ] || [ -z "$CARDANO_ADDR_PATH" ]; then echo "Could not find one or more required executables" find ~/.cache/cardano-cli -type f exit 1 fi - + echo "Found cardano-cli at: $CARDANO_CLI_PATH" echo "Found cardano-node at: $CARDANO_NODE_PATH" echo "Found cardano-address at: $CARDANO_ADDR_PATH" - + # Install to system sudo cp "$CARDANO_CLI_PATH" /usr/local/bin/cardano-cli sudo cp "$CARDANO_NODE_PATH" /usr/local/bin/cardano-node sudo cp "$CARDANO_ADDR_PATH" /usr/local/bin/cardano-address - + # Make them executable sudo chmod +x /usr/local/bin/cardano-cli sudo chmod +x /usr/local/bin/cardano-node sudo chmod +x /usr/local/bin/cardano-address - + # Verify installation cardano-cli --version cardano-address --version - + # Add to PATH for the current session echo "$(dirname "$CARDANO_CLI_PATH")" >> $GITHUB_PATH @@ -163,19 +221,19 @@ jobs: run: | # Kill any existing Yaci DevKit processes pkill -f yaci-devkit || true - + # Start Yaci DevKit with verbose output and use pre-downloaded components # Defaults to emitting blocks in conway era format, which is the only # era currently supported by Xander. nohup yaci-devkit up > yaci-devkit.log 2>&1 & - + # Save the process ID echo $! > yaci-devkit.pid - + # Display the log file for debugging tail -f yaci-devkit.log & TAIL_PID=$! - + # Wait for the log to show that Yaci DevKit is starting for i in {1..10}; do if grep -q "Starting Yaci DevKit" yaci-devkit.log; then @@ -185,7 +243,7 @@ jobs: echo "Waiting for Yaci DevKit to start in logs..." sleep 2 done - + # Kill the tail process kill $TAIL_PID || true @@ -197,7 +255,7 @@ jobs: cat yaci-devkit.log exit 1 fi - + # Wait for the Cardano node socket to be available for i in {1..60}; do # Extract the socket path from the Yaci DevKit logs @@ -217,7 +275,7 @@ jobs: echo "Waiting for Yaci DevKit Cardano node socket to start... (attempt $i/60)" sleep 5 done - + echo "Yaci DevKit failed to start. Log contents:" cat yaci-devkit.log exit 1 diff --git a/README.md b/README.md index 1a2abc1..f7108d3 100644 --- a/README.md +++ b/README.md @@ -47,48 +47,48 @@ $ iex For a more detailed description of different ways to use this library, read the following sections: -
Running Queries via Docker - ## Running Queries via Docker +## Running Queries via Docker - In order to run queries via Docker, you need to build the image first: +In order to run queries via Docker, you need to build the image first: - ``` - docker build -t xander . - ``` +``` +docker build -t xander . +``` - With the image built, you can now connect to either a local Cardano node via a UNIX socket or to a node at Demeter.run. +With the image built, you can now connect to either a local Cardano node via a UNIX socket or to a node at Demeter.run. - #### 1. Connecting via a local UNIX socket +#### 1. Connecting via a local UNIX socket - This assumes you have access to a fully synced Cardano node. +This assumes you have access to a fully synced Cardano node. - 🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. +🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. - Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to - the container's default socket path (`/tmp/cardano-node.socket`): +Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to +the container's default socket path (`/tmp/cardano-node.socket`): + +``` +docker run --rm \ + -v /your/local/node.socket:/tmp/cardano-node.socket \ + xander elixir run_queries.exs +``` - ``` - docker run --rm \ - -v /your/local/node.socket:/tmp/cardano-node.socket \ - xander elixir run_queries.exs - ``` +#### 2. Connecting to a node at Demeter.run - #### 2. Connecting to a node at Demeter.run +The demo application can connect to a Cardano node at [Demeter.run](https://demeter.run/) 🪄 - The demo application can connect to a Cardano node at [Demeter.run](https://demeter.run/) 🪄 +First, create a Node on Demeter and grab the Node's URL. - First, create a Node on Demeter and grab the Node's URL. +Then, run the Docker image with the `DEMETER_URL` environment variable set to your Node's URL: - Then, run the Docker image with the `DEMETER_URL` environment variable set to your Node's URL: +```bash +docker run --rm \ + -e DEMETER_URL=https://your-node-at.demeter.run \ + xander elixir run_queries_with_demeter.exs +``` - ```bash - docker run --rm \ - -e DEMETER_URL=https://your-node-at.demeter.run \ - xander elixir run_queries_with_demeter.exs - ```
@@ -96,167 +96,180 @@ For a more detailed description of different ways to use this library, read the ## Running Queries with native Elixir install - For those with Elixir already installed, simply run the commands below: +For those with Elixir already installed, simply run the commands below: - ``` - # Must set a local unix socket - elixir run_queries.exs +``` +# Must set a local unix socket +elixir run_queries.exs + +# Must set a Demeter URL +elixir run_queries_with_demeter.exs +``` - # Must set a Demeter URL - elixir run_queries_with_demeter.exs - ``` +More information on connection below: - More information on connection below: +#### a) Connecting via local UNIX socket - #### a) Connecting via local UNIX socket +Run the following command using your own Cardano node's socket path: - Run the following command using your own Cardano node's socket path: +```bash +CARDANO_NODE_PATH=/your/cardano/node.socket elixir run_queries.exs +``` - ```bash - CARDANO_NODE_PATH=/your/cardano/node.socket elixir run_queries.exs - ``` +##### Setting up Unix socket mapping (optional when no direct access to Cardano node) - ##### Setting up Unix socket mapping (optional when no direct access to Cardano node) +This is useful if you want to run the application on a server different from your Cardano node. - This is useful if you want to run the application on a server different from your Cardano node. +🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. - 🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. +1. Run socat on the remote server with the following command: - 1. Run socat on the remote server with the following command: +```bash +socat TCP-LISTEN:3002,reuseaddr,fork UNIX-CONNECT:/home/cardano_node/socket/node.socket +``` - ```bash - socat TCP-LISTEN:3002,reuseaddr,fork UNIX-CONNECT:/home/cardano_node/socket/node.socket - ``` +2. Run socat on the local machine with the following command: - 2. Run socat on the local machine with the following command: +```bash +socat UNIX-LISTEN:/tmp/cardano_node.socket,reuseaddr,fork TCP:localhost:3002 +``` - ```bash - socat UNIX-LISTEN:/tmp/cardano_node.socket,reuseaddr,fork TCP:localhost:3002 - ``` +3. Start an SSH tunnel from the local machine to the remote server with the following command: - 3. Start an SSH tunnel from the local machine to the remote server with the following command: +```bash +ssh -N -L 3002:localhost:3002 user@remote-server-ip +``` - ```bash - ssh -N -L 3002:localhost:3002 user@remote-server-ip - ``` +4. Run the example script: - 4. Run the example script: +```bash +CARDANO_NODE_PATH=/tmp/cardano_node.socket elixir run.exs +``` - ```bash - CARDANO_NODE_PATH=/tmp/cardano_node.socket elixir run.exs - ``` +#### b) Connecting via Demeter.run - #### b) Connecting via Demeter.run +To connect to a node at Demeter.run, set `DEMETER_URL` to your Node Demeter URL. - To connect to a node at Demeter.run, set `DEMETER_URL` to your Node Demeter URL. +```bash +DEMETER_URL=https://your-node-at.demeter.run elixir run_queries_with_demeter.exs +``` - ```bash - DEMETER_URL=https://your-node-at.demeter.run elixir run_queries_with_demeter.exs - ```
Submitting Transactions - ## Submitting Transactions +## Submitting Transactions + +⚠️ This project does not provide off-chain transaction functionality such as building and signing of transactions. + +In order to submit transactions via Xander, you can either run the `submit_tx.exs` script directly or use Docker. - ⚠️ This project does not provide off-chain transaction functionality such as building and signing of transactions. +## Running the script - In order to submit transactions via Xander, you can either run the `submit_tx.exs` script directly or use Docker. +This assumes you have Elixir installed. In order to run the script directly, follow the steps below: +1. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) +2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node. +3. Ensure the `Config.default_config!` function call matches the network being used: - ## Running the script + - `Config.default_config!(socket_path)` defaults to Mainnet + - `Config.default_config!(socket_path, :preview)` for Preview network - This assumes you have Elixir installed. In order to run the script directly, follow the steps below: +4. Run `elixir submit_tx.exs ` providing the CBOR hex as its single argument. - 1. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) - 2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node. - 3. Ensure the `Config.default_config!` function call matches the network being used: - - `Config.default_config!(socket_path)` defaults to Mainnet - - `Config.default_config!(socket_path, :preview)` for Preview network - 4. Run `elixir submit_tx.exs ` providing the CBOR hex as its single argument. +A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. - A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. +## Using Docker - ## Using Docker +This assumes you have Docker installed. No Elixir installation is required. - This assumes you have Docker installed. No Elixir installation is required. +1. First, build the image: + +``` +docker build -t xander . +``` - 1. First, build the image: +2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used: - ``` - docker build -t xander . - ``` + - `Config.default_config!(socket_path)` defaults to Mainnet + - `Config.default_config!(socket_path, :preview)` for Preview network - 2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used: - - `Config.default_config!(socket_path)` defaults to Mainnet - - `Config.default_config!(socket_path, :preview)` for Preview network +3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) - 3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) +Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to +the container's default socket path (`/tmp/cardano-node-preview.socket`): - Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to - the container's default socket path (`/tmp/cardano-node-preview.socket`): +``` +docker run --rm \ +-v /your/local/preview-node.socket:/tmp/cardano-node-preview.socket \ +xander elixir submit_tx.exs +``` - ``` - docker run --rm \ - -v /your/local/preview-node.socket:/tmp/cardano-node-preview.socket \ - xander elixir submit_tx.exs - ``` +A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. - A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer.
Running ChainSync - ## Chain Sync +## Chain Sync + +In order to sync blocks from a Cardano node, you can either run the `run_chain_sync.exs` script directly or use Docker. + +## Running the script - In order to sync blocks from a Cardano node, you can either run the `run_chain_sync.exs` script directly or use Docker. +This assumes you have Elixir installed. In order to run the script directly, follow the steps below: - ## Running the script +1. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced **mainnet** Cardano node. +2. Run `elixir run_chain_sync.exs` - This assumes you have Elixir installed. In order to run the script directly, follow the steps below: +Using default settings, this will start syncing from the start of the Conway era. For each block, the block number (height) and block size (in bytes) will be displayed. - 1. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced **mainnet** Cardano node. - 2. Run `elixir run_chain_sync.exs` +If you wish to connect with one of the testnets, see comments on the `FollowDaChain.start_link/1` function for more information on exact points in the chain to start syncing from. - Using default settings, this will start syncing from the start of the Conway era. For each block, the block number (height) and block size (in bytes) will be displayed. +## Using Docker - If you wish to connect with one of the testnets, see comments on the `FollowDaChain.start_link/1` function for more information on exact points in the chain to start syncing from. +This assumes you have Docker installed. No Elixir installation is required. - ## Using Docker +1. First, build the image: - This assumes you have Docker installed. No Elixir installation is required. +``` +docker build -t xander . +``` - 1. First, build the image: +``` +docker run --rm -v /your/local/cardano-node.socket:/tmp/cardano-node.socket xander elixir run_chain_sync.exs +``` - ``` - docker build -t xander . - ``` +## Using Demeter.run - ``` - docker run --rm -v /your/local/cardano-node.socket:/tmp/cardano-node.socket xander elixir run_chain_sync.exs - ``` +Populate the environment variable `DEMETER_URL` with the URL of a node at Demeter.run and run the `run_chain_sync_with_demeter.exs` script. - ## Using Demeter.run - - Populate the environment variable `DEMETER_URL` with the URL of a node at Demeter.run and run the `run_chain_sync_with_demeter.exs` script. +``` +DEMETER_URL=https://your-node-at.demeter.run elixir run_chain_sync_with_demeter.exs +``` - ``` - DEMETER_URL=https://your-node-at.demeter.run elixir run_chain_sync_with_demeter.exs - ``` +or use Docker: - or use Docker: +``` +docker run --rm -e DEMETER_URL=https://your-node-at.demeter.run xander elixir run_chain_sync_with_demeter.exs +``` - ``` - docker run --rm -e DEMETER_URL=https://your-node-at.demeter.run xander elixir run_chain_sync_with_demeter.exs - ```
## Testing -The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act) like so: +The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act). + +For x86_64 (Intel/AMD) chips: ``` act -j integration_test -``` \ No newline at end of file +``` + +For Apple Silicon (M1/M2/M3) chips: + +``` +act -j integration_test --container-architecture linux/arm64 +``` From cc2ba05efcefed880700564602750e45afe850c1 Mon Sep 17 00:00:00 2001 From: Dave Miner Date: Mon, 12 Jan 2026 00:29:43 -0500 Subject: [PATCH 2/4] simpler readme changes for running act integration tests on apple silicon --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f7108d3..2bbe214 100644 --- a/README.md +++ b/README.md @@ -173,8 +173,9 @@ This assumes you have Elixir installed. In order to run the script directly, fol 2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node. 3. Ensure the `Config.default_config!` function call matches the network being used: - - `Config.default_config!(socket_path)` defaults to Mainnet - - `Config.default_config!(socket_path, :preview)` for Preview network + + - `Config.default_config!(socket_path)` defaults to Mainnet + - `Config.default_config!(socket_path, :preview)` for Preview network 4. Run `elixir submit_tx.exs ` providing the CBOR hex as its single argument. @@ -192,8 +193,9 @@ docker build -t xander . 2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used: - - `Config.default_config!(socket_path)` defaults to Mainnet - - `Config.default_config!(socket_path, :preview)` for Preview network + + - `Config.default_config!(socket_path)` defaults to Mainnet + - `Config.default_config!(socket_path, :preview)` for Preview network 3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) From d315188d380b9520df95e0b5430c7a6c429b243f Mon Sep 17 00:00:00 2001 From: Dave Miner Date: Mon, 12 Jan 2026 00:30:33 -0500 Subject: [PATCH 3/4] revert readme changes --- README.md | 253 +++++++++++++++++++++++++----------------------------- 1 file changed, 119 insertions(+), 134 deletions(-) diff --git a/README.md b/README.md index 2bbe214..1a2abc1 100644 --- a/README.md +++ b/README.md @@ -47,48 +47,48 @@ $ iex For a more detailed description of different ways to use this library, read the following sections: +
Running Queries via Docker -## Running Queries via Docker + ## Running Queries via Docker -In order to run queries via Docker, you need to build the image first: + In order to run queries via Docker, you need to build the image first: -``` -docker build -t xander . -``` + ``` + docker build -t xander . + ``` -With the image built, you can now connect to either a local Cardano node via a UNIX socket or to a node at Demeter.run. + With the image built, you can now connect to either a local Cardano node via a UNIX socket or to a node at Demeter.run. -#### 1. Connecting via a local UNIX socket + #### 1. Connecting via a local UNIX socket -This assumes you have access to a fully synced Cardano node. + This assumes you have access to a fully synced Cardano node. -🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. + 🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. -Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to -the container's default socket path (`/tmp/cardano-node.socket`): + Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to + the container's default socket path (`/tmp/cardano-node.socket`): -``` -docker run --rm \ - -v /your/local/node.socket:/tmp/cardano-node.socket \ - xander elixir run_queries.exs -``` + ``` + docker run --rm \ + -v /your/local/node.socket:/tmp/cardano-node.socket \ + xander elixir run_queries.exs + ``` -#### 2. Connecting to a node at Demeter.run + #### 2. Connecting to a node at Demeter.run -The demo application can connect to a Cardano node at [Demeter.run](https://demeter.run/) 🪄 + The demo application can connect to a Cardano node at [Demeter.run](https://demeter.run/) 🪄 -First, create a Node on Demeter and grab the Node's URL. + First, create a Node on Demeter and grab the Node's URL. -Then, run the Docker image with the `DEMETER_URL` environment variable set to your Node's URL: - -```bash -docker run --rm \ - -e DEMETER_URL=https://your-node-at.demeter.run \ - xander elixir run_queries_with_demeter.exs -``` + Then, run the Docker image with the `DEMETER_URL` environment variable set to your Node's URL: + ```bash + docker run --rm \ + -e DEMETER_URL=https://your-node-at.demeter.run \ + xander elixir run_queries_with_demeter.exs + ```
@@ -96,182 +96,167 @@ docker run --rm \ ## Running Queries with native Elixir install -For those with Elixir already installed, simply run the commands below: + For those with Elixir already installed, simply run the commands below: -``` -# Must set a local unix socket -elixir run_queries.exs + ``` + # Must set a local unix socket + elixir run_queries.exs -# Must set a Demeter URL -elixir run_queries_with_demeter.exs -``` + # Must set a Demeter URL + elixir run_queries_with_demeter.exs + ``` -More information on connection below: + More information on connection below: -#### a) Connecting via local UNIX socket + #### a) Connecting via local UNIX socket -Run the following command using your own Cardano node's socket path: - -```bash -CARDANO_NODE_PATH=/your/cardano/node.socket elixir run_queries.exs -``` + Run the following command using your own Cardano node's socket path: -##### Setting up Unix socket mapping (optional when no direct access to Cardano node) + ```bash + CARDANO_NODE_PATH=/your/cardano/node.socket elixir run_queries.exs + ``` -This is useful if you want to run the application on a server different from your Cardano node. + ##### Setting up Unix socket mapping (optional when no direct access to Cardano node) -🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. + This is useful if you want to run the application on a server different from your Cardano node. -1. Run socat on the remote server with the following command: + 🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X. -```bash -socat TCP-LISTEN:3002,reuseaddr,fork UNIX-CONNECT:/home/cardano_node/socket/node.socket -``` + 1. Run socat on the remote server with the following command: -2. Run socat on the local machine with the following command: + ```bash + socat TCP-LISTEN:3002,reuseaddr,fork UNIX-CONNECT:/home/cardano_node/socket/node.socket + ``` -```bash -socat UNIX-LISTEN:/tmp/cardano_node.socket,reuseaddr,fork TCP:localhost:3002 -``` + 2. Run socat on the local machine with the following command: -3. Start an SSH tunnel from the local machine to the remote server with the following command: + ```bash + socat UNIX-LISTEN:/tmp/cardano_node.socket,reuseaddr,fork TCP:localhost:3002 + ``` -```bash -ssh -N -L 3002:localhost:3002 user@remote-server-ip -``` + 3. Start an SSH tunnel from the local machine to the remote server with the following command: -4. Run the example script: + ```bash + ssh -N -L 3002:localhost:3002 user@remote-server-ip + ``` -```bash -CARDANO_NODE_PATH=/tmp/cardano_node.socket elixir run.exs -``` + 4. Run the example script: -#### b) Connecting via Demeter.run + ```bash + CARDANO_NODE_PATH=/tmp/cardano_node.socket elixir run.exs + ``` -To connect to a node at Demeter.run, set `DEMETER_URL` to your Node Demeter URL. + #### b) Connecting via Demeter.run -```bash -DEMETER_URL=https://your-node-at.demeter.run elixir run_queries_with_demeter.exs -``` + To connect to a node at Demeter.run, set `DEMETER_URL` to your Node Demeter URL. + ```bash + DEMETER_URL=https://your-node-at.demeter.run elixir run_queries_with_demeter.exs + ```
Submitting Transactions -## Submitting Transactions - -⚠️ This project does not provide off-chain transaction functionality such as building and signing of transactions. + ## Submitting Transactions -In order to submit transactions via Xander, you can either run the `submit_tx.exs` script directly or use Docker. + ⚠️ This project does not provide off-chain transaction functionality such as building and signing of transactions. -## Running the script + In order to submit transactions via Xander, you can either run the `submit_tx.exs` script directly or use Docker. -This assumes you have Elixir installed. In order to run the script directly, follow the steps below: -1. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) -2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node. -3. Ensure the `Config.default_config!` function call matches the network being used: + ## Running the script + This assumes you have Elixir installed. In order to run the script directly, follow the steps below: + 1. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) + 2. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced Cardano node. + 3. Ensure the `Config.default_config!` function call matches the network being used: - `Config.default_config!(socket_path)` defaults to Mainnet - `Config.default_config!(socket_path, :preview)` for Preview network + 4. Run `elixir submit_tx.exs ` providing the CBOR hex as its single argument. -4. Run `elixir submit_tx.exs ` providing the CBOR hex as its single argument. + A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. -A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. + ## Using Docker -## Using Docker - -This assumes you have Docker installed. No Elixir installation is required. - -1. First, build the image: - -``` -docker build -t xander . -``` + This assumes you have Docker installed. No Elixir installation is required. -2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used: + 1. First, build the image: + ``` + docker build -t xander . + ``` - - `Config.default_config!(socket_path)` defaults to Mainnet + 2. Ensure the `Config.default_config!` function inside the `submit_tx.exs` file matches the network being used: + - `Config.default_config!(socket_path)` defaults to Mainnet - `Config.default_config!(socket_path, :preview)` for Preview network -3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) - -Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to -the container's default socket path (`/tmp/cardano-node-preview.socket`): + 3. Get ahold of the CBOR hex of a valid signed transaction (not covered by this library) -``` -docker run --rm \ --v /your/local/preview-node.socket:/tmp/cardano-node-preview.socket \ -xander elixir submit_tx.exs -``` + Run the previously built Docker image with the `-v` argument, which mounts the path of your local socket path to + the container's default socket path (`/tmp/cardano-node-preview.socket`): -A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer. + ``` + docker run --rm \ + -v /your/local/preview-node.socket:/tmp/cardano-node-preview.socket \ + xander elixir submit_tx.exs + ``` + A successful submission should return the transaction ID. This ID can be used to check the status of the transaction on any Cardano blockchain explorer.
Running ChainSync -## Chain Sync + ## Chain Sync -In order to sync blocks from a Cardano node, you can either run the `run_chain_sync.exs` script directly or use Docker. + In order to sync blocks from a Cardano node, you can either run the `run_chain_sync.exs` script directly or use Docker. -## Running the script + ## Running the script -This assumes you have Elixir installed. In order to run the script directly, follow the steps below: + This assumes you have Elixir installed. In order to run the script directly, follow the steps below: -1. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced **mainnet** Cardano node. -2. Run `elixir run_chain_sync.exs` + 1. Populate the environment variable `CARDANO_NODE_SOCKET_PATH` with a socket file for a fully synced **mainnet** Cardano node. + 2. Run `elixir run_chain_sync.exs` -Using default settings, this will start syncing from the start of the Conway era. For each block, the block number (height) and block size (in bytes) will be displayed. + Using default settings, this will start syncing from the start of the Conway era. For each block, the block number (height) and block size (in bytes) will be displayed. -If you wish to connect with one of the testnets, see comments on the `FollowDaChain.start_link/1` function for more information on exact points in the chain to start syncing from. + If you wish to connect with one of the testnets, see comments on the `FollowDaChain.start_link/1` function for more information on exact points in the chain to start syncing from. -## Using Docker + ## Using Docker -This assumes you have Docker installed. No Elixir installation is required. + This assumes you have Docker installed. No Elixir installation is required. -1. First, build the image: + 1. First, build the image: -``` -docker build -t xander . -``` + ``` + docker build -t xander . + ``` -``` -docker run --rm -v /your/local/cardano-node.socket:/tmp/cardano-node.socket xander elixir run_chain_sync.exs -``` - -## Using Demeter.run + ``` + docker run --rm -v /your/local/cardano-node.socket:/tmp/cardano-node.socket xander elixir run_chain_sync.exs + ``` -Populate the environment variable `DEMETER_URL` with the URL of a node at Demeter.run and run the `run_chain_sync_with_demeter.exs` script. - -``` -DEMETER_URL=https://your-node-at.demeter.run elixir run_chain_sync_with_demeter.exs -``` + ## Using Demeter.run + + Populate the environment variable `DEMETER_URL` with the URL of a node at Demeter.run and run the `run_chain_sync_with_demeter.exs` script. -or use Docker: + ``` + DEMETER_URL=https://your-node-at.demeter.run elixir run_chain_sync_with_demeter.exs + ``` -``` -docker run --rm -e DEMETER_URL=https://your-node-at.demeter.run xander elixir run_chain_sync_with_demeter.exs -``` + or use Docker: + ``` + docker run --rm -e DEMETER_URL=https://your-node-at.demeter.run xander elixir run_chain_sync_with_demeter.exs + ```
## Testing -The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act). - -For x86_64 (Intel/AMD) chips: +The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act) like so: ``` act -j integration_test -``` - -For Apple Silicon (M1/M2/M3) chips: - -``` -act -j integration_test --container-architecture linux/arm64 -``` +``` \ No newline at end of file From 5236bcca72838cd1558c284d28e978af7e11a92e Mon Sep 17 00:00:00 2001 From: Dave Miner Date: Mon, 12 Jan 2026 00:31:45 -0500 Subject: [PATCH 4/4] add instructions for integration tests on apple silicon --- README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1a2abc1..c4ee53b 100644 --- a/README.md +++ b/README.md @@ -255,8 +255,16 @@ For a more detailed description of different ways to use this library, read the ## Testing -The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act) like so: +The integration tests are built upon [Yaci Devkit](https://github.com/bloxbean/yaci-devkit) and can be run locally with [nektos/act](https://github.com/nektos/act). + +For x86_64 (Intel/AMD) chips: ``` act -j integration_test -``` \ No newline at end of file +``` + +For Apple Silicon (M1/M2/M3) chips: + +``` +act -j integration_test --container-architecture linux/arm64 +```