@cardano-ogmios/repl

Cardano Ogmios TypeScript Client Packages - REPL

A Node.js REPL which exposes the client behaviour in a terminal. Loaded into the context are the client builder functions, isolated query functions, and an instance of ChainSyncClient as chainSync with handlers to log the returned data. On exit the chainSync instance is shutdown. Optionally pass --host and --port arguments to specify the Ogmios server connection.

Quick Start

Download and run static package from the latest release for your environment.

Build From Source

See instructions in Workspace root

Example

ogmios> await currentEpoch()
256

ogmios> await ledgerTip()
{
  hash: '41364e89e44370a009f083ce9963261aabf6138db519b039012232bf40f187f8',
  slot: 25541023
}

ogmios> await currentProtocolParameters()
{
  poolDeposit: 500000000,
  protocolVersion: { minor: 0, major: 4 },
  minUtxoValue: 1000000,
  minFeeConstant: 155381,
  maxTxSize: 16384,
  minPoolCost: 340000000,
  maxBlockBodySize: 65536,
  extraEntropy: 'neutral',
  minFeeCoefficient: 44,
  poolInfluence: '3/10',
  maxBlockHeaderSize: 1100,
  stakeKeyDeposit: 2000000,
  decentralizationParameter: '1/50',
  desiredNumberOfPools: 500,
  poolRetirementEpochBound: 18,
  monetaryExpansion: '3/1000',
  treasuryExpansion: '1/5'
}

ogmios> chainSync.startSync()
ogmios> ROLL BACKWARD
Point
{
  hash: '21d0038f32a5e969caf110970a0657267e685c6492e0ce7d048ec601a29fcc2e',
  slot: 25551317
}
Tip
{
  hash: 'eb3725d8065683a5b760aabc158283ee580928e736d6f8dacc840c567236dedf',
  blockNo: 5527800,
  slot: 25551480
}

ogmios> ROLL FORWARD
Block
{
  mary: {
    body: [
      {
        body: {
          withdrawals: {},
          validityInterval: { invalidHereafter: 100000000, invalidBefore: null },
          inputs: [
            {
              index: 1,
              txId: '83e246ea8def447f71a981307e99e9455bad761e2817320319daed2b42a6bec2'
            }
          ],
          fee: 178233,
          certificates: [],
          outputs: [
            {
              value: { coins: 754010453, assets: {} },
              address: 'DdzFFzCqrhsrZ7RaLpeWen2bQCKyp2iPcAvE9HmB18VJh39dixDfGdXcxQRS9vUfU3jCv5qMrrTz62MpWXefmWouxDBmVeLyDjLNxHJi'
            }
          ],
          mint: { coins: 0, assets: {} },
          update: null
        },
        witness: {
          script: {},
          address: [
            {
              signature: 'vMpZfapEPMeA7JA7CAa5JYT8XrsYxw+3o/VseAmPG86xtNfB07mvbXV5ed8Pccmi3MgB0RIc4hJ2SaKmaYwyBg==',
...

Changelog

[5.5.0] - 2022-06-29

Added

• Added Vasil/Babbage support, including:
  • A new block type babbage with:
    • New (optional) transaction fields references, collateralReturn, totalCollateral;
    • New (optional) transaction output's fields datum and script;
  • A new plutus:v2 script language;
• New transaction error submission failures in the Babbage era:
  • mirNegativeTransfer: return when attempting to perform a negative MIR transfer from a reward pot to another;
  • totalCollateralMismatch: returned when totalCollateral is set but does not match what is actually computed by the ledger (i.e. sum of collateral inputs minus collateral return);
  • malformedReferenceScripts: returned when the script specified in an output isn't actually a well-formed Plutus script;
  • malformedScriptWitnesses, occurs when a script witness specified in the transaction does not properly deserialize to a Plutus script.
• New script evaluation failures in the Babbage era:
  • corruptCostModelForLanguage: An artifact from a distant past. This is unused but somehow still present in the ledger internal definitions. Should be removed eventually.
• New server evaluation failures:
  • NotEnoughSynced: Happens when attempting to evaluate execution units on a node that isn't enough synchronized. This is, if the node is still in an era prior to Alonzo, evaluation of execution units won't be possible.
  • CannotCreateEvaluationContext: Happens when the ledger fails to create an evaluation context from a given transaction. This is mostly due to the transaction being malformed (e.g. wrong redeemer pointer, missing UTxO).

<p align="right">See the <a href="https://ogmios.dev/api">📘 API reference</a> for more details.</p>

Changed

• Updated cardano-configurations to include the vasil-dev network and switch to cardano-world as a source instead of Hydra artifacts -- now being deprecated.

• Partially fixed an issue causing websocket connection to be terminated by the server when p2p is enabled on the underlying node. Ogmios now has a workaround which makes the issue less likely, but the real fix belongs in the upstream networking stack. See #230, #208.

• The missingRequiredScripts error now contains an extra field resolved that is a map of (pointer → script hash) that have been correctly resolved by said pointers.

• The introduction of the Babbage era comes with some minor (albeit possibly breaking) changes and deprecations:

  • ⚠️ datums, redeemerData and plutus:v1 scripts are no longer encoded as base64 strings, but are encoded as base16 strings. The data payload remains however identical. This change is meant for more compatibility across the API since those data-types can now also be submitted to the server when evaluating execution units for transactions. Using base64 for input data here is a bit awkward since most existing interfaces in the ecosystem favor base16;

  • ⚠️ When passing transaction outputs to the server (e.g. when providing an additional UTxO for script evaluation), datum hashes in output must now be specified as datumHash (instead of datum). However, the server does a best-effort for the sake of backward compatibility and should still work if provided with a valid hash under datum. However, after the Vasil hard-fork, it'll be possible to also pass inline-datums using datum, while datum hash digest are expected to be specified as datumHash. Said differently, existing applications relying on this functionality will keep working without a change on this release, but applications willing to make use of the new inline-datum functionality coming in Vasil must abide by the new notation;

  • ⚠️ Similarly, Alonzo transaction outputs will now contain a datumHash field, carrying the datum hash digest. However, they will also contain a datum field with the exact same value for backward compatibility reason. In Babbage however, transaction outputs will carry either datum or datumHash depending on the case; and datum will only contain inline datums;

  • ⚠️ The outputTooSmall errors from transaction submission will slightly change format for transactions submitted during the Babbage era. Instead of an array of outputs, it is an array of objects with output and minimumRequiredValue fields;

  • ⚠️ A slightly modified block header: leaderValue and nounce fields are gone and replaced by a single inputVrf field;

  • ⚠️ Few protocol parameters changes:

    • A new protocol parameter coinsPerUTxOByte comes to replace coinsPerUtxoWord with a slightly different semantic. coinsPerUTxOByte is meant to compute the minimum Lovelace requirement on transaction outputs, and is simply a coefficient in a linear function of the serialized (CBOR) output:

      minUTxOValue(output) =  |serialise(output)| * coinsPerUTxOByte
      

    • The decentralizationParameter no longer exists.<br/> The block production is forever decentralized :tada:!

    • The extraEntropy no longer exists.

<p align="right">See the <a href="https://ogmios.dev/api">📘 API reference</a> for more details.</p>

Removed

• UnknownInputs and UncomputableSlotArithmetic errors have been removed from the top-level possible cases of EvaluationFailure. Instead, those errors are now comprised in the CannotCreateEvaluationContext case.

• The corruptCostModelForLanguage error has been removed from the top-level possible cases of ScriptFailure. This one was effectively dead-code that couldn't be reached and was there for completeness. The code has now been removed upstream.

---

---