Skip to content

user-guide.md

Latest commit

 

History

History
204 lines (121 loc) · 8.39 KB

user-guide.md

File metadata and controls

204 lines (121 loc) · 8.39 KB

User Guide

This guide walks through using the Orcfax On-Demand portal to fetch and publish oracle price feed data on Cardano.

What You Need

  • A Cardano wallet browser extension — Eternl, Nami, or Lace are supported
  • Some ADA in your wallet — at least 15 ADA recommended (10 ADA minimum deposit + 2 ADA channel reserve + network fees)
  • The wallet must be set to the same network as the app (Preview for testing, Mainnet for production)

Step 1: Connect Your Wallet

When you first open the app at /app, an account setup dialog appears.

  1. Click Connect Wallet to see available wallets
  2. Select your wallet from the list — a connection prompt will appear in your wallet extension
  3. Approve the connection

The app stores your wallet name in localStorage for automatic reconnection on future visits. You can disconnect at any time from the sidebar.

Network mismatch

If your wallet is on a different network than the app (e.g., wallet on Mainnet, app on Preview), the app will show a warning. Switch your wallet's network to match, or use the network selector in the sidebar if available.

Step 2: Open a Payment Channel

After connecting your wallet, the dialog moves to channel setup.

What is a payment channel?

A payment channel lets you pay for API requests without a blockchain transaction for each one. You lock ADA in a smart contract (escrow), then authorize payments off-chain using signed messages called IOUs. This is fast (instant) and cheap (no transaction fees per request).

Opening a new channel

  1. Review the pricing:
    • Price update: 0.01 ADA per request
    • On-chain publish: 5 ADA per request
  2. Set your initial deposit (minimum 10 ADA). The total transaction will be:
    • Your deposit + 2 ADA channel reserve + ~0.2 ADA network fee
  3. Optionally customize the channel tag (a random identifier is generated by default)
  4. Check the Terms of Service checkbox
  5. Click Open Channel
  6. Approve the transaction in your wallet extension

After submission, the app will:

  • Wait for blockchain confirmation (~20-60 seconds)
  • Sync the channel with the backend
  • Show you the key download screen

Transaction costs

The 2 ADA "channel reserve" is the minimum ADA that must remain in the UTxO (a Cardano protocol requirement). It's returned to you when you close the channel. It's not a fee.

Step 3: Download Your Key File

After the channel opens, the app generates an Ed25519 signing keypair and prompts you to download it.

This key file is critical. It contains the private key used to sign payment authorizations (IOUs). Without it, you cannot use the channel or close it through the standard flow.

  1. Review the security warning — you are responsible for keeping this key safe
  2. Click Download Key
  3. Store the file securely (treat it like a password)
  4. Optionally check Remember this key on this device to cache it in the browser for easier reconnection

The key file is a JSON document (orcfax-on-demand-key format) containing:

  • Ed25519 private and public keys (hex + bech32)
  • Public key hash
  • Channel binding (tag, keytag)
  • Metadata (network, provider, ToS version/hash)

Step 4: Fetch Price Data

Once setup is complete, the main application shows a feeds table listing all available price pairs (e.g., ADA-USD, ADA-DJED).

Updating a single feed

Click the Update button next to a feed to fetch its latest price. This:

  • Signs an IOU for 0.01 ADA (10,000 lovelace)
  • Sends the request to the server with your credential
  • Returns the latest price from the Orcfax validator
  • Stores the result in your browser's IndexedDB for local history

Updating multiple feeds

Use the checkboxes to select multiple feeds, then click the batch update button to fetch them all in a single request.

Viewing price history

Click the expand arrow on a feed row to see its price history. History is stored locally in your browser — it persists across sessions but is device-specific.

Step 5: Publish On-Chain

Publishing writes a price datum to the Cardano blockchain. This costs 5 ADA per request.

Click the Publish button next to a feed. The published datum includes:

  • The price value (numerator/denominator)
  • A timestamp
  • A transaction ID and archive source reference

Published prices show an indicator in the feeds table.

Managing Your Channel

The sidebar shows your channel status: stage, balance, and costs.

Checking your balance

Your available balance is: locked ADA - accumulated costs - 2 ADA reserve.

For example, if you deposited 10 ADA and have used 0.05 ADA in requests:

  • Locked: 12 ADA (10 deposit + 2 reserve)
  • Available: 7.95 ADA (12 - 0.05 - 2 reserve - ~2 Cardano min-UTxO)

Adding funds

If your balance runs low, click Add Funds in the sidebar. Enter an amount, approve the wallet transaction, and wait for confirmation. The new ADA is added to your existing channel.

Closing and withdrawing

When you're done using the service:

  1. Click Close Channel — this starts a 1-hour settlement window
  2. During this window, the provider may settle (claim the amount you authorized via IOUs)
  3. After settlement, click Withdraw to reclaim your remaining ADA
  4. If the provider doesn't settle within the window, click Expire to reclaim all your ADA

The sidebar tracks the close deadline and shows the appropriate action button.

What happens during the settlement window?

After you close the channel, the app automatically (fire-and-forget) triggers the provider to settle. The provider submits a settlement transaction claiming the ADA you authorized. This is normal — you agreed to pay this amount through your IOUs.

If the provider settles: you get back lockedAmount - settledAmount. If the provider doesn't settle: you get back everything (via Expire).

Restoring a Session

If you return to the app on the same device, the wallet auto-reconnects and you may be able to restore your channel.

From browser cache

If you previously checked "Remember this key on this device", click Unlock in the returning user tab. No file upload needed.

From key file

If you didn't cache the key (or you're on a different device):

  1. Go to the Returning User tab in the account setup dialog
  2. Upload your key file
  3. The app restores your key, syncs the channel, and you're back in business

What if I lost my key file?

If you didn't cache the key and lost the file, you cannot use the channel through the portal. However, your funds are safe on-chain — the Subbit smart contract ensures you can always recover your ADA after the close period. You would need to interact with the smart contract directly using the wallet that opened the channel.

Terms of Service

The Terms of Service define pricing, channel parameters, and legal clauses. You accept them when opening a channel.

ToS updates

If the ToS is updated while you have an open channel:

  • A grace period (7 days) begins, during which previous pricing still applies
  • A dialog will notify you of the changes
  • You can: accept the new terms, or close your channel and withdraw before the grace period ends
  • After the grace period, new terms apply automatically

Programmatic API

If you're using the REST API, ToS updates are communicated via response headers. See the API reference for details.

Troubleshooting

"Insufficient funds" error when fetching a price

Your channel balance is too low. Add funds via the sidebar, or close and open a new channel with a larger deposit.

Wallet popup doesn't appear

Some wallets need to be unlocked before they can respond to connection/signing requests. Open your wallet extension, enter your password if needed, then try again.

"Network mismatch" warning

Your wallet is set to a different Cardano network than the app. Switch your wallet to match (Preview or Mainnet).

Channel shows "closing" but no deadline

The close transaction may still be confirming. The app polls the blockchain every 30 seconds. Wait a minute and the deadline should appear.

"Channel not found" on restore

This can happen if:

  • The channel was already expired/ended in another session
  • SubbitMan doesn't have the channel in its records
  • There's a network mismatch (the channel was opened on a different network)

Check that your wallet and the app are on the same network, and that you're using the correct key file.