feat(core-api): hasTransactionFinality(): boolean on connector API

[petermetz]

Is your feature request related to a problem? Please describe.

Need a way to ask the connector at runtime whether its ledger has transaction finality guaranteed or not.

Describe the solution you'd like

Depends on #355

A method on the connector that returns a boolean, something like:

For ledgers that only support one consensus algorithm (public permissionless ledgers mostly I guess?)

public hasTransactionFinality(): Promise<boolean> {
    return false;
}

In cases where the ledger has configurable consensus the function's return value would depend on which one is configured for the current ledger instance.

public async hasTransactionFinality(): Promise<boolean> {
    const algorithmsWithTxFinality = ["IBFT2", "RAFT", "Other_Algo"];
    const algorithmsWithOutTxFinality = ["Proof_of_Work", "Some_Other_Algo"];
    const currentAlgo = await this.getConsensusAlgorithm();
    const unrecognizedAlgorithm = !algorithmsWithTxFinality.includes(currentAlgo) &&  !algorithmsWithOutTxFinality.includes(currentAlgo);
    if (unrecognizedAlgorithm) { // fail fast when algorithm is unrecognized
        throw new Error(`Unrecognized consensus algorithm: ${currentAlgo}`);
    } else {
        return algorithmsWithTxFinality.includes(currentAlgo);
    }
}

To avoid the problem of a ledger introducing a new consensus algorithm that does support TX finality and then us returning incorrect results based on that, we must check the currentAlgo for presence in both lists and throw if it isn't present in either one of them. This guarantees that we fail fast instead of non-deterministic behavior.

Describe alternatives you've considered

Another way of going about this would be to have the consensus algorithms defined in the consortium definition which would provide us with the means to have the consensus algorithm locked down. Not sure if we should do this because the problem is regarding enforcement: Big mistakes can still happen if a consortium member accidentally changes the consensus algorithm of their own ledger without seeking an update in the consensus definition first.

cc: @sfuji822 @takeutak @jonathan-m-hamilton

[jscode017]

I would like to work on this, but seems that issue #355 is closed?

[petermetz]

@jscode017 Yeah, #355 was a dependency of this so that being closed is good news not the other way around (e.g. meaning that this can now be worked on).
Did you want to go with the proposed algorithm in the issue description or had something else in mind? Just asking because I'm not a 100% sure that what I laid out in the description actually works/makes sense (it was just some late-night pseudo code).

TLDR: Feel free to work on this and drop by the pair programming session on weekday mornings PST if you have any questions about build setup/code/etc.

[jscode017]

I would first try to go with the proposed algorithm. If I have something else come to mind, maybe I would discuss on the chat?

[petermetz]

@jscode017 Sure thing, that works and thank you for taking this up!

[jscode017]

@petermetz
I've written something like:

ConsensusAlgorithmFamiliesWithOutTxFinality":{
                "description":"",
                "type": "string",
                "enum": [
                    "org.hyperledger.cactus.consensusalgorithm.PROOF_OF_WORK"
                ],
                "x-enum-varnames": ["WORK"]
},

in the cactus-core-api/src/main/json/openapi.json
to generate

export enum ConsensusAlgorithmFamiliesWithOutTxFinality {
    WORK = 'org.hyperledger.cactus.consensusalgorithm.PROOF_OF_WORK'
}

But I'm thinking this may not be a good approach,
would want to generate an array with default value, i.e: ConsensusAlgorithmFamiliesWithOutTxFinality=[ConsensusAlgorithmFamily.Work]
, but could not find a way to do this.
Are there any way to do this?

[petermetz]

@jscode017 Thanks for teaching me about "x-enum-varnames" I was looking for something like that in the OpenAPI specs just the other day to be able to control the enum variable names!

Back on-topic: Yeah you might not need to declare an array at all, because of the way you structured your enum you could just check later in code if an algorithm name is part of that enum, the same way they are advising at Check if value exists in enum in TypeScript

That array thing would only be needed if you had one enum containing both the algos with and without tx finality IMO (that was my initial idea, but I like yours better).
The way you did it is probably better because then the information is encoded in the enum at design time (when you are typingthe openapi.json file).