Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,45 @@ pre: "<b>6. </b>"
math: true
---

### [Unreleased]

#### Added

- Stake pools returned by `queryLedgerState/stakePools`, and stake pools listed in the genesis configuration, can carry an optional `blsKey` with a `verificationKey` and a `proofOfPossession`. It is present only for pools that registered a BLS key (Dijkstra).

- Evaluation failures now report "Unexpected failure while building the script context: ..." when the ledger cannot build a script context for a transaction, and, in the Dijkstra era, "Couldn't find the script executed for ..." when a redeemer has no matching script.

- New transaction submission errors in the Dijkstra era:
- [`MissingRequiredGuards`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3169/MissingRequiredGuards) (`code=3169`) when the transaction or one of its sub-transactions requires guards that the top-level transaction does not list in its guards. `data.missingGuards` lists them.
- [`MalformedGuardDatums`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3170/MalformedGuardDatums) (`code=3170`) when a required top-level guard has the wrong datum: a guard that resolves to a Plutus script needs a datum, and a key hash or native script guard must not have one. `data.malformedGuards` lists the guards.
- [`PointerAddressInCollateralReturn`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3171/PointerAddressInCollateralReturn) (`code=3171`) when the collateral return output pays to a pointer address, which the Dijkstra era no longer allows. `data.collateralReturn` holds the output.
- [`InvalidBlsProofOfPossession`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3172/InvalidBlsProofOfPossession) (`code=3172`) when a stake pool registration carries a BLS key with an invalid proof of possession. The error gives the pool id and the key.
- [`AllInputsAreSpent`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3173/AllInputsAreSpent) (`code=3173`) when all inputs of the transaction are already spent, which usually means that the transaction is already on chain.
- [`WithdrawalsExceedingBalance`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3174/WithdrawalsExceedingBalance) (`code=3174`) when the total withdrawn from an account across the batch is more than the account balance at the start of the batch. For each account, the error gives the amount withdrawn and the balance.
- [`BalancesOutsideIntervals`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3175/BalancesOutsideIntervals) (`code=3175`) when an account balance does not satisfy an account balance interval that the transaction asserts. For each account, the error gives the balance and the interval, and `data.checkedAgainst` tells whether the check used the balances at the start of the batch or the balances seen by the transaction.

- New transaction submission error [`StakePoolVrfKeyAlreadyRegistered`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3176/StakePoolVrfKeyAlreadyRegistered) (`code=3176`) when a stake pool registration or update uses a VRF key that another stake pool already uses. `data.stakePool.id` gives the pool and `data.vrfVerificationKeyHash` the VRF key hash. Before, Ogmios reported this failure as [`UnknownStakePool`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3140/UnknownStakePool) (`code=3140`), which pointed to the wrong cause.

#### Changed

- **⚠️ BREAKING-CHANGE ⚠️**: Ogmios now requires node-to-client version 23, which cardano-node 10.7.1 and later offer. A cardano-node that does not offer it is refused at the handshake. Ogmios then stops with an error that lists the node-to-client versions the cardano-node offers and the versions Ogmios supports, instead of a raw handshake protocol error.

- The message of [`IncompleteWithdrawals`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3141/IncompleteWithdrawals) (`code=3141`) no longer says that every withdrawal must take the full account balance. That rule holds before the Dijkstra era, and in the Dijkstra era only for transactions in legacy mode.

- In the Dijkstra era, the evaluation error for a pointer address says whether it was found in an input ("Found inputs locked by a (legacy) pointer address") or in an output ("Found outputs to a (legacy) pointer address"). It always said outputs before.

- Bump dependencies to the latest cardano-ledger, ouroboros-consensus and ouroboros-network releases.

#### Fixed

- A failure while encoding the response of `submitTransaction` now returns a JSON-RPC internal error to the client. Before, the websocket connection was closed with no reply.

- In the Dijkstra era, `submitTransaction` now reports why the ledger rejected a transaction, with the same errors as in earlier eras. Before, a Dijkstra rejection closed the websocket connection with no reply. A failure inside a sub-transaction gets the same error as the same failure in a top-level transaction, and the error does not say which sub-transaction failed. A withdrawal from an account that is not registered gets [`UnknownCredential`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3146/UnknownCredential) (`code=3146`) with the credential of one such account, where earlier eras report [`IncompleteWithdrawals`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3141/IncompleteWithdrawals) (`code=3141`).

- [`RetirementTooLate`](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3142/RetirementTooLate) (`code=3142`) now reports the right epochs. Before, `data.currentEpoch` and `data.declaredEpoch` were swapped, and `data.firstInvalidEpoch` held the last valid retirement epoch instead of the first invalid one. The ledger also raises this error when the retirement epoch is not after the current epoch, and the message now says so.

- The JSON schema now lists `dijkstra` as an era name where Ogmios can return it, such as the `era` of a block and the eras in an era mismatch error. The schema also describes the `guard` clause of native scripts and the `guard` script purpose, which Dijkstra transactions can contain. The `guard` purpose appears in redeemer pointers and in the list of missing redeemers. Before, such responses did not match the schema. The schema also describes the `maxReferenceScriptsSizePerBlock` and `maxReferenceScriptsSizePerTransaction` protocol parameters of the Dijkstra era, and accepts the stake addresses that Ogmios uses as keys of the withdrawals in a `treasuryWithdrawals` governance action. Before, responses that contained them did not match the schema.

### [6.14.0] - 2025-10-16

#### Added
Expand Down
178 changes: 164 additions & 14 deletions clients/TypeScript/packages/schema/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,14 @@ export type Script = Native | Plutus;
/**
* A phase-1 monetary script. Timelocks constraints are only supported since Allegra.
*/
export type ScriptNative = ClauseSignature | ClauseAny | ClauseAll | ClauseSome | ClauseBefore | ClauseAfter;
export type ScriptNative =
| ClauseSignature
| ClauseGuard
| ClauseAny
| ClauseAll
| ClauseSome
| ClauseBefore
| ClauseAfter;
/**
* A Blake2b 28-byte hash digest, encoded in base16.
*/
Expand Down Expand Up @@ -124,6 +131,10 @@ export type MetadatumDetailedSchema =
* An Ed25519 verification key.
*/
export type VerificationKey = string;
/**
* An Ed25519-BIP32 Byron genesis delegate verification key with chain-code.
*/
export type ExtendedVerificationKey = string;
/**
* An EdDSA signature.
*/
Expand All @@ -141,10 +152,6 @@ export type AddressAttributes = string;
*/
export type RedeemerData = string;
export type BootstrapProtocolId = number;
/**
* An Ed25519-BIP32 Byron genesis delegate verification key with chain-code.
*/
export type ExtendedVerificationKey = string;
export type GenesisHash = "genesis";
export type VrfProof = string;
export type VrfOutput = string;
Expand Down Expand Up @@ -220,21 +227,30 @@ export type SubmitTransactionFailure =
| SubmitTransactionFailureReferenceScriptsTooLarge
| SubmitTransactionFailureUnknownVoters
| SubmitTransactionFailureEmptyTreasuryWithdrawal
| SubmitTransactionFailureMissingRequiredGuards
| SubmitTransactionFailureMalformedGuardDatums
| SubmitTransactionFailurePointerAddressInCollateralReturn
| SubmitTransactionFailureInvalidBlsProofOfPossession
| SubmitTransactionFailureAllInputsAreSpent
| SubmitTransactionFailureWithdrawalsExceedingBalance
| SubmitTransactionFailureBalancesOutsideIntervals
| SubmitTransactionFailureStakePoolVrfKeyAlreadyRegistered
| SubmitTransactionFailureUnexpectedMempoolError
| SubmitTransactionFailureUnrecognizedCertificateType;
export type Era = "byron" | "shelley" | "allegra" | "mary" | "alonzo" | "babbage" | "conway";
export type Era = "byron" | "shelley" | "allegra" | "mary" | "alonzo" | "babbage" | "conway" | "dijkstra";
export type ScriptPurpose =
| ScriptPurposeSpend
| ScriptPurposeMint
| ScriptPurposePublish
| ScriptPurposeWithdraw
| ScriptPurposePropose
| ScriptPurposeVote;
| ScriptPurposeVote
| ScriptPurposeGuard;
/**
* A Blake2b 28-byte hash digest, encoded in base16.
*/
export type PolicyId = string;
export type Language = "plutus:v1" | "plutus:v2" | "plutus:v3";
export type Language = "plutus:v1" | "plutus:v2" | "plutus:v3" | "plutus:v4";
export type Utxo = {
transaction: {
id: TransactionId;
Expand Down Expand Up @@ -659,6 +675,10 @@ export interface ClauseSignature {
clause: "signature";
from: DigestBlake2B224;
}
export interface ClauseGuard {
clause: "guard";
from: DigestBlake2B224;
}
export interface ClauseAny {
clause: "any";
from: ScriptNative[];
Expand All @@ -681,7 +701,7 @@ export interface ClauseAfter {
slot: Slot;
}
export interface Plutus {
language: "plutus:v1" | "plutus:v2" | "plutus:v3";
language: "plutus:v1" | "plutus:v2" | "plutus:v3" | "plutus:v4";
cbor: string;
}
/**
Expand Down Expand Up @@ -741,6 +761,7 @@ export interface StakePoolRegistration {
export interface StakePool {
id: StakePoolId;
vrfVerificationKeyHash: DigestBlake2B256;
blsKey?: BlsKey;
owners: DigestBlake2B224[];
cost: ValueAdaOnly;
margin: Ratio;
Expand All @@ -749,6 +770,13 @@ export interface StakePool {
metadata?: Anchor;
relays: Relay[];
}
/**
* A BLS12-381 (minimal-signature-size variant) verification key, along with a proof of possession of its signing key.
*/
export interface BlsKey {
verificationKey: string;
proofOfPossession: string;
}
export interface Anchor {
hash: DigestAny;
url: string;
Expand Down Expand Up @@ -897,6 +925,12 @@ export interface ProposedProtocolParameters {
maxReferenceScriptsSize?: {
bytes: UInt64;
};
maxReferenceScriptsSizePerBlock?: {
bytes: UInt64;
};
maxReferenceScriptsSizePerTransaction?: {
bytes: UInt64;
};
maxValueSize?: {
bytes: UInt64;
};
Expand Down Expand Up @@ -1115,7 +1149,7 @@ export interface MetadatumMap {
v: MetadatumDetailedSchema;
}
/**
* A signatory (EdDSA) for the transaction. The fields 'chainCode' and 'addressAttributes' are only present on bootstrap signatures (when spending from a Byron/Bootstrap address).
* A signatory (EdDSA) for the transaction. The fields 'chainCode' and 'addressAttributes' are only present on bootstrap signatures (when spending from a Byron/Bootstrap address). On Byron, the 'key' is an Ed25519-BIP32 XPub (key + chain-code) so the chain-code is carried inline; on Shelley and later it is a plain Ed25519 key with the chain-code in the separate 'chainCode' field.
*/
export interface Signatory {
key: VerificationKey | ExtendedVerificationKey;
Expand All @@ -1129,7 +1163,7 @@ export interface Redeemer {
validator: RedeemerPointer;
}
export interface RedeemerPointer {
purpose: "spend" | "mint" | "publish" | "withdraw" | "vote" | "propose";
purpose: "spend" | "mint" | "publish" | "withdraw" | "vote" | "propose" | "guard";
index: UInt64;
}
/**
Expand Down Expand Up @@ -1195,7 +1229,7 @@ export interface BootstrapVote {
}
export interface BlockPraos {
type: "praos";
era: "shelley" | "allegra" | "mary" | "alonzo" | "babbage" | "conway";
era: "shelley" | "allegra" | "mary" | "alonzo" | "babbage" | "conway" | "dijkstra";
id: DigestBlake2B256;
ancestor: DigestBlake2B256 | GenesisHash;
nonce?: CertifiedVrf;
Expand Down Expand Up @@ -1409,6 +1443,10 @@ export interface ScriptPurposeVote {
purpose: "vote";
issuer: VoterGenesisDelegate | VoterConstitutionalCommittee | VoterDelegateRepresentative | VoterStakePoolOperator;
}
export interface ScriptPurposeGuard {
purpose: "guard";
script: DigestBlake2B224;
}
/**
* Extraneous (non-required) redeemers found in the transaction. There are some redeemers that aren't pointing to any script. This could be because you've left some orphan redeemer behind, because they are pointing at the wrong thing or because you forgot to include their associated validator. Either way, the field 'data.extraneousRedeemers' lists the different orphan redeemer pointers.
*/
Expand Down Expand Up @@ -1745,7 +1783,7 @@ export interface SubmitTransactionFailureUnknownStakePool {
};
}
/**
* The transaction contains incomplete or invalid rewards withdrawals. When present, rewards withdrawals must consume rewards in full, there cannot be any leftover. You may also run into this error if the associatd stake credential is not registered. The field 'data.incompleteWithdrawals' contains a map of culprit withdrawals.
* Some withdrawals are incomplete or invalid. Before the Dijkstra era, and for a Dijkstra transaction in legacy mode, a withdrawal must take the full balance of its account. Before the Dijkstra era, this error also reports a withdrawal from a stake credential that is not registered. The field 'data.incompleteWithdrawals' maps each culprit reward account to the amount withdrawn.
*/
export interface SubmitTransactionFailureIncompleteWithdrawals {
code: 3141;
Expand All @@ -1755,7 +1793,7 @@ export interface SubmitTransactionFailureIncompleteWithdrawals {
};
}
/**
* A stake pool retirement certificate is trying to retire too late in the future. Indeed, there's a maximum delay for stake pool retirement, controlled by a protocol parameter. The field 'data.currentEpoch' indicates the current epoch known of the ledger, 'data.declaredEpoch' refers to the epoch declared in the retirement certificate and 'data.firstInvalidEpoch' is the first epoch considered invalid (too far) for retirement
* A stake pool retirement certificate lists an invalid retirement epoch. The epoch must be after the current epoch and before 'data.firstInvalidEpoch'. A protocol parameter sets the maximum delay for retirement. The field 'data.currentEpoch' is the current epoch, 'data.declaredEpoch' is the epoch listed in the certificate, and 'data.firstInvalidEpoch' is the first epoch too far in the future for retirement.
*/
export interface SubmitTransactionFailureRetirementTooLate {
code: 3142;
Expand Down Expand Up @@ -2050,6 +2088,111 @@ export interface SubmitTransactionFailureEmptyTreasuryWithdrawal {
code: 3168;
message: string;
}
/**
* Some guards required by the transaction or by its sub-transactions are missing from the top-level transaction. Any credential (key hash or script) listed as a required top-level guard must also appear in the 'guards' of the top-level transaction. The field 'data.missingGuards' lists the required credentials that are absent.
*/
export interface SubmitTransactionFailureMissingRequiredGuards {
code: 3169;
message: string;
data: {
missingGuards: {
from: CredentialOrigin;
credential: DigestBlake2B224;
}[];
};
}
/**
* Some required top-level guards have a malformed datum. A required guard that resolves to a Plutus script must come with a datum, whereas a guard that is a key hash or resolves to a native script must not have one. The field 'data.malformedGuards' lists the offending credentials.
*/
export interface SubmitTransactionFailureMalformedGuardDatums {
code: 3170;
message: string;
data: {
malformedGuards: {
from: CredentialOrigin;
credential: DigestBlake2B224;
}[];
};
}
/**
* The collateral return output is sent to a pointer address. Since the Dijkstra era, pointer addresses are no longer allowed in collateral return outputs. The field 'data.collateralReturn' contains the offending output.
*/
export interface SubmitTransactionFailurePointerAddressInCollateralReturn {
code: 3171;
message: string;
data: {
collateralReturn: TransactionOutput;
};
}
/**
* A stake pool registration carries a BLS key with an invalid proof of possession. The proof must show possession of the signing key that matches the BLS verification key. The field 'data.stakePool.id' indicates the stake pool, and 'data.blsKey' contains the key and proof found in the certificate.
*/
export interface SubmitTransactionFailureInvalidBlsProofOfPossession {
code: 3172;
message: string;
data: {
stakePool: {
id: StakePoolId;
};
blsKey: BlsKey;
};
}
/**
* All inputs of the transaction are already spent. This usually means that the transaction has already been included in the ledger, so there's no need to submit it again.
*/
export interface SubmitTransactionFailureAllInputsAreSpent {
code: 3173;
message: string;
}
/**
* Some withdrawals exceed the balance of their account. A withdrawal may take any amount up to the account balance, but the total withdrawn from an account across the whole batch (the top-level transaction and its sub-transactions) must not exceed the balance at the start of the batch. In legacy mode, only withdrawals from sub-transactions count towards that total. The field 'data.excessiveWithdrawals' lists, for each account, the total withdrawn and the balance at the start of the batch.
*/
export interface SubmitTransactionFailureWithdrawalsExceedingBalance {
code: 3174;
message: string;
data: {
excessiveWithdrawals: {
account: RewardAccount;
withdrawn: ValueAdaOnly;
balance: ValueAdaOnly;
}[];
};
}
/**
* Some account balances fall outside the intervals asserted by the transaction. An interval has an inclusive lower bound and an exclusive upper bound, or asserts an exact balance. The field 'data.checkedAgainst' tells which balances were checked: 'batchStart' for the balances at the start of the batch, or 'transaction' for the balances seen by the (sub-)transaction that asserts the interval. The field 'data.balancesOutsideIntervals' lists each account with its balance and the interval it doesn't satisfy.
*/
export interface SubmitTransactionFailureBalancesOutsideIntervals {
code: 3175;
message: string;
data: {
checkedAgainst: "batchStart" | "transaction";
balancesOutsideIntervals: {
account: RewardAccount;
balance: ValueAdaOnly;
interval:
| {
exact: ValueAdaOnly;
}
| {
lowerBound?: ValueAdaOnly;
upperBound?: ValueAdaOnly;
};
}[];
};
}
/**
* A stake pool registration or update uses a VRF key that another stake pool already uses. Each stake pool needs its own VRF key. The field 'data.stakePool.id' indicates the stake pool, and 'data.vrfVerificationKeyHash' is the hash of the VRF key in use.
*/
export interface SubmitTransactionFailureStakePoolVrfKeyAlreadyRegistered {
code: 3176;
message: string;
data: {
stakePool: {
id: StakePoolId;
};
vrfVerificationKeyHash: DigestBlake2B256;
};
}
/**
* A transaction was rejected due to custom rules that prevented it from entering the mempool. A justification is given as 'data.error'.
*/
Expand Down Expand Up @@ -2797,6 +2940,12 @@ export interface ProtocolParameters {
maxReferenceScriptsSize?: {
bytes: UInt64;
};
maxReferenceScriptsSizePerBlock?: {
bytes: UInt64;
};
maxReferenceScriptsSizePerTransaction?: {
bytes: UInt64;
};
stakePoolVotingThresholds?: StakePoolVotingThresholds;
constitutionalCommitteeMinSize?: UInt16;
constitutionalCommitteeMaxTermLength?: UInt64;
Expand Down Expand Up @@ -2949,6 +3098,7 @@ export interface QueryLedgerStateStakePoolsResponse {
export interface StakePoolView {
id: StakePoolId;
vrfVerificationKeyHash?: DigestBlake2B256;
blsKey?: BlsKey;
owners?: DigestBlake2B224[];
cost?: ValueAdaOnly;
margin?: Ratio;
Expand Down
Loading
Loading