Integrate a Conduit

This guide walks you through integrating a deployed Conduit into your platform. By the end, you’ll be able to show balances, handle deposits and withdrawals, preview operations with fees, and monitor positions through the Railnet API.

This guide assumes a Conduit has already been deployed for your platform. If you need to deploy one first, see Create a Conduit.

Prerequisites

Conduit address — the deployed Conduit contract on your target network
RPC endpoint — an Ethereum JSON-RPC provider (Alchemy, Infura, etc.)
Railnet API endpoint — https://graphql-enriched.staging.railnet.org/query (staging)

Read Conduit state

A Conduit exposes view functions you can call directly on-chain to display balances, share prices, and product status in your UI.

Product info

// The underlying asset (e.g., USDC)
address asset = conduit.asset();

// The underlying Vehicle (strategy) the Conduit wraps
IVehicle vehicle = conduit.getVehicle();

// Whether the Conduit is enabled and accepting operations
bool isReady = conduit.ready();

// Coming soon

// Total underlying assets managed by the Conduit
uint256 tvl = conduit.totalAssets();

// Total Conduit shares in circulation
uint256 supply = conduit.totalSupply();

// A specific user's share balance
uint256 userShares = conduit.balanceOf(userAddress);

// Share price: assets per share (no fees applied)
Asset memory shareValue = conduit.convert(
    Asset({asset: address(conduit), value: 1e18}),  // 1 share
    true                                            // shares → assets
);

// Coming soon

Preview operations

Use estimate() to show users what they’ll receive after fees before they commit to a transaction. Use convert() for a pure conversion without fees (e.g., displaying portfolio value).

// How many cShares will the user get for 100 USDC? (includes fees)
Asset memory estimated = conduit.estimate(
    Asset({asset: address(usdc), value: 100e6}),
    Mode.DEPOSIT,
    EstimationType.OUTPUT
);
// estimated.value = cShares the user will receive

// How much USDC for burning 50 cShares? (includes fees)
Asset memory redeemEstimate = conduit.estimate(
    Asset({asset: address(conduit), value: 50e18}),
    Mode.REDEEM,
    EstimationType.OUTPUT
);
// redeemEstimate.value = USDC the user will receive

// Coming soon

estimate() includes all fee types (deposit, redeem, management, performance). Use it for transaction previews. Use convert() for display-only share-to-asset conversions where fees don’t apply.

Handle deposits

Users deposit base assets (e.g., USDC) and receive Conduit shares representing proportional ownership. The Conduit handles all interaction with the underlying strategy.

Approve the Conduit

The user approves the Conduit to spend their tokens.

IERC20(usdc).approve(address(conduit), amount);

// Coming soon

Create the deposit

The Conduit binds each query id to its creator: query.salt must equal keccak256(abi.encode(msg.sender, sourceSalt)), otherwise create reverts InvalidQuerySalt. This stops anyone else from occupying the id your user’s query would get.

bytes32 sourceSalt = keccak256(abi.encode("deposit", nonce));

Query memory query = Query({
    owner: address(conduit),
    receiver: address(conduit),
    input: Asset({asset: address(usdc), value: amount}),
    output: Asset({asset: address(conduit.getVehicle()), value: 0}),
    mode: Mode.DEPOSIT,
    salt: keccak256(abi.encode(msg.sender, sourceSalt)),
    data: ""
});

// Create the deposit — auto-processes for sync strategies
(Id queryId, State state) = conduit.create(query, userAddress, sourceSalt);

// Coming soon

The query’s owner and receiver are always the Conduit; the userAddress argument is who receives the minted cShares.

output.value is a floor enforced at the Vehicle output only. It ignores Conduit fees and the cShare exchange rate, so it does not bound what the user finally receives — set it from estimate() if you need slippage protection, or 0 to disable it.

For sync strategies (e.g., Aave, Compound), the deposit settles in the same transaction. The user receives shares immediately.For async strategies (e.g., Ethena, Syrup), the query enters PROCESSING. A keeper calls process() automatically when the underlying protocol is ready — the user doesn’t need to take any further action.

Handle withdrawals

Users burn Conduit shares and receive the underlying asset. Call createRedeemFromConduitShares — it converts the cShare amount to Vehicle shares at the current ratio and hands the assembled REDEEM query to the same create entrypoint. Building the query yourself only makes sense if you already hold a Vehicle-share figure; input.asset would then have to be the Vehicle address, never the Conduit’s.

bytes32 sourceSalt = keccak256(abi.encode("redeem", nonce));

// Minimum asset to receive; 0 disables the floor
Asset memory outputAsset = Asset({asset: address(usdc), value: minAssetsOut});

// Burns the caller's cShares — auto-processes for sync strategies
(Id queryId, State state) = conduit.createRedeemFromConduitShares(
    shareAmount,
    outputAsset,
    sourceSalt,
    userAddress
);

// Coming soon

No approve call is needed on either path. The Conduit recognizes a Vehicle-share input and burns the caller’s cShares through its internal ERC-20 primitives, so a withdrawal is a single transaction.

Same settlement behavior as deposits: sync strategies settle immediately, async strategies are settled automatically by keepers.

For async strategies, keepers monitor active queries and call process() when the underlying protocol is ready to settle. Your platform doesn’t need to build monitoring infrastructure, and users never need to return for a second transaction. The experience is identical for sync and async strategies from the user’s perspective.

Monitor with the Railnet API

The Railnet GraphQL API provides indexed on-chain data for building dashboards, tracking operations, and generating reports. Use it alongside on-chain view calls for a complete picture.

https://graphql-enriched.staging.railnet.org/query

This is the staging endpoint. The production endpoint will be provided when available.

See the API reference for query conventions and core entities. Addresses are indexed lowercase, so filter them with _ilike, and every numeric value is returned as a decimal string in raw on-chain units.

Read Conduit configuration

One query replaces most of the view calls above, and adds fee configuration, compliance mode, and yield.

GraphQL

query ConduitState($conduit: String!) {
  Conduit(where: { address: { _ilike: $conduit } }) {
    address
    name
    symbol
    asset
    assetSymbol
    assetDecimals
    assetPriceUSD
    supply
    enabled
    transferEnabled
    vehicle {
      address
      name
      vehicleType
    }
    feeManager {
      fees {
        feeType
        fee
        maxFee
      }
    }
    accountList {
      mode
      sanctionsEnabled
    }
    inceptionYield {
      netApr
      netApy
    }
  }
}

Query a user’s position

ConduitBalance holds the share balance of every holder of your Conduit’s token.

GraphQL

query UserPosition($conduit: String!, $owner: String!) {
  ConduitBalance(
    where: {
      conduit: { address: { _ilike: $conduit } }
      owner: { _ilike: $owner }
    }
  ) {
    value
    conduit {
      symbol
      assetSymbol
      assetDecimals
    }
  }
}

Track operation lifecycle

Each deposit or withdrawal is a ConduitQuery wrapping a STEAM Query. Read query.state for the current STEAM state, and query.input / query.output for the assets involved.

GraphQL

query UserOperations($conduit: String!, $owner: String!) {
  ConduitQuery(
    where: {
      conduit: { address: { _ilike: $conduit } }
      owner: { _ilike: $owner }
    }
    order_by: { event: { tx: { block: { number: desc } } } }
    limit: 20
  ) {
    id
    query {
      mode
      state
      input {
        address
        value
      }
      output {
        address
        value
      }
    }
    event {
      tx {
        hash
        block {
          number
          timestamp
        }
      }
    }
  }
}

To surface a “pending operations” badge, filter out the two terminal states:

GraphQL

query PendingOperations($conduit: String!) {
  ConduitQuery(
    where: {
      conduit: { address: { _ilike: $conduit } }
      _not: { query: { state: { _in: ["SETTLED", "REJECTED"] } } }
    }
    order_by: { event: { tx: { block: { number: asc } } } }
  ) {
    id
    owner
    query {
      mode
      state
    }
  }
}

Poll for updates

Fetch position data on a regular interval to keep your UI current.

TypeScript

const ENDPOINT = "https://graphql-enriched.staging.railnet.org/query";

async function getPosition(conduit: string, owner: string) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: `
        query ($conduit: String!, $owner: String!) {
          ConduitBalance(where: {
            conduit: { address: { _ilike: $conduit } }
            owner: { _ilike: $owner }
          }) {
            value
            conduit { symbol assetDecimals }
          }
        }
      `,
      variables: { conduit, owner },
    }),
  });

  const { data, errors } = await res.json();
  if (errors) throw new Error(errors.map((e: { message: string }) => e.message).join("; "));
  return data.ConduitBalance;
}

GraphQL errors come back with HTTP 200 in the errors array — check it explicitly instead of relying on the status code.

Next steps

Configure fees

Set up management, performance, deposit, and redeem fees for your Conduit.

Set up compliance

Configure allowlists, blocklists, and sanctions screening.

Conduit reference

Full technical reference for the Conduit contract.

Getting started

How-to guides

Reference

Integrate a Conduit

Prerequisites

Read Conduit state

Product info

Preview operations

Handle deposits

Handle withdrawals

Monitor with the Railnet API

Read Conduit configuration

Query a user’s position

Track operation lifecycle

Poll for updates

Next steps

Configure fees

Set up compliance

Conduit reference

​Prerequisites

​Read Conduit state

​Product info

​Balances and share price

​Preview operations

​Handle deposits

​Handle withdrawals

​Monitor with the Railnet API

​Read Conduit configuration

​Query a user’s position

​Track operation lifecycle

​Poll for updates

​Next steps

Configure fees

Set up compliance

Conduit reference

Prerequisites

Read Conduit state

Product info

Balances and share price

Preview operations

Handle deposits

Handle withdrawals

Monitor with the Railnet API

Read Conduit configuration

Query a user’s position

Track operation lifecycle

Poll for updates

Next steps