Off-Chain Architecture (TypeScript)

This bridge service connects Substrate oracle data to Cardano smart contracts, facilitating multi-sig deployments and continuous feed updates.

Prerequisites

• Node.js: v18 or higher
• Yarn: v4 (uses Berry/Zero-install)
• Cardano Infrastructure:
  • Ogmios (HTTP): For Cardano node interaction.
  • Kupo: For UTxO indexing.
• Substrate Node: Access to the Charli3 Substrate chain RPC.

Local Development Setup

1. Install Dependencies:

   yarn install

2. Environment Configuration: Copy the example environment file:

   cp .env.example .env

   Key variables to set:

   • SUBSTRATE_RPC_URL: Substrate node RPC endpoint.
   • OGMIOS_HTTP_URL: Ogmios HTTP API.
   • KUPO_URL: Kupo HTTP API.
   • CARDANO_NETWORK: mainnet, preprod, or preview.
   • ORACLE_PLATFORM_SIGNING_KEY: Your Ed25519 private key (hex).

3. Application Configuration: This project uses two primary YAML configs:

   • auth-config.yaml: For Platform Authorization NFT (multisig settings).
   • oracle-config.yml: For Oracle deployment (nodes, pairs, fees).

   cp oracle-config.yml.example oracle-config.yml
   # Generate auth template if needed
   yarn dev auth generate-config

Core Workflows

1. Authorization NFT (Platform Setup)

Before deploying an oracle, you need a Platform Authorization NFT.

# Build the minting transaction
yarn dev auth build --config auth-config.yaml
 
# Sign it (collect signatures if multisig)
yarn dev auth sign --config auth-config.yaml --tx-file tx_auth_mint.json
 
# Submit to Cardano
yarn dev auth submit --config auth-config.yaml --tx-file tx_auth_mint.json

2. Oracle Deployment

Deploys the oracle smart contracts and initializes channels/pairs.

# Build deployment (creates reference scripts and data UTxOs)
yarn dev oracle deploy --config oracle-config.yml
 
# Sign and Submit (same flow as auth)
yarn dev oracle sign --config oracle-config.yml --tx-file tx_oracle_data.json
yarn dev oracle submit --config oracle-config.yml --tx-file tx_oracle_data.json

Deployment info is saved to oracle-deployment.json.

3. Oracle Feed Service (Bridge)

This is the long-running process that monitors Substrate and updates Cardano.

# Run the continuous bridge loop
yarn dev oracle feed --config oracle-config.yml

CLI Reference

The main entry point is yarn dev (or node dist/cli.js after building).

Troubleshooting

• UTxO Issues: If the deployment fails due to lack of UTxOs, ensure your wallet has at least 2-3 UTxOs with sufficient ADA (10+ ADA recommended for fees and reference scripts).
• Substrate Connection: Ensure SUBSTRATE_RPC_URL is reachable. The bridge loop will wait if the connection is lost.
• Kupo Sync: Ensure Kupo is fully synced, otherwise the bridge won’t find the deployed contract UTxOs.