Marlowe Runtime Chain Index Architecture #180
Replies: 21 comments 80 replies
-
|
Interface summary: querySynchronizationStatus :: ClientM SynchronizationStatus
queryContractRoster :: ContractFilter -> ClientM ContractRoster
queryTransactions :: MonadIO m => Set TransactionId -> ClientM (Producer TransactionResult m ())
streamChainEvents :: MonadIO m => ClientM (Producer ChainEvent m ())
-- pure helpers
applyFilter :: ContractFilter -> ContractRoster -> ContractRosterNote that In this context, |
Beta Was this translation helpful? Give feedback.
-
|
Architecture diagram: graph
node((node socket))
consumer(("consumer(s)"))
db[(Database)]
config[(Config)]
qport((Query Port))
sport((Streaming Port))
subgraph Chain Index
epoch[Marlowe Epoch]
intersect[Intersection Points]
env[Environment]
sync[Chain Sync Client]
dbcon[DB connection]
status[Synchronization Status]
persist[Chain Persister]
sapi[Streaming API]
qapi[Query API]
qsock[Query Socket]
ssock[Streaming Socket]
end
sync-->node
config-->db
sync-->epoch
epoch-->env
qapi-->qsock
qapi-->status
qapi-->dbcon
qsock-->env
qsock--->qport
sapi-->ssock
sapi-->status
sapi-->sync
ssock-->env
ssock--->sport
status-->sync
persist-->status
sync-->intersect
intersect-->dbcon
persist-->dbcon
env-->config
dbcon-->env
dbcon-->db
persist-->sync
consumer-->qport
consumer-->sport
|
Beta Was this translation helpful? Give feedback.
-
|
I'm realizing that the consumer has no way to apply a contract filter to a contract roster with the information it contains. I think that |
Beta Was this translation helpful? Give feedback.
-
|
Interface draft v2: querySynchronizationStatus :: ClientM SynchronizationStatus
queryContractRoster :: ContractFilter -> ClientM ContractRoster
queryTransactions :: MonadIO m => Set TransactionId -> ClientM (Producer TransactionResult m ())
streamChainEvents :: MonadIO m => ContractFilter -> ClientM (Producer ChainEvent m ())The filter passed to |
Beta Was this translation helpful? Give feedback.
-
|
I'm also realizing that the querySynchronizationStatus :: ClientM SynchronizationStatus
queryTransactions :: ContractFilter -> ClientM (Producer Transaction m ())
streamChainEvents :: MonadIO m => ContractFilter -> ClientM (Producer ChainEvent m ())
data ChainEvent
= SynchronizationComplete
| RollForward ChainTip [Transaction]
| RollBackward ChainTipThis should dramatically simplify the API, and consequentially, the consumer. |
Beta Was this translation helpful? Give feedback.
-
|
Actually, this might not be a good idea to discard the idea after all - one benefit of the |
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra, Is the "Roster" mechanism something standard? Do you have a reference to an explanation of it? Maybe it would be good to add it to the discussion. I saw you wrote rationale for using it, but it would be useful to have some more information about what a Roster is, how does it work, etc |
Beta Was this translation helpful? Give feedback.
-
On solution could be that the client could, in principle create a filter that just contains the difference and make a separate query for the delta. So for example: The client wants all transactions that satisfy filter A |
Beta Was this translation helpful? Give feedback.
-
I am not sure, I think you can do intersection and union of bloom filters too. You cannot get each transaction in the bloom filter from the bloom filter, but then again, the client doesn't need to (I think). The only problems I see is that I am not sure how efficient it is to fetch everything that matches a bloom filter from a DB, and that it is probabilistic, so it may get you transactions you don't want. But it is not obvious to me that it wouldn't do the trick. I think using ranges would be better, in principle. |
Beta Was this translation helpful? Give feedback.
-
|
Regarding the discussion on bloom filters, I don't think it's a good use of focus at the current moment to be thinking about them, and I would caution about getting too fixated on them. We don't have more than a vague intuition they might be handy at the moment, so it doesn't seem like a productive topic to consider right now. Personally, I would start by just using raw SQL queries to filter data, database engines are extremely efficient for this. I also think there may be some confusion here as to terminology - you keep using the term "client" but I'm not sure if we're on the same page as to what that is referring to. When you say "client," what do you mean? |
Beta Was this translation helpful? Give feedback.
-
I think utilizing deltas in some way might be a good approach indeed. This relates closely to what I was mentioning the other day about incremental computing. This may be a good application for that, as we are talking about constructing a large data structure that changes in small ways over time. That's exactly what incremental computing is designed to deal with. Is there a way we could express this overall problem in terms of deltas, beyond just the filters? I guess delta filters are like program deltas, so that's a pretty important component to consider if we go down this route. |
Beta Was this translation helpful? Give feedback.
-
|
The main problem I see with using an incremental approach is that it would by necessity make the chain index stateful (in the sense that it would need to manage session state for each downstream consumer), which makes things again more complicated. |
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra, is it the case that the chain index has no Marlowe-specific knowledge aside from (1) the roster knows the opaque |
Beta Was this translation helpful? Give feedback.
-
@bwbush yes, that's the idea. It would get (1) from the transaction metadata and (2) from configuration |
Beta Was this translation helpful? Give feedback.
-
|
@bwbush I think option (1) is closest to what I'm proposing here and I think it is the best option for our purposes. Here are my reasons for not preferring the other two: Option (2): This would result in unnecessary data storage and data transfer from the chain index. I think we can afford to build some basic awareness of Marlowe into the chain index (to the degree stated in option (1)) because our goal is not to build a general-purpose chain-index. This gives us more license to embed some domain-specific concerns in it. Option (3): The fact that the PAB chain index was designed this way created problems with data consistency. If components that are downstream from the chain index are notified directly by the node and try to pull from the chain index, they may pull before the chain index has updated, and receive inconsistent results. This is why I think the index should be the source of this push information to the downstream components. I would actually classify the approach as suggested as "pull-init, push-update" - the initial data is pulled and then updates are received via push. This simply makes the push logic a lot easier to implement, as it doesn't need to "replay" or "catch up" the subscriber when it connects. |
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra, thanks for clarifying. I think this approach is fine. For security, we have to be careful not to trust the metadata. The best the metadata can do is to provide assertions or hints that would be cryptographically verified. Given that situation, I propose that we define |
Beta Was this translation helpful? Give feedback.
-
|
Ah, yeah that would be a good choice of identifier for contracts. I had in mind that we could use the |
Beta Was this translation helpful? Give feedback.
-
|
I can create two contracts with the same |
Beta Was this translation helpful? Give feedback.
-
Query/Filtering RequirementsTransaction InformationThe Marlowe-relevant information in
This information is essential for reconstructing the Query Patterns
References
|
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra, we'll need to verify that the above information is efficiently discoverable and extractable from the chain index. |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
In Functional Requirements 2.: "Given the synchronization status of the chain index is not Synchronized, the response should indicate that that the roster is possibly incomplete." This could be expressed with Phantom Types if that makes sense with how the roster is to be used. Then the compiler can keep us from mixing synchronized and unsynchronized rosters accidentally. And we can define operations |
Beta Was this translation helpful? Give feedback.
-
|
That's a possibility, however I don't know to what extend these two cases are actually mutually exclusive. And there is the added fact that we would need some kind of value-level witness to the phantom type in order to perform control flow and serialize it. |
Beta Was this translation helpful? Give feedback.
-
|
Although the synchronization state does alert clients that a roster might be incomplete, it doesn't provide any guarantee of completeness because there is always a possibility that contract transactions have occurred after the node's tip. Clients might decide to hold off on processing transactions until the chain index reports synchronization, but they always need to be ready to handle lack of synchronization with the block-producing nodes. |
Beta Was this translation helpful? Give feedback.
-
|
True. Maybe it would be better to design this under the assumption that we are always out of sync with the blockchain. That would also get rid of the distinction between the two states. The main benefit of the distinction is that we can do certain things more optimally when we are catching up to the tip, as the system is subjected to a different stress profile, but it shouldn't change the core business logic. |
Beta Was this translation helpful? Give feedback.
-
|
Yes, clients need to defensively assume that the information they act on is stale or rolled back. There's no avoiding that, but synchronization information gives the client a hint of how-up-to date the roster information is. |
Beta Was this translation helpful? Give feedback.
-
|
@palas @bwbush @dino-iog Can we explore a different idea for a minute? I would like to break out of the weeds of this one proposed solution and consider a different approach to clear our thinking a bit. What if our chain index consisted of:
In this sense, it would be quite similar to what we already have (the PAB implementation) with a couple of crucial differences:
|
Beta Was this translation helpful? Give feedback.
-
|
We also would need to consider what combinators the callbacks would support. We actually need to consider simultaneous occurence (because we work with a discrete representation of time), so there is really only one associative operator that covers combining them: alignCallbacks :: Callback a -> Callback b -> Callback (These a b) |
Beta Was this translation helpful? Give feedback.
-
|
The more I think about it, the more this seems like the best approach to take with the chain index. I don't yet have a very clear picture of how it will be consumed by downstream components, but this sort of machinery is flexible enough that it can be integrated relatively easily into various configurations. |
Beta Was this translation helpful? Give feedback.
-
|
That being said, I try to always assume I'm wrong, so maybe someone has a better suggestion? 😄 |
Beta Was this translation helpful? Give feedback.
-
|
Queries sounds nice in principle, but we would still need to address the synchronisation problem, and I am not sure callbacks will do the trick. Making queries when out of sync would give us inconsistent state (and we can be out of sync because of rollbacks and because of rollforwards that may happen between queries or before you subscribe, for example). It is the whole race condition nightmare, when we make the first query the state is one, when we make the second query the state is different... Suddenly the thing we are querying about doesn't exist anymore because there was a rollback. So I think we need a holistic approach to ensuring synchronisation at all times. We can still use queries, we would just need to include synchronisation info, and queries should fail if synchronisation info doesn't match. If synchronisation fails, then we need a procedure to get in sync. |
Beta Was this translation helpful? Give feedback.
-
|
@palas that is a good point. Let's look at a few options for dealing with this.
In terms of a procedure to get in sync, this would be outside the scope of the chain index component - the downstream components would need to handle this appropriately. But mostly, this would come down to reverting state in response to rollbacks. I'll start a new thread and work up something in a bit more detail for option 3, as I think it is an intriguing one that could solve this problem quite neatly. |
Beta Was this translation helpful? Give feedback.
-
|
This is a modification to the previous proposal which was motivated by @palas raising concerns about consistency / transactionality. The idea is that the downstream consumers of the chain index may need to aggregate data across multiple queries that should all come from a consistent view of the ledger. If the API of the chain index requires consumers to perform one call per query, we would need to do extra work to ensure the results are consistent with one another. Instead, what we could do is only expose a single API which accepts a composite query and runs them all against a consistent view of the data, returning the results in bulk. Here is an example of the proposed API: -- Previous proposal
queryUtxosAtAddress :: MonadChainIndex m => AddressAny -> m [TxOut]
queryTxOut :: MonadChainIndex m => TxOutRef -> m (Maybe TxOut)
...
-- New proposal
data ChainIndexQuery a where
GetUtxosAtAddress :: AddressAny -> ChainIndexQuery [TxOut]
GetTxOut :: TxOutRef -> ChainIndexQuery (Maybe TxOut)
...
GetProduct :: ChainIndexQuery a -> ChainIndexQuery b -> ChainIndexQuery (a, b)
queryChainIndex :: MonadChainIndex m => ChainIndexQuery a -> m aThis would take care of consistent queries, as it transforms multiple calls into a single call. It is also more efficient as it avoids multiple network round-trips. We would also need to consider synchronization between receiving a callback and performing a query as a follow-up. When awaiting an on-chain event, we will often want to perform one or more queries after we receive the callback. In the time between when the chain index calls us back and when it receives our follow-up query, there is a chance that the chain state has changed. This is especially true when the chain index is synchronizing. We can employ a similar technique to the previous one to bring the two together into the same call, but it requires a bit more work, because we need to consider how to use the data associated with event results as parameters for the queries. This will likely involve some complex type-level machinery and I want to get a sense of what people think of this approach before diving too deep into design here. |
Beta Was this translation helpful? Give feedback.
-
|
There isn't an |
Beta Was this translation helpful? Give feedback.
-
|
I've written |
Beta Was this translation helpful? Give feedback.
-
|
As in the product constructor? |
Beta Was this translation helpful? Give feedback.
-
|
Yes. |
Beta Was this translation helpful? Give feedback.
-
|
OK, that makes sense :) |
Beta Was this translation helpful? Give feedback.
-
|
One observation that I've made is that different components of the runtime require radically different query patterns. The history processor is predominantly push-driven, in that it needs to traverse transactions and receive notifications when the chain is updated. Transaction balancing, on the other hand, is entirely pull-driven, in that it needs to query existing UTxOs, but is unconcerned about updates to the chain. This is part of what makes designing this component so challenging - the design needs to satisfy both sets of requirements. |
Beta Was this translation helpful? Give feedback.
-
|
I'd like to consider yet another approach for this component that side-steps some of the complexity we've been considering by pushing it downstream. The approach would be to make the chain index basically act like a smart proxy for the chain sync protocol. NOTE If you are not already familiar with the chain sync protocol, I highly recommend you familiarize yourself with it first before reading this proposal. A good example of its use can be seen here The responsibilities of the chain index would be:
This would allow downstream components to be built as state machines that pull the next information in the chain they need and do with it as they see fit. Benefits of this approach include:
Drawbacks of the approach include:
Here is a draft of the protocol types, adapted from newtype FilteredChainSyncClient (query :: Type -> Type) point tip m a = FilteredChainSyncClient
{ runFilteredChainSyncClient :: m (ClientStIdle query point tip m a) }
data ClientStIdle query point tip m a where
SendMsgRequestNext
:: query result -- ^ a query that extracts a result from a block
-> ClientStNext result query point tip m a -- handler to run if the server responds immediately
-> m (ClientStNext result query point tip m a) -- handler to run if the server tells us to wait
-> ClientStIdle query point tip m a
SendMsgFindIntersect
:: [point]
-> ClientStIntersect query point tip m a
-> ClientStIdle query point tip m a
SendMsgDone
:: a
-> ClientStIdle query point tip m a
data ClientStNext result query point tip m a = ClientStNext
{ recvMsgRollForward :: result -- the result of the query
-> tip -- information about the tip of the chain
-> ChainSyncClient query point tip m a -- continuation client
, recvMsgRollBackward :: point -- rollbback point
-> tip -- information about the tip of the chain
-> ChainSyncClient query point tip m a -- continuation client
}
data ClientStIntersect query point tip m a = ClientStIntersect
{ recvMsgIntersectFound :: point -- found intersection point
-> tip -- information about the tip of the chain
-> ChainSyncClient query point tip m a -- continuation client
, recvMsgIntersectNotFound :: tip --- information about the tip of the chain
-> ChainSyncClient query point tip m a -- continuation client
}The main difference between this and the regular
The concrete argument for the To summarize, whereas the regular chain sync protocol allows you to define a state machine that handles each block in the chain sequentially, the filtered chain sync protocol allows you to define a similar state machine that handles a sequence of chain events which are at the discretion of the client to specify. |
Beta Was this translation helpful? Give feedback.
-
|
A limited example of a type that could be used for data Query a where
-- Get the next block header
GetBlockHeader :: Query BlockHeader
-- Get the transaction that consumes a UTxO (warning will never fulfill if the TxOutRef was previously consumed)
GetConsumingTx :: TxOutRef -> Query Tx
-- A query that is fultilled when the specified slot number has been reached or passed
AwaitSlotNoElapsed :: SlotNo -> Query ()
...
-- A query that is fulfilled when both constituent queries are fulfilled
GetBoth :: Query a -> Query b -> Query (a, b)
-- A query that is fulfilled when either constituend queries are fulfilled
GetEither :: Query a -> Query b -> Query (These a b)And example usage: getFirstBlockafterSlot slot = client
where
client = FilteredChainSyncClient do
SendMsgRequestNext
(GetBoth (AwaitSlotNoElapsed slot) GetBlockHeader)
next
(pure next)
next = ClientStNext
{ recvMsgRollForward = \(_, header) _ -> SendMsgDone header
, recvMsgRollBackward = \_ -> client -- ignore the rollback and try again. Should never be called anyway because `AwaitSlotNoElapsed` would never be invalidated. Maybe there is a way to capture this in the types with Void or something similar.
} |
Beta Was this translation helpful? Give feedback.
-
|
Another consideration is that we may be able to replace the Another way to think of queries is that they combine navigation with observation - they jump you to a different point in the chain and allow you to extract information from that point. In this light, the |
Beta Was this translation helpful? Give feedback.
-
|
Another possible semantics for the |
Beta Was this translation helpful? Give feedback.
-
|
I don't 100% understand this proposal. But am I right in thinking that this approach could be done without having a database for the chain-index at all? That would be a good reason for doing it this way. If the chain-index requires a database then we should be able to request information retroactively and efficiently from the chain-index, like the typical token you just discovered but already has history that you filtered out before. Can we do that efficiently with this approach? I understand we could with a query system. On the other hand, we can make the query system work in a consistent way without needing to make all the queries at the same time or ensuring that queries and the waiting happen all transactionally. We just need to have every call require the client to be synchronised, and having a way to catch-up and a way to "wait for something new to happen". Then we can just retry until we are caught up and then we block while "waiting for something to happen" (a bit like STM). And, as part of catching-up, clients would need to keep track of what information belongs to what block (in order to invalidate it if there is a rollback). But I understand clients would need to do that with this approach too. And I am guessing the only thing we need to "wait to happen" would be for UTXOs to get spent and for particular addresses to receive new UTXOs. Am I missing anything? So a query system shouldn't be complicated. And it would be stateless, which would just discard a whole type of errors and make debugging really easy. |
Beta Was this translation helpful? Give feedback.
-
No, the chain index would still require a database for this to work. The idea is that new clients can connect at any time and start traversing the blockchain, so the index would need to remember what it had received previously. There is no getting around this. When we receive data from the node, we don't know if we will need it in the future, so we have to store it for later use.
There is certainly no reason a call-and-response query protocol couldn't coexist with a synchronization protocol. Another option is to have the downstream components maintain private caches / data stores to optimize performance if and when they are needed. In the example you gave, the approach I would take is have a This could be made more efficient by adding bulk
Yup, that's another option and one which we've discussed as well. However, I think "requiring the client to be synchronized", "having a way to catch up" and a way to `"wait for something new to happen" will not be as straightforward as it sounds. This approach deals with all three of those concerns in a systematic way. Again, I think the main benefit of an approach like this is that it doesn't require us to be very inventive. These issues are ones that have been solved already by the Node API - the chain sync protocol was designed to handle these problems, and it does a very good job of doing so. By modelling our solution after it, we benefit from that existing knowledge and avoid having to come up with a novel solution to these problems.
Yes, that is true. They would need to do that no matter what approach we took. But this isn't complicated to do, as I discovered when implementing the initial POC.
I can't think of anything else personally, though there may be subtle variations of these events that it would be helpful to distinguish between. As for plain queries being stateless, they're not really stateless - they just delegate state management downstream. I can see cases where that makes the architecture less complex (when the state management is specific to the given downstream component), as well as cases where it makes it more complex (when the state management is common to all clients of the chain index). What I'm attempting to do here is pull only the common state management tasks (keeping track of the client's "current position" in the chain and detecting rollbacks) into the chain index. |
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra, which of the following are still under consideration in the design for the chain index?
|
Beta Was this translation helpful? Give feedback.
-
|
@bwbush I recommend you read my summary post below, it answers a number of these questions. |
Beta Was this translation helpful? Give feedback.
-
|
Checked items in the checklist as best as I could, some are only under consideration in a subset of the proposed options. |
Beta Was this translation helpful? Give feedback.
-
|
At this point, we've discussed four separate proposals, which I'd like to summarize here: 1. Roster SyncThe Chain Index pushes roster changes to clients. The Roster is a map that shows A) which Marlowe contracts exist and B) what transactions are associated with each Marlowe contract. The Roster only includes identifiers, both for contracts and transactions. The client can control which contracts the Roster contains via a The Chain Index also provides a bulk download API for transactions. When the client sees new transaction IDs in its Roster, it can use this API to download the transactions. Benefits
Drawbacks
2. Queries and CallbacksThe Chain Index exposes a set of queries and a set of event callbacks via its API. Clients use queries to load data from the blockchain and event callbacks to wait for new transactions. Clients receive a synchronization token from event callbacks. This token describes the client's "position" in the blockchain as of the event occurrence. The client then provides this token to subsequent queries and event requests. The Chain Index uses the token to give the client a consistent view of the blockchain. It also detects when the client needs to be informed of a rollback. Benefits
Drawbacks
3. Aggregated Queries and CallbacksThis option is a variation of the second one. Clients send batch queries to the Chain Index and receive batch results instead of threading a synchronization token through multiple queries. Continuation queries accompany event callbacks so the Chain index can ensure consistency between event results and query results. Benefits
Drawbacks
4. Extended Chain SyncDownstream clients communicate with the Chain Index via a modified version of the Chain Sync protocol. The Filtered Chain Sync protocol extends the base Chain Sync protocol by adding a
Benefits
Drawbacks
|
Beta Was this translation helpful? Give feedback.
-
|
Re 3, can you clarify "continuation query"? |
Beta Was this translation helpful? Give feedback.
-
|
Here is the framework I am using for evaluating these too:
|
Beta Was this translation helpful? Give feedback.
-
|
I'm more or less using those criteria too - in addition I'm careful considering flexibility of design. |
Beta Was this translation helpful? Give feedback.
-
|
Some notes:
|
Beta Was this translation helpful? Give feedback.
-
|
Recap of discussion from video call:
|
Beta Was this translation helpful? Give feedback.
-
|
I am going to write here a couple of what-if questions like we talked about, to understand better how the option 4 works, and to test it, and I will write them as separate replies to make it easier to discuss:
|
Beta Was this translation helpful? Give feedback.
-
|
Great question! This is also something that consumers of the The client is generally expected to start from the latest common intersection point (if the client has points that are beyond this point, they should be discarded as they are out of date anyway). The degenerate case of this is that the latest common intersection point is the genesis block, in which case the client would have to throw everything away and start from genesis. However, this rarely happens in practice thanks to the security parameter - which is the number of blocks past which you are guaranteed by the consensus protocol not to encounter a rollback. Blocks older than the security parameter can safely be assumed to be permanent - they are guaranteed to exist in the chain databases of all up-to-date and well-behaved nodes forevermore. If a client were to connect to a node, the security parameter defines the maximum reasonable distance before the previous tip to find a common intersection. In fact, if the node still says it can't find an intersection beyond there, the best thing the client can do is abort the connection and exit with an error, because the node is either not up-to-date, or it is playing against the rules, and should not be interacted with. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks, that is a relief. I didn't think of the security parameter, that ensures we don't traverse the whole chain |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
Good question. At least in the base chain sync protocol, the client does not have agency when awaiting a response to a There is probably an argument for interrupting or cancelling requests, though none come to mind immediately. One of the problems with this that I can see is that it involves forking the client's thread. In your question, you say the client is "waiting for the next event from the chain." You also say it concurrently "decides to follow a new UTxO or stop following the UTxO," implying that the client is running more than one thread. This could be supported by having the constructor for So my response to this question would be: is there a clear case where you anticipate this is necessary? If not, I would say it's probably not worth adding to the protocol, as it would incur a complexity penalty that wouldn't pay off in most cases. |
Beta Was this translation helpful? Give feedback.
-
|
I think probably every client will have at least something else that it wants to communicate with, often asynchronously, and if the communication is bidirectional then messages can arrive at any time and they typically have to be processed when they arrive, which requires another thread or some kind of |
Beta Was this translation helpful? Give feedback.
-
|
I see two separate concerns here:
Regarding graceful termination, we care about gracefully terminating the transport channel that we have opened and releasing resources. The monad used to run the client is the appropriate place to deal with this concern, not the protocol. The way to run a typed protocol is to provide a We can use Regarding cancelling an in-flight protocol message, this is explicitly impossible when using
The concept of agency is explicitly declared and enforced by the library. When the client sends a message (e.g. You could, however, design the protocol so that the client polls the server for a response. Then the client could maintain agency while awaiting the response and decide to cancel it. Something like this: newtype FilteredChainSyncClient (query :: Type -> Type) point tip m a = FilteredChainSyncClient
{ runFilteredChainSyncClient :: m (ClientStIdle query point tip m a) }
data ClientStIdle query point tip m a where
-- Send a query to the server
SendMsgQueryNext
:: query result -- ^ a query that extracts a result from a block
-> ClientStNext result query point tip m a -- handler to run if the server responds immediately
-> m (ClientStWait result query point tip m a) -- handler to run if the server tells us to wait
-> ClientStIdle query point tip m a
-- Terminate
SendMsgDone
:: a
-> ClientStIdle query point tip m a
data ClientStNext result query point tip m a = ClientStNext
{ recvMsgRollForward :: result -- the result of the query
-> tip -- information about the tip of the chain
-> FilteredChainSyncClient query point tip m a -- continuation client
, recvMsgRollBackward :: point -- rollbback point
-> tip -- information about the tip of the chain
-> FilteredChainSyncClient query point tip m a -- continuation client
}
data ClientStWait result query point tip m a where
-- Poll for the query result
SendMsgPollResult
:: ClientStNext result query point tip m a -- handler to run if a result is available
-> m (ClientStWait result query point tip m a) -- handler to run if the server tells us to wait
-> ClientStWait query point tip m a
-- Cancel the query and resume with a different client
SendMsgCancel
:: FilteredChainSyncClient result query point tip m a -- continuation client
-> ClientStWait query point tip m aThis could be a viable option to consider. Polling has advantages as well as disadvantages. |
Beta Was this translation helpful? Give feedback.
-
|
Marlowe Runtime Chain Index Entity-Relationship Diagram v1 erDiagram
Block ||--o{ Transaction : contains
Transaction ||--|{ TransactionInput : receives
Transaction ||--|{ TransactionOutput : produces
TransactionOutput ||--o{ AssetTransfer : transfers
TransactionOutput ||--o| TransactionInput : feeds
TransactionInput ||--o| PlutusScriptWitness : provides
AssetClass ||--o{ AssetTransfer : classifies
AssetClass ||--o{ AssetMint : classifies
Transaction ||--o{ AssetMint : mints
Block {
bytea headerHash PK
bigint slotNo "INDEX"
bigint blockNo
}
Transaction {
bytea id PK
bytea headerHash FK
bigint validityLowerBound "NULL"
bigint validityUpperBound "NULL"
bytea metadataKey1564 "NULL"
}
TransactionOutput {
uuid id PK
bytea transactionId FK
int index "INDEX"
bytea datum "NULL"
bytea address "INDEX"
bigint lovelace
}
TransactionInput {
uuid id PK
uuid transactionOutputId FK
bytea transactionId FK
}
PlutusScriptWitness {
uuid transactionInputId
bytea datum
bytea redeemer
}
AssetClass {
uuid id PK
bytea policyId FK
text name "INDEX"
}
AssetTransfer {
uuid transactionOutputId FK
uuid assetClassId FK
bigint quantity
}
AssetMint {
bytea transactionId FK
uuid assetClassId FK
bigint quantity
}
|
Beta Was this translation helpful? Give feedback.
-
|
Also, I don't think we need to precisely define secondary indices at this point. They can be added to support the query patterns and query optimization. |
Beta Was this translation helpful? Give feedback.
-
What would you suggest as a schema change for this then?
Confirming no action is needed on this point?
Correct, that is the idea.
We could, but can a PlutusScriptWitness contain a datum without a redeemer and vice-versa? My point is that
Is this correct? Cardano: AssetId, PolicyId; Plutus: AssetClass, CurrencySymbol. I agree on sticking with Cardano conventions.
As mentioned, this doesn't need to be captured here.
I can include this as a note. Though this is presumably enforced by the ledger rules already - so we shouldn't have to validate these invariants ourselves. We just accept whatever the node tells us.
I'll take a look, thanks.
Yup, that's the plan 🙂 |
Beta Was this translation helpful? Give feedback.
-
|
Marlowe Runtime Chain Index Entity-Relationship Diagram v2 erDiagram
Block ||--o{ Tx : contains
Tx ||--|{ TxIn : consumes
Tx ||--|{ TxOut : produces
TxOut ||--o{ AssetOut : transfers
TxOut ||--o| TxIn : feeds
Asset ||--o{ AssetOut : classifies
Asset ||--o{ AssetMint : classifies
Tx ||--o{ AssetMint : mints
Block {
serial id PK
bytea hash
bigint slotNo
bigint blockNo
}
Tx {
serial id PK
int blockId FK
bytea hash
bigint validityLowerBound "NULL"
bigint validityUpperBound "NULL"
bytea metadataKey1564 "NULL"
}
TxOut {
serial id PK
int txId FK
bigint index
bytea address
bigint lovelace
bytea datumHash "NULL"
bytea datumBytes "NULL"
}
TxIn {
serial id PK
int transactionOutputId FK
int txOutId FK
bytea redeemerDatumBytes "NULL"
}
Asset {
serial id PK
bytea policyId
text name
}
AssetOut {
serial id PK
int txOutId FK
int assetId FK
bigint quantity
}
AssetMint {
serial id PK
int txId FK
int assetId FK
bigint quantity
}
@bwbush does this address your comments? |
Beta Was this translation helpful? Give feedback.
-
|
@jhbertra Yes! Re 1, the latest diagram, with nullable Re 2, 3, 6, 7, 8, 9, 10, no changes advised. Re 4, as we discussed on slack, datum+redeemer in txin. Re 5, correct. |
Beta Was this translation helpful? Give feedback.
-
|
Marlowe Runtime Chain Index Entity-Relationship Diagram v3 (extracts Datum table) erDiagram
Block ||--o{ Tx : contains
Tx ||--|{ TxIn : consumes
Tx ||--|{ TxOut : produces
TxOut ||--o| Datum : contains
TxOut ||--o{ AssetOut : transfers
TxOut ||--o| TxIn : feeds
Asset ||--o{ AssetOut : classifies
Asset ||--o{ AssetMint : classifies
Tx ||--o{ AssetMint : mints
Block {
serial id PK
bytea hash
bigint slotNo
bigint blockNo
}
Tx {
serial id PK
int blockId FK
bytea hash
bigint validityLowerBound "NULL"
bigint validityUpperBound "NULL"
bytea metadataKey1564 "NULL"
}
TxOut {
serial id PK
int txId FK
int datumId FK "NULL"
bigint index
bytea address
bigint lovelace
}
Datum {
serial id PK
bytea hash
bytea bytes "NULL"
}
TxIn {
serial id PK
int transactionOutputId FK
int txOutId FK
bytea redeemerDatumBytes "NULL"
}
Asset {
serial id PK
bytea policyId
text name
}
AssetOut {
serial id PK
int txOutId FK
int assetId FK
bigint quantity
}
AssetMint {
serial id PK
int txId FK
int assetId FK
bigint quantity
}
|
Beta Was this translation helpful? Give feedback.
-
|
Filtered Chain Sync Protocol State Diagram v1 Note the omission of the stateDiagram-v2
[*] --> Idle
Idle --> Next : QueryNext
Idle --> [*] : Done
state Next {
[*] --> CanAwait
CanAwait --> MustAwait : AwaitReply
CanAwait --> [*] : RollForward
CanAwait --> [*] : RollBackward
MustAwait --> [*] : RollForward
MustAwait --> [*] : RollBackward
}
Next --> Idle : RollForward
Next --> Idle : RollBackward
|
Beta Was this translation helpful? Give feedback.
-
|
v2 stateDiagram-v2
[*] --> Init
Init --> Handshake : RequestHandshake
Handshake --> Idle : ConfirmHandshake
Handshake --> Fault : RejectHandshake
Idle --> Next : QueryNext
Idle --> Done : Done
Fault --> [*]
Done --> [*]
state Next {
[*] --> CanAwait
CanAwait --> MustAwait : Wait
CanAwait --> [*] : QueryRejected
CanAwait --> [*] : RollForward
CanAwait --> [*] : RollBackward
MustAwait --> [*] : RollForward
MustAwait --> [*] : RollBackward
}
Next --> Idle : QueryRejected
Next --> Idle : RollForward
Next --> Idle : RollBackward
|
Beta Was this translation helpful? Give feedback.
-
|
I propose that from now on, we refer to this component as the "Marlowe Chain Sync Engine" instead of the "Marlowe Chain Index." It is a more descriptive and accurate name for what we plan to build. |
Beta Was this translation helpful? Give feedback.
-
I've started this thread as a place to discuss the design for the chain index component of the runtime. I'm tentatively using the term "chain index" as opposed to "chain follower" or "chain sync client" because we may be using more than just the chain sync mini protocol, so "chain index" is more general.
Before we dive into the internals of the component, we should settle on an initial set of requirements that we feel comfortable with and describe the interface.
Here is a first draft of the specification for discussion:
High-level and Rationale
I'm beginning to think that we want the chain index to actually be a separate process. The reason for this is because of the potentially large volume of data it will store. It may make sense in some cases to deploy it on a different physical computer, or provide hosted instances for users who don't want to host either the Cardano Node or the database themselves. It certainly makes sense to segregate the chain index's database from other databases in the runtime for this reason.
The reason for introducing the intermediate contract roster structure is to support use cases in which only a subset of contracts are required with minimal data transfer, particularly in the streaming API. Sending only transaction IDs makes the message payload smaller, and enables the streaming API to send everything, simplifying its semantics. This also allows consumers to maintain a lightweight index that they can cheaply update and hold in memory, while actual transactions can be loaded lazily and optionally kept in a transient caching layer.
Definitions
Functional requirements
Synchronized, the response should indicate that that the roster is possibly incomplete.Synchronizing.Synchronized.Disconnected.Synchronized, the response should indicate that that the transaction set is possibly incomplete.Synchronizing, the stream should not send any events.Synchronized, the first event the stream should send should be aSynchronizationComplete.Disconnected, the connection request should be rejected.Disconnected, the connection should be severed.Synchronized, the first event the stream should send should be aSynchronizationComplete.Non-functional requirements
Usage notes
SynchronizationCompleteon the streaming connection, it should request the contract roster.Beta Was this translation helpful? Give feedback.
All reactions