### Configure uniond as a Systemd Service Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Sets up `uniond` to run as a systemd service for automatic startup and restarts. A service file is created in `/etc/systemd/system` specifying the user and the command to start the daemon. This ensures `uniond` runs reliably in the background. ```toml [Unit] Description=uniond [Service] Type=simple Restart=always RestartSec=1 User=$USER ExecStart=/usr/bin/uniond start [Install] WantedBy=multi-user.target ``` -------------------------------- ### Verify uniond Binary Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Checks if the downloaded uniond binary is functional by running the --help command. This is a basic verification step. ```sh ./uniond --help ``` -------------------------------- ### Move uniond Binary to PATH Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Adds the downloaded uniond binary to the system's PATH, allowing it to be executed from any directory. This requires superuser privileges. ```sh mv ./uniond /usr/bin/ ``` -------------------------------- ### Download and Configure Genesis File Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Downloads the genesis.json file from the specified GENESIS_URL and processes it using jq to extract the genesis configuration, saving it to the uniond home directory. ```sh curl $GENESIS_URL | jq '.result.genesis' > ~/.union/config/genesis.json ``` -------------------------------- ### Run Union Docs Development Server (Shell) Source: https://github.com/unionlabs/union/blob/main/docs/README.md This command initiates a development server for the Union project's documentation. It allows for live updates as files in the `site/` directory are edited. Ensure Nix is installed and configured to run the specified development environment. ```sh nix run .#docs-dev-server ``` -------------------------------- ### Download uniond Binary (x86_64-linux) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Downloads the uniond binary for x86_64-linux architecture using curl. The UNIOND_VERSION variable should be set to the desired release version. ```sh curl --output uniond --location https://github.com/unionlabs/union/releases/download/$UNIOND_VERSION/uniond-release-x86_64-linux ``` -------------------------------- ### Download uniond Binary (aarch64-linux) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Downloads the uniond binary for aarch64-linux architecture using curl. The UNIOND_VERSION variable should be set to the desired release version. ```sh curl --output uniond --location https://github.com/unionlabs/union/releases/download/$UNIOND_VERSION/uniond-release-aarch64-linux ``` -------------------------------- ### Install Union SDK with pnpm Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/typescript/index.mdx Installs the Union SDK version 2.0.0-beta.0 or higher using the pnpm package manager. Ensure peer dependencies like 'effect' are met. ```sh pnpm add @unionlabs/sdk@^2.0.0-beta.0 ``` -------------------------------- ### Install Union SDK with npm Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/typescript/index.mdx Installs the Union SDK version 2.0.0-beta.0 or higher using the npm package manager. Ensure peer dependencies like 'effect' are met. ```sh npm install @unionlabs/sdk@^2.0.0-beta.0 ``` -------------------------------- ### Install Union SDK with yarn Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/typescript/index.mdx Installs the Union SDK version 2.0.0-beta.0 or higher using the yarn package manager. Ensure peer dependencies like 'effect' are met. ```sh yarn add @unionlabs/sdk@^2.0.0-beta.0 ``` -------------------------------- ### Install Nix Package Manager Source: https://github.com/unionlabs/union/blob/main/README.md Installs the Nix package manager, which is used for reproducible builds of Union's components. This command fetches and executes the installation script for Nix. ```shell curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install ``` -------------------------------- ### Build and Sign EVM Deployer Transaction using Nix and Cast Source: https://github.com/unionlabs/union/blob/main/tools/build-evm-deployer-tx/README.md This snippet demonstrates how to use Nix to run the `build-evm-deployer-tx` tool to get a signature hash, then use `cast` to sign that hash, and finally use the tool again to generate the raw transaction. It requires `nix` and `cast` to be installed and configured. ```sh SIG_HASH="$(nix run .#build-evm-deployer-tx -- signature-hash)" # the wallet will need to be threaded to cast here (see `cast wallet address --help` for more information) SIG="$(cast wallet sign --no-hash "$SIG_HASH")" nix run .#build-evm-deployer-tx -- raw-tx "$SIG" ``` -------------------------------- ### Initialize uniond Node Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Initializes the uniond node's data and configuration directories with the specified moniker and chain ID. This command creates default configuration files. ```sh uniond init $MONIKER --chain-id $CHAIN_ID ``` -------------------------------- ### Install Union Labs TypeScript SDK Source: https://github.com/unionlabs/union/blob/main/typescript-sdk/README.md This command installs the Union Labs TypeScript SDK using npm. This is the first step to using the SDK in your project. ```sh npm install @unionlabs/client ``` -------------------------------- ### Set Environment Variables for Initialization Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Sets essential environment variables required for initializing the uniond node, including chain ID, moniker, key name, and genesis URL. ```sh export CHAIN_ID=union-1 export MONIKER="unionized-goblin" export KEY_NAME=alice export GENESIS_URL="https://union.build/genesis.json" ``` -------------------------------- ### Create Validator JSON Configuration Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Initializes an empty `validator.json` file and populates it with validator details. This file includes essential information like public key, staking amount, moniker, and commission rates. Replace placeholders with actual values obtained from other commands or desired settings. ```json { "pubkey": , "amount": "1000000au", "moniker": "", "identity": "optional identity signature (ex. UPort or Keybase)", "website": "validator's (optional) website", "security": "validator's (optional) security contact email", "details": "validator's (optional) details", "commission-rate": "0.1", "commission-max-rate": "0.2", "commission-max-change-rate": "0.01", "min-self-delegation": "1" } ``` -------------------------------- ### Submit Create Validator Transaction using uniond Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Submits the transaction to create a validator on the Union network. This command requires the path to the `validator.json` file and the generated proof of possession. It also specifies the wallet key and chain ID. Note that `--gas auto` is not supported; manual gas and fees are required. ```sh uniond tx union-staking create-union-validator $VALIDATOR_JSON_PATH $POSSESSION_PROOF \ --from $KEY_NAME \ --chain-id union-1 ``` -------------------------------- ### View uniond Node Logs Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Displays the real-time logs for the `uniond` service using `journalctl`. This command is useful for monitoring the node's activity and troubleshooting any issues. ```sh sudo journalctl -f --user uniond ``` -------------------------------- ### NixOS Configuration for Unionvisor Validator Source: https://github.com/unionlabs/union/blob/main/unionvisor/README.md This snippet demonstrates a complete NixOS configuration for a validator node using Unionvisor. It includes setting up the uniond service, defining firewall rules, and installing optional inspection tools. The configuration relies on the `union.nixosModules.unionvisor` module and specific Nixpkgs versions. ```nix { inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; union.url = "git+ssh://git@github.com/unionlabs/union"; }; outputs = { self, nixpkgs, union, ... }: { nixosConfigurations.testnet-validator = let system = "x86_64-linux"; pkgs = import nixpkgs { inherit system; }; in nixpkgs.lib.nixosSystem { inherit system; modules = [ union.nixosModules.unionvisor { system.stateVersion = "23.11"; # Base configuration for openstack-based VPSs imports = [ "${nixpkgs}/nixos/modules/virtualisation/openstack-config.nix" ]; # Allow other validators to reach you networking.firewall.allowedTCPPorts = [ 80 443 26656 26657 ]; # Unionvisor module configuration services.unionvisor = { enable = true; moniker = "your-testnet-moniker"; }; # OPTIONAL: Some useful inspection tools for when you SSH into your validator environment.systemPackages = with pkgs; [ bat bottom helix jq neofetch tree ]; } ]; }; }; } ``` -------------------------------- ### Add Union Wallet using uniond CLI Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/infrastructure/node-operators/getting-started.mdx Adds a new wallet or recovers an existing one using the `uniond keys add` command. This wallet will hold Union tokens for validator operations. It's recommended not to store the wallet on a production server. ```sh uniond keys add $KEY_NAME --recover ``` -------------------------------- ### Voyager CLI: Start Relayer with Configuration (Bash) Source: https://context7.com/unionlabs/union/llms.txt Starts the Voyager relayer service, responsible for relaying cross-chain messages. This involves initializing the relayer's configuration file with chain details and then starting the relayer daemon using the 'voyager queue' command. The configuration specifies RPC and IBC handler URLs for different chains, while the command sets the configuration file path, database URL, and number of workers. ```bash # Initialize configuration voyager config init \ --config-file ./config.json \ --chains ethereum.11155111,union.union-testnet-10 # Start relayer daemon voyager queue \ --config-file ./config.json \ --database-url postgres://localhost/voyager \ --workers 8 \ --log-level info # Example configuration file (config.json): cat > config.json < mapping(uint32 => mapping(bytes => bytes))) public beneficiaries; struct DEXParams { uint256 maxSlippage; address[] routePath; uint256 deadline; } function solve( IBCPacket calldata packet, TokenOrderV2 calldata order, uint256 path, address caller, address relayer, bytes calldata relayerMsg, bool intent ) external override returns (bytes memory) { require(!intent, "only finalized txs are currently supported"); // Decode the SolverMetadata from the order SolverMetadata memory solverMeta = abi.decode(order.metadata, (SolverMetadata)); // Decode custom parameters from the solver metadata's metadata field DEXParams memory params = abi.decode(solverMeta.metadata, (DEXParams)); // Validate deadline require(block.timestamp <= params.deadline, "Order expired"); // The quoteToken from the order specifies what token to provide address quoteToken = address(bytes20(order.quoteToken)); address receiver = address(bytes20(order.receiver)); // Validate that we support this quote token require(isSupported(quoteToken), "Unsupported quote token"); // Perform the trade to obtain the quote tokens uint256 outputAmount = findBestRouteAndTrade( order.baseToken, ``` -------------------------------- ### NixOS Configuration Example for Unionvisor Source: https://github.com/unionlabs/union/blob/main/unionvisor/docs/README.md This snippet demonstrates a typical flake.nix configuration for setting up a production-ready machine running a validator under unionvisor using the unionbundle. It showcases how to integrate unionvisor with NixOS for managing uniond deployments and blockchain synchronization. ```nix { inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; unionbundle.url = "github:unionlabs/unionbundle"; unionvisor.url = "github:unionlabs/union"; }; outputs = { self, nixpkgs, unionbundle, unionvisor }: let system = "x86_64-linux"; pkgs = nixpkgs.legacyPackages.${system}; in { nixosConfigurations.unionvisor = nixpkgs.lib.nixosSystem { inherit system; modules = [ ({ config, pkgs, ... }: { services.unionvisor.enable = true; services.unionvisor.package = unionvisor; services.unionvisor.unionbundle = unionbundle; # Additional configuration for unionvisor can be added here # For example, specifying network, genesis, etc. }) # You might want to include other modules for your system # e.g., ./hardware-configuration.nix ]); }; }; } ``` -------------------------------- ### Run Drip Faucet with Configuration Source: https://github.com/unionlabs/union/blob/main/drip/README.md This command starts the Drip faucet application using Nix, specifying a configuration file. The '--' separates Nix arguments from the application's arguments. Ensure './drip/config.json' is a valid Drip configuration. ```sh nix run .#drip -- -c ./drip/config.json ``` -------------------------------- ### Complex Solver Logic with Multi-Step Execution (Solidity) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/ucs/03.mdx This example shows how to configure a solver order for multi-step execution. It defines a `MultiStepParams` struct to specify intermediate tokens, minimum outputs at each step, and custom data for swaps. The `TokenOrderV2` is then created with this metadata. ```solidity struct MultiStepParams { uint8 steps; address[] intermediateTokens; uint256[] minOutputs; bytes[] customData; } // Create a solver order with multi-step instructions SolverMetadata memory solverMeta = SolverMetadata({ solverAddress: abi.encodePacked(address(multiStepSolver)), metadata: abi.encode(MultiStepParams({ steps: 3, intermediateTokens: [USDC, WETH, TARGET_TOKEN], minOutputs: [1000e6, 0.5e18, 100e18], customData: [swapParams1, swapParams2, swapParams3] })) }); TokenOrderV2 memory order = TokenOrderV2({ sender: abi.encodePacked(msg.sender), receiver: abi.encodePacked(recipient), baseToken: abi.encodePacked(USDC), baseAmount: 1000e6, quoteToken: abi.encodePacked(TARGET_TOKEN), // Final token solver should provide quoteAmount: 100e18, // Minimum TARGET_TOKEN output expected kind: TOKEN_ORDER_KIND_SOLVE, metadata: abi.encode(solverMeta) }); ``` -------------------------------- ### Solidity Example: Batching Orders and Funded Call with ZKGM Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/ucs/06.mdx Demonstrates how to construct a ZKGM batch instruction that includes token transfer orders followed by a funded contract call using the UCS06 protocol. This example illustrates composing multiple ZKGM instructions for complex cross-chain operations. ```solidity // ZKGM( // Batch[ // Order(TokenA -> FundedDispatch, amountA), // Order(TokenB -> FundedDispatch, amountB), // Call( // FundedDispatch( // Funds[TokenA, TokenB], // Call[ // Staking.stake( // amountA, // amountB, // receiver // ) // ] // ) // ) // ] // ) Instruction[] memory instructions = new Instruction[](3); // Add two token transfer orders instructions[0] = makeTokenOrderV1(...); // Transfer token A instructions[1] = makeTokenOrderV1(...); // Transfer token B // Add a funded dispatch call to stake the tokens FundedDispatchFund[] memory funds = new FundedDispatchFund[](2); funds[0] = FundedDispatchFund({ token: tokenA, amount: amountA }); funds[1] = FundedDispatchFund({ token: tokenB, amount: amountB }); FundedDispatchParameters memory params = FundedDispatchParameters({ flags: FLAG_DEFAULT, funds: funds, contractAddress: stakingContract, contractCalldata: abi.encodeCall(IStaking.stake, (amountA, amountB, receiver)), beneficiary: receiver }); // Add the funded dispatch as a multiplex instruction instructions[2] = makeCallCall( sender, false, // not eureka mode fundedDispatchContract, abi.encode(params) ); // Create and send the batch Instruction memory batchInstruction = makeBatch(instructions); zkgm.send( channelId, timeoutHeight, timeoutTimestamp, salt, batchInstruction ); ``` -------------------------------- ### Start uniond Node with Docker Compose Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/obtaining-uniond.mdx Starts the uniond node in detached mode using Docker Compose. This command assumes a 'compose.yml' file (or similar) has been created with the node configuration. ```shell docker compose --file path/to/compose.yaml up --detach ``` -------------------------------- ### Example ProxyAccount Call Preparation (Solidity) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/ucs/03.mdx Demonstrates how to prepare calldata for a ProxyAccount to execute a call on a remote chain. Encodes the target contract, value, and function payload for a cross-chain transaction. ```Solidity // On source chain, prepare a call to be executed via ProxyAccount bytes memory proxyCalldata = abi.encode( targetContract, // Contract to call on destination 0, // ETH value to send abi.encodeCall( // The actual function call IERC20.transfer, (recipient, amount) ) ); // Prepare a call instruction to submit. Call memory call = Call({ sender: abi.encodePacked(msg.sender), eureka: false, contractAddress: abi.encodePacked(proxyAccountAddress), contractCalldata: proxyCalldata }); ``` -------------------------------- ### Minimal Docker Compose for uniond Node Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/obtaining-uniond.mdx Defines a Docker Compose configuration to run a uniond node. It specifies the Docker image, mounts the local configuration directory, uses host networking, and sets the command to start the node. The 'restart: unless-stopped' policy ensures the container restarts if it crashes. ```yaml services: node: image: ghcr.io/unionlabs/uniond-release:${UNIOND_VERSION} volumes: - ~/.union:/.union - /tmp:/tmp network_mode: "host" restart: unless-stopped command: start --home /.union ``` -------------------------------- ### Update Vendored Go Dependencies with Nix Source: https://github.com/unionlabs/union/wiki/Useful-Commands This Nix command updates the vendored Go dependencies for projects within the unionlabs/union repository, such as 'uniond' and 'galoisd'. Ensure Nix is installed and configured. ```shell nix run .#go-vendor ``` -------------------------------- ### Generate Proof of Possession Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/creating-validators.mdx This snippet shows how to generate a proof of possession for a validator key. It covers two scenarios: using a standard uniond-release setup and using Unionvisor. The `jq` command extracts the private key, and `uniond prove-possession` generates the proof. ```shell export PRIV_KEY=$(jq -r '.priv_key.value' ~/.union/config/priv_validator_key.json) export POSSESSION_PROOF=$(uniond prove-possession "$PRIV_KEY") ``` ```shell export PRIV_KEY=$(jq -r '.priv_key.value' ~/.unionvisor/home/config/priv_validator_key.json) export POSSESSION_PROOF=$(uniond prove-possession "$PRIV_KEY") ``` -------------------------------- ### Example Configuration for Voyager Transaction Batch Plugin Source: https://github.com/unionlabs/union/blob/main/voyager/plugins/transaction-batch/README.md This JSON configuration defines parameters for the Voyager Transaction Batch Plugin, including chain ID, client configurations with batch size limits, and maximum wait times for event batching. It illustrates how to set up the plugin for specific IBC chains and clients. ```json { "chain_id": "32382", "client_configs": [ { "client_id": 1, "min_batch_size": 1, "max_batch_size": 3, "max_wait_time": { "secs": 10, "nanos": 0 } } ] } ``` -------------------------------- ### Run galoisd CLI Help (Shell) Source: https://github.com/unionlabs/union/blob/main/galoisd/README.md This command displays the up-to-date overview of functions available in the galoisd CLI. It's a self-documenting feature for understanding the service's capabilities and options. ```shell nix run .#galoisd -- --help ``` -------------------------------- ### Build Union Components with Nix Source: https://github.com/unionlabs/union/blob/main/README.md Demonstrates how to build specific components of the Union project using Nix. These commands trigger Nix to fetch dependencies and compile the specified packages. ```shell nix build .#uniond -L nix build .#voyager -L nix build .#app -L # to see all packages, run: nix flake show ``` -------------------------------- ### Initialize Cosmos Chain Home Directory Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/new-chain.mdx Initializes a new Cosmos chain's home directory and creates a wallet for the chain. This sets up the necessary configuration files and keypair for interacting with the chain. ```bash mkdir ./starsd-home ./starsd init --chain-id elgafar-1 --home ./starsd-home cor-systems ./starsd keys add cor-systems --home ./starsd-home ``` -------------------------------- ### Initialize Rust Project for CosmWasm Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/app/asset-transfer/cosmwasm.mdx Creates a new Rust library project for a CosmWasm contract and navigates into the project directory. This is the initial step for setting up a new smart contract. ```sh cargo new --lib example-ucs03-cosmwasm cd example-ucs03-cosmwasm ``` -------------------------------- ### Initialize uniond Chain Configuration with Docker Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/obtaining-uniond.mdx Initializes the chain configuration and state folder within the Docker container by mounting the local '~/.union' directory. This command ensures the container runs with the current user's permissions and interacts with the mounted volume. ```shell docker run \ --user $(id -u):$(id -g) \ --volume ~/.union:/.union \ --volume /tmp:/tmp \ -it ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION init $MONIKER \ --home /.union ``` -------------------------------- ### Pagination Guide Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/api/graphql.mdx Guide to using cursor-based pagination with `p_limit`, `p_sort_order`, and `p_comparison` parameters. ```APIDOC ## Pagination Guide This API uses cursor-based pagination with three parameters that control which data is returned: ### Parameters - **`p_limit`** Maximum number of items to return. - Default: `100` - Maximum: `100` - **`p_sort_order`** Acts as a cursor for pagination. - For the **next page**, pass the `sort_order` value of the **last item** in the current result set. - For the **previous page**, pass the `sort_order` value of the **first item** in the current result set. - **`p_comparison`** Controls the pagination direction: - `"lt"`: Fetch the **next** page (items **after** the given `sort_order`), results are returned in **descending** order. - `"gt"`: Fetch the **previous** page (items **before** the given `sort_order`), results are returned in **ascending** order. ### Notes - Each result includes a `sort_order` field used for pagination. - **Do not parse or rely on the contents** of the `sort_order` value — its structure may change at any time. Treat it as an opaque value. - **Do not use external filtering or sorting options** — pagination and ordering are controlled solely through these parameters. ### Example: Fetch first page (latest transfers) No cursor needed. This returns the most recent transfers. ```graphql query GetInitialTransfers { v2_transfers(args: { p_limit: 20 }) { sender_canonical receiver_canonical base_amount sort_order } } ``` ### Example: Fetch next page Use the `sort_order` value of the **last item** from the previous result. Set `p_comparison: "lt"` to fetch items after it (newer → older). ```graphql query GetNextPage { v2_transfers(args: { p_limit: 20, p_sort_order: "cursor-from-last-item", p_comparison: "lt" }) { sender_canonical receiver_canonical base_amount sort_order } } ``` ``` -------------------------------- ### Get Union Testnet Validator Address Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/getting-tokens.mdx This command retrieves the validator address for your Union Testnet account. This is specifically used for validator-related operations. ```shell uniond keys show $KEY_NAME --bech=val --address ``` -------------------------------- ### Initialize Unionvisor Chain Configuration and State Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/unionvisor.mdx This command initializes the Unionvisor configuration and state folder using Docker. It mounts a local directory (~/.unionvisor) into the container and also mounts /tmp. The 'init' command sets up themoniker, network, and seeds for the uniond node. ```sh docker run \ --volume ~/.unionvisor:/.unionvisor \ --volume /tmp:/tmp \ -it ghcr.io/unionlabs/bundle-testnet-10:$UNIONVISOR_VERSION \ init --moniker $MONIKER \ --network union-testnet-10 \ --seeds "${chainVersion({chainId: 'union-testnet-10'}).seeds}" ``` -------------------------------- ### Get Union Testnet Account Address Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/getting-tokens.mdx This command retrieves the public address associated with your Union Testnet account. This address is needed to receive testnet tokens. ```shell uniond keys show $KEY_NAME --address ``` -------------------------------- ### Example JSON Response for Decoded Client State Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/architecture/voyager/concepts.mdx An example of a decoded client state for an Ethereum client. The `state` field is now a JSON object containing details like `chain_id`, `genesis_time`, and `ibc_contract_address`, instead of raw bytes. ```json { "height": "1-2194412", "state": { "data": { "chain_id": 1, "chain_spec": "mainnet", "frozen_height": "0", "genesis_time": 1606824023, "genesis_validators_root": "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95", "ibc_contract_address": "0xee4ea8d358473f0fcebf0329feed95d56e8c04d7", "latest_height": 23031324 }, "version": "v1" } } ``` -------------------------------- ### Initialize Foundry Project Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/app/asset-transfer/solidity.mdx Initializes a new Foundry project for the Solidity contract. This command sets up the basic directory structure required for a Foundry project, including source files, scripts, and tests. ```sh forge init ucs03-asset-transfer ``` -------------------------------- ### IZkgmable Interface Implementation Example (Solidity) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/ucs/03.mdx Provides an example implementation of the `IZkgmable` interface for contracts that need to receive cross-chain messages via ZKGM. It includes an event for received messages and the `onZkgm` function for processing incoming data. ```Solidity contract MyContract is IZkgmable { event MessageReceived( uint256 path, uint32 sourceChannelId, uint32 destinationChannelId, address sender, bytes message ); function onZkgm( uint256 path, uint32 sourceChannelId, uint32 destinationChannelId, bytes calldata sender, bytes calldata message ) external { // Verify caller is zkgm contract require(msg.sender == address(zkgm), "Only zkgm"); // Verify that the sourceChannelId and sender are authorized... // Process the cross-chain message emit MessageReceived( path, sourceChannelId, destinationChannelId, address(bytes20(sender)), message ); } } ``` -------------------------------- ### Example JSON Response for Client State Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/architecture/voyager/concepts.mdx An example JSON output representing the raw state of a client queried via the voyager RPC interface. It includes the block height at which the state was retrieved and the state data as a hexadecimal string. ```json { "height": "2194359", "state": "0x000000000100000000000000010000004b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe955730c65f000000001c6e5f0100000000000000000000000000ee4ea8d358473f0fcebf0329feed95d56e8c04d700" } ``` -------------------------------- ### Build Union Binaries with Nix Source: https://github.com/unionlabs/union/blob/main/ARCHITECTURE.md This snippet demonstrates how to use the Nix package manager to build specific binaries for the Union network, such as `uniond`, `unionvisor`, or `galoisd`. It assumes a Nix environment is set up. ```nix nix build .#uniond # or unionvisor or galoisd ``` -------------------------------- ### Create Union Client using Relayer Source: https://github.com/unionlabs/union/wiki/Architecture-Overview This command demonstrates how to create a client for a Union network using the 'relayer' tool, specifying counterparty details and an EVM preset. It's a prerequisite for establishing IBC connections and channels. ```shell # Create a union client relayer client create union ethereum08-wasm \ --on union-devnet \ --counterparty ethereum-devnet \ --evm-preset minimal ``` -------------------------------- ### Create uniond Data Directory Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/obtaining-uniond.mdx Creates a directory named '.union' in the user's home directory to store the chain configuration and state. This directory will be mounted into the Docker container. ```shell mkdir ~/.union ``` -------------------------------- ### Example JSON Response for Latest Client State Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/architecture/voyager/concepts.mdx An example JSON output for the latest client state. The height format indicates a block range, and the state is represented as a hexadecimal string. This output is typical when the `--height` flag is omitted and a finality module is configured. ```json { "height": "1-2194387", "state": "0x000000000100000000000000010000004b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe955730c65f000000001c6e5f0100000000000000000000000000ee4ea8d358473f0fcebf0329feed95d56e8c04d700" } ``` -------------------------------- ### Build and Publish to NPM Source: https://github.com/unionlabs/union/blob/main/typescript-sdk/README.md These commands build the project and then publish the package to the npm registry. Ensure you run the build command before publishing to include all necessary changes. ```sh npm run build # important! npm publish --access='public' --no-git-tags ``` -------------------------------- ### Combine Filters with Pagination - GraphQL Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/api/graphql.mdx This example demonstrates how to combine filtering by `p_source_universal_chain_id` with pagination parameters (`p_sort_order` and `p_comparison`) to paginate through a specific subset of data. ```graphql query FilterAndPaginate { v2_transfers(args: { p_limit: 20, p_source_universal_chain_id: "union.union-testnet-10", p_sort_order: "cursor-from-last-item", p_comparison: "lt" }) { sender_canonical receiver_canonical base_amount sort_order } } ``` -------------------------------- ### Build Tendermint Light Client with Nix Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/new-chain/cosmwasm.mdx Builds the Tendermint light client using Nix. This command fetches the necessary dependencies from the specified GitHub repository and compiles the light client artifact. ```sh nix build github:unionlabs/union#tendermint-light-client -L ``` -------------------------------- ### C++: String Length Calculation Source: https://github.com/unionlabs/union/blob/main/app2/src/lib/config/base64.txt Shows how to get the length of a std::string object in C++ using the .length() method. This is useful for determining buffer sizes or iterating over strings. ```cpp int len = s1.length(); ``` -------------------------------- ### Instantiate CometBLS Contract on Stargaze Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/new-chain/cosmwasm.mdx Instantiates the CometBLS light client contract on Stargaze, providing the `ibc_host` address of the Union chain. This step deploys the contract instance and associates it with the specified configuration. ```sh ./starsd tx wasm instantiate 5012 '{"ibc_host": "stars1s0x3yq0pmltxq56f4yppgmd02ret3uj5k9ftj6ug9c7lc379sw7qv396zm"}' \ --node $STARGAZE_RPC_URL \ --home ./starsd-home \ --from $KEY_NAME \ --gas auto \ --gas-adjustment 1.4 \ --gas-prices 1ustars \ --label cosmwasm-union-testnet-9-1 \ --admin stars1qcvavxpxw3t8d9j7mwaeq9wgytkf5vwputv5x4 \ --chain-id elgafar-1 \ -y ``` -------------------------------- ### Filter by Transaction Hash - GraphQL Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/api/graphql.mdx This example shows how to filter the `v2_transfers` query by a specific transaction hash. Filters must be passed via the `args` object, not GraphQL-level `where` clauses. ```graphql query FilterByTransactionHash { v2_transfers(args: { p_limit: 20, p_transaction_hash: "0x9276722fb205ddf6bf94e5baa03ae990e4d4ef44a4342cbf17396f00a6313d57" }) { sender_canonical receiver_canonical base_amount sort_order } } ``` -------------------------------- ### Create New Union Testnet Account Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/joining-testnet/getting-tokens.mdx This command creates a new account and generates a mnemonic phrase for your Union Testnet account. Ensure you securely store the outputted mnemonic. ```shell uniond keys add $KEY_NAME ``` -------------------------------- ### Create Contract Running Script (Solidity) Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/connect/app/asset-transfer/solidity.mdx A Foundry script to deploy and interact with the Transfer contract. The `run` function handles broadcasting transactions, instantiating the Transfer contract, transferring UNO tokens, and initiating the asset transfer via `transferAsset`. ```solidity pragma solidity ^0.8.27; import {Script, console} from "forge-std/Script.sol"; import {Transfer} from "../src/Transfer.sol"; import {IERC20} from "forge-std/interfaces/IERC20.sol"; contract TransferScript is Script { address public constant UNO = 0xF2865969cF99A28Bb77e25494fE12D5180fE0efD; function run() public { uint256 privateKey = vm.envUint("PRIVATE_KEY"); vm.startBroadcast(privateKey); Transfer transfer = new Transfer(); IERC20(UNO).transfer(address(transfer), 1500000); console.log("transferring"); transfer.transferAsset(); console.log("complete"); vm.stopBroadcast(); } } ``` -------------------------------- ### Example: Fetch Initial Transfers (Latest Page) - GraphQL Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/api/graphql.mdx Demonstrates how to fetch the first page of transfers, which are the most recent ones. This query uses `p_limit` but no cursor parameters, returning the latest items. ```graphql query GetInitialTransfers { v2_transfers(args: { p_limit: 20 }) { sender_canonical receiver_canonical base_amount sort_order } } ``` -------------------------------- ### WASM Light Client Contract Instantiation (Rust) Source: https://github.com/unionlabs/union/wiki/IBC‐go-`08‐wasm`-Guide Implements the `instantiate` entrypoint for WASM light client contracts. This function is called when the contract is first deployed and receives the initial configuration including client state, consensus state, and checksum. ```rust #[entry_point] pub fn instantiate( mut deps: DepsMut, env: Env, info: MessageInfo, msg: InstantiateMsg, ) -> Result; ``` -------------------------------- ### C++: String Substring Replacement Source: https://github.com/unionlabs/union/blob/main/app2/src/lib/config/base64.txt Shows replacing a portion of a string with another string using `replace`. This overload allows specifying the starting position, length of the segment to replace, and the replacement string. ```cpp std::string s = "abcdefgh"; s.replace(2, 3, "XYZ"); // s becomes "abcXYZfgh" ``` -------------------------------- ### Create Client Transaction CLI Command Source: https://github.com/unionlabs/union/wiki/Ethereum-light-client This CLI command is used to send the `CreateClient` transaction to instantiate a new IBC light client. It requires paths to JSON files containing the client state and consensus state configurations. ```bash uniond tx ibc client create [path/to/client_state.json] [path/to/consensus_state.json] ``` -------------------------------- ### Pre-signed Transaction (100 Gwei) Source: https://github.com/unionlabs/union/blob/main/tools/build-evm-deployer-tx/pre-signed-txs.md An example of a pre-signed transaction with a gas price of 100 gwei. This transaction is intended for deployment within the Union IBC stack and includes the necessary bytecode. ```ethereum-transaction 0xf903418085174876e800830493e08080b902ee608080604052346015576102d4908161001a8239f35b5f80fdfe60806040526004361015610011575f80fd5b5f3560e01c63d83c113814610024575f80fd5b346102055760603660031901126102055760043567ffffffffffffffff8111610205573660238201121561020557610066903690602481600401359101610258565b6024359067ffffffffffffffff821161020557366023830112156102055781600401359167ffffffffffffffff831161020557366024848301011161020557604051608081016040526f30313233343536373839616263646566600f526002810192602884525f604a8301523360601b60015f5b8080018501602284831a600f811651602384015360041c5191015301906014821461010857906001906100da565b505061017d600161018b9560226020825195613078600288019452838852604051968794838087019a018a5e8401907f2f0000000000000000000000000000000000000000000000000000000000000084830152805192839101602383015e01015f838201520301601f198101835282610209565b519020926024369201610258565b906f67363d3d37363d34f03d5260086018f35f526010805ff59081156101f8575f80918360145261d694825260016034536017601e209360208251920190604435905af1813b02156101f85760209073ffffffffffffffffffffffffffffffffffffffff60405191168152f35b63301164255f526004601cfd5b5f80fd5b90601f8019910116810190811067ffffffffffffffff82111761022b57604052565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b92919267ffffffffffffffff821161022b5760405191610282601f8201601f191660200184610209565b829481845281830111610205578281602093845f96013701015256fea264697066735822122033d99c7c2a972ec5b96de29f5b4d23e6db548a0751b6849b2d3d9d6efd3d03ed64736f6c634300081b00331ba0278117804b13cc66257e3e1174e919275fd5c1cf0adc5e9afbfa75713d6c8773a050365dacbdf549c14f03815876eb259d971986899160056ce83ed40018859bc5 ``` -------------------------------- ### Deploy IBC Package with Nix Source: https://github.com/unionlabs/union/blob/main/aptos/README.md Deploys an IBC package using the Movement CLI. This command initializes and publishes the Move IBC package to the network. It requires specifying the package directory and can optionally skip git dependencies and override size checks. ```bash nix run .#movement move create-object-and-publish-package -- --address-name ibc --package-dir move/move-ibc --skip-fetch-latest-git-deps --override-size-check --included-artifacts none ``` -------------------------------- ### C++: String Erase Range Source: https://github.com/unionlabs/union/blob/main/app2/src/lib/config/base64.txt Demonstrates erasing a range of characters from a std::string using the `.erase()` method, specifying a starting position and the number of characters to remove. This is useful for removing sections of text. ```cpp std::string s = "abcdefghi"; s.erase(3, 3); // Removes "def", s becomes "abcghi" ``` -------------------------------- ### Download GraphQL Schema using graphqurl Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/api/graphql.mdx This snippet shows how to download the GraphQL schema using the graphqurl CLI tool. It provides options to save the schema in both .graphql and .json formats. This requires pnpm to be installed. ```sh pnpm dlx graphqurl https://graphql.union.build/v1/graphql \ --introspect > schema.graphql ``` ```sh pnpm dlx graphqurl https://graphql.union.build/v1/graphql \ --introspect \ --format json > schema.json ``` -------------------------------- ### Execute zkgm Request and Handle Response Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/typescript/guided-tutorial/evm-holesky-sepolia.mdx Executes a zkgm request using ZkgmClient and waits for the completion of the EVM transaction receipt. It logs the submission hash and the final completion event. ```typescript import { ChannelId } from "@unionlabs/sdk/schema/channel" import * as ZkgmClient from "@unionlabs/sdk/ZkgmClient" import * as ZkgmClientRequest from "@unionlabs/sdk/ZkgmClientRequest" import * as ZkgmClientResponse from "@unionlabs/sdk/ZkgmClientResponse" import * as ZkgmIncomingMessage from "@unionlabs/sdk/ZkgmIncomingMessage" import { Effect, Logger } from "effect" const program = Effect.gen(function*() { // ... snip ... const zkgmClient = yield* ZkgmClient.ZkgmClient // NOTE: 1. switch chain is assumed // NOTE: 2. write in progress const response: ZkgmClientResponse.ZkgmClientResponse = yield* zkgmClient.execute(request) // NOTE: 3. write complete (with tx hash) yield* Effect.log("Submission Hash", response.txHash) const completion = yield* response.waitFor( ZkgmIncomingMessage.LifecycleEvent.$is("EvmTransactionReceiptComplete"), ) // NOTE: 4. tx complete yield* Effect.log("Completion", completion) }) ``` -------------------------------- ### Calculating Union IBC Stack Contract Addresses Source: https://github.com/unionlabs/union/blob/main/evm/README.md This command-line example demonstrates how to calculate the specific addresses for the Union IBC stack contracts. It utilizes a `nix` command with the `evm-contracts-addresses` tool, taking the precomputed deployer address and a sender address as input. The output lists the addresses for various contracts like IBCHandler and CometblsClient. ```sh nix run .#evm-contracts-addresses -- 0x86D9aC0Bab011917f57B9E9607833b4340F9D4F8 0xBe68fC2d8249eb60bfCf0e71D5A0d2F2e292c4eD ``` -------------------------------- ### Create zkgm Client Request Source: https://github.com/unionlabs/union/blob/main/docs/src/content/docs/integrations/typescript/guided-tutorial/evm-holesky-sepolia.mdx Creates a zkgm client request using the constructed token order as an instruction. It includes source and destination chains, channel ID, and the ucs03 address. ```typescript import * as ZkgmClientRequest from "@unionlabs/sdk/ZkgmClientRequest" import { Effect, Logger } from "effect" const program = Effect.gen(function*() { // ... snip ... const request = ZkgmClientRequest.make({ source, destination, channelId: ChannelId.make(2), ucs03Address: "0x5fbe74a283f7954f10aa04c2edf55578811aeb03", instruction: tokenOrder, }) }) ``` -------------------------------- ### WASM Light Client Instantiation Message (Go) Source: https://github.com/unionlabs/union/wiki/IBC‐go-`08‐wasm`-Guide Defines the structure of the `InstantiateMessage` passed to the `instantiate` entrypoint of a WASM light client contract. It includes the initial client state, consensus state, and a checksum, all as byte slices. ```go type InstantiateMessage struct { ClientState []byte `json:"client_state"` ConsensusState []byte `json:"consensus_state"` Checksum []byte `json:"checksum"` } ```