Known Issues / FAQ

This page documents known issues, workarounds, and frequently asked questions about Yaci DevKit.

Known Issues

PV11 Ogmios/Kupo Docker arm64 Compatibility

Current Behavior

The DevKit Docker image bundles those x86_64 Ogmios/Kupo binaries in both the linux/amd64 and linux/arm64 images as a temporary workaround.

• Linux x86_64 Docker hosts: Supported.
• Apple Silicon Docker Desktop: Expected to work through Docker Desktop's x86_64 emulation.
• Native Linux arm64 Docker hosts: May fail at runtime unless x86_64 binfmt/qemu emulation is configured on the host.
• Native CLI on macOS arm64: The default PV11 Ogmios/Kupo Linux x86_64 binaries cannot run directly. Use Docker, or set custom ogmios.url / kupo.url values when compatible native binaries are available.

Workaround

On native Linux arm64 hosts, run the DevKit Docker image as linux/amd64 or configure x86_64 emulation. For native CLI installs, use a compatible Ogmios/Kupo build when one becomes available by setting direct URLs in config/download.properties.

Yaci Store Tx Evaluator Mode (v0.12.0-beta5+)

Default Yaci Store transaction evaluation no longer requires Ogmios. If Ogmios is enabled and running when Yaci Store starts, DevKit automatically switches the evaluator mode to ogmios.

This means the temporary PV11 Ogmios/Kupo binary limitations do not block the default Yaci Store transaction evaluation path.

Check the active mode in the Yaci CLI startup output:

Yaci Store tx evaluator mode: scalus

Plutus V2 Script Data Hash Mismatch (v0.11.0-beta1+)

Background

In Yaci DevKit v0.11.0-beta1 and later, two configuration flags are commented out by default in config/node.properties:

# conwayHardForkAtEpoch=1
# shiftStartTimeBehind=true

These flags were previously used as a workaround to avoid extra cost model entries in Plutus V2 when the Conway hard fork happens at epoch 0. The workaround manipulated the devnet start time to move to epoch 1, avoiding 10 extra entries in the Plutus V2 cost model in protocol parameters.

Current Behavior With Default Configuration

• Plutus V3 transactions: Work perfectly ✅
• Regular transactions: Work perfectly ✅
• Plutus V2 with Cardano Client Lib: Works perfectly ✅
• Plutus V2 with Lucid Evolution: May fail with script data hash mismatch ❌

Root Cause

The default configuration works fine with Cardano Client Lib for all Plutus versions (including Plutus V2) because Cardano Client Lib fetches the cost model directly from the node to calculate script data hash for script transactions.

However, Plutus V2 scripts fail with Lucid Evolution using the default configuration. The issue appears to be related to hardcoded cost models that don't match the current protocol parameters when Conway hard fork occurs at epoch 0.

Workaround

If you need to use Plutus V2 with Lucid Evolution or other off-chain SDKs, enable the workaround flags:

1. Edit your node configuration file:

   • Docker distribution: config/node.properties
   • Zip distribution: config/node.properties

2. Uncomment and enable the flags:

   conwayHardForkAtEpoch=1
   shiftStartTimeBehind=true

3. Restart your devnet to apply the changes

More Information

For technical details about this issue, see: GitHub Issue #65 (opens in a new tab)

Getting Help

If you encounter issues not covered here:

1. Check the documentation: Verify you're following the correct setup for your distribution
2. Search existing issues: GitHub Issues (opens in a new tab)
3. Join the community: Discord (opens in a new tab)
4. Report a bug: Create new issue (opens in a new tab)