These are the steps that I think most Oracle implementations will comprise of. More steps could be added in and the validation that is done could be as complex or simple as the use-case demands. Although more steps could be added, I really doubt that there would be much use out of an Oracle that excluded any of the steps shown above.<\/p>\n
All the steps shown above only show the process from the side of the Oracle. There is a bit more going on so I think a good diagram will help us out here. It will also go on to present the example that I will use for this post.<\/p>\n Quite a few of these steps are generic ones that are going to be made in whatever Flow you put together. In this section, I will expand and show the code involved to implement the Flow shown in the diagram. Therefore it is worth having a reasonable look at it\u2026 I also spent a lot of time making that look nice, so please look at it!!<\/p>\n Oh, another point before I continue. I want to highlight how helpful putting together sequence diagrams to model Corda Flows is. It really highlights who is involved, how many network hops need to be made and how much work each participant does. Furthermore, they go a good way of explaining what is going on to people who are only interested in the higher level processes that you are architecting and\/or implementing.<\/p>\n As I mentioned before, some of the code here is generic code that you are likely to put into any Flow that you write. I have shown it all so there is no ambiguity around what is happening, but I will only expand on points that need to be highlighted as they contain code specific to interacting with an Oracle.<\/p>\n First, let\u2019s have a look at how the transaction is built:<\/p>\n There is not too much different here from how I would create a transaction that does not involve an Oracle. The only two differences are, retrieving the stock price from an external source (hidden inside the We will look closer at retrieving the external data separately.<\/p>\n Next up is collecting the recipients signature:<\/p>\n Collecting the counterparty\u2019s signature is not really an uncommon step of a Flow but what is done differently here is the use of Now that the recipient has signed the transaction, the Oracle needs to sign it:<\/p>\n Before sending the transaction to the Oracle, it is recommended to filter it to remove any information that is not needed by the Oracle. This prevents information that shouldn\u2019t be shared from being seen by the Oracle. Remember the Oracle is likely to be a node controlled by another organisation and is not a participant that you are attempting to share states and transactions with.<\/p>\n This outputs a All this code does is send the Finally, the Now that we have covered the client side of the code, we need to have a look into how the Oracle validates the transaction. Below is the contents of the Oracle code:<\/p>\n Some of the code that should be here is hidden in the Back to the I chose to complete the validation via throwing exceptions (along with error messages) which are then propagated to the requesting party. I think this makes it easier on to understand what has gone wrong so it can be handled properly, rather than just a straight \u201cfailed validation\u201d message. If the validation the Oracle is performing is complex, these error messages become even more valuable.<\/p>\n You should have seen the The code can be found below:<\/p>\n The Once the response is returned, it is converted into a In conclusion, you should use an Oracle when your CorDapp requires frequently changing external data that needs to be validated before the transaction can be committed. Just like data held within states, external data is extremely important, probably the most important, as it is likely to determine the main contents of a transaction. Therefore all participants must feel comfortable that the data is correct and hasn\u2019t just come out of thin air. Now for the main conclusion\u2026 In conclusion, you now have the knowledge to answer questions in the slack channel about Oracles or know where to send them if you can\u2019t!<\/p>\n The code used in this post can be found on my GitHub<\/a>.<\/p>\n If you found this post helpful, you can follow me on Twitter at @LankyDanDev<\/a> to keep up with my new posts.<\/p>\n![\"\"](\"https:\/\/www.javacodegeeks.com\/wp-content\/uploads\/2019\/01\/oracle-flow-chart.png\")
Client \/ Not the Oracle side<\/h2>\n
@InitiatingFlow\n@StartableByRPC\nclass GiveAwayStockFlow(\n private val symbol: String,\n private val amount: Long,\n private val recipient: String\n) :\n FlowLogic<SignedTransaction>() {\n\n @Suspendable\n override fun call(): SignedTransaction {\n val recipientParty = party()\n val oracle = oracle()\n val transaction =\n collectRecipientSignature(\n verifyAndSign(transaction(recipientParty, oracle)),\n recipientParty\n )\n val allSignedTransaction = collectOracleSignature(transaction, oracle)\n return subFlow(FinalityFlow(allSignedTransaction))\n }\n\n private fun party(): Party =\n serviceHub.networkMapCache.getPeerByLegalName(CordaX500Name.parse(recipient))\n ?: throw IllegalArgumentException(\"Party does not exist\")\n\n private fun oracle(): Party = serviceHub.networkMapCache.getPeerByLegalName(\n CordaX500Name(\n \"Oracle\",\n \"London\",\n \"GB\"\n )\n )\n ?: throw IllegalArgumentException(\"Oracle does not exist\")\n\n @Suspendable\n private fun collectRecipientSignature(\n transaction: SignedTransaction,\n party: Party\n ): SignedTransaction {\n val signature = subFlow(\n CollectSignatureFlow(\n transaction,\n initiateFlow(party),\n party.owningKey\n )\n ).single()\n return transaction.withAdditionalSignature(signature)\n }\n\n private fun verifyAndSign(transaction: TransactionBuilder): SignedTransaction {\n transaction.verify(serviceHub)\n return serviceHub.signInitialTransaction(transaction)\n }\n\n private fun transaction(recipientParty: Party, oracle: Party): TransactionBuilder =\n TransactionBuilder(notary()).apply {\n val priceOfStock = priceOfStock()\n addOutputState(state(recipientParty, priceOfStock), StockContract.CONTRACT_ID)\n addCommand(\n GiveAway(symbol, priceOfStock),\n listOf(recipientParty, oracle).map(Party::owningKey)\n )\n }\n\n private fun priceOfStock(): Double =\n serviceHub.cordaService(StockRetriever::class.java).getCurrent(symbol).price\n\n private fun state(party: Party, priceOfStock: Double): StockGiftState =\n StockGiftState(\n symbol = symbol,\n amount = amount,\n price = priceOfStock * amount,\n recipient = party\n )\n\n private fun notary(): Party = serviceHub.networkMapCache.notaryIdentities.first()\n\n @Suspendable\n private fun collectOracleSignature(\n transaction: SignedTransaction,\n oracle: Party\n ): SignedTransaction {\n val filtered = filteredTransaction(transaction, oracle)\n val signature = subFlow(CollectOracleStockPriceSignatureFlow(oracle, filtered))\n return transaction.withAdditionalSignature(signature)\n }\n \n private fun filteredTransaction(\n transaction: SignedTransaction,\n oracle: Party\n ): FilteredTransaction =\n transaction.buildFilteredTransaction(Predicate {\n when (it) {\n is Command<*> -> oracle.owningKey in it.signers && it.value is GiveAway\n else -> false\n }\n })\n}\n\n@InitiatedBy(GiveAwayStockFlow::class)\nclass SendMessageResponder(val session: FlowSession) : FlowLogic<Unit>() {\n @Suspendable\n override fun call() {\n subFlow(object : SignTransactionFlow(session) {\n override fun checkTransaction(stx: SignedTransaction) {}\n })\n }\n}<\/pre>\nprivate fun transaction(recipientParty: Party, oracle: Party): TransactionBuilder =\n TransactionBuilder(notary()).apply {\n val priceOfStock = priceOfStock()\n addOutputState(state(recipientParty, priceOfStock), StockContract.CONTRACT_ID)\n addCommand(\n GiveAway(symbol, priceOfStock),\n listOf(recipientParty, oracle).map(Party::owningKey)\n )\n }\n\nprivate fun priceOfStock(): Double =\n serviceHub.cordaService(StockRetriever::class.java).getCurrent(symbol).price<\/pre>\n<\/p>\nStockRetriever<\/code> service) and including the signature of the Oracle in the Command. These code additions line up with the reasons for using an Oracle. External data is included in the transaction and the Oracle needs to verify it is correct. To prove that the Oracle has deemed a transaction valid, we need its signature.<\/p>\n@Suspendable\nprivate fun collectRecipientSignature(\n transaction: SignedTransaction,\n party: Party\n): SignedTransaction {\n val signature = subFlow(\n CollectSignatureFlow(\n transaction,\n initiateFlow(party),\n party.owningKey\n )\n ).single()\n return transaction.withAdditionalSignature(signature)\n}<\/pre>\n<\/p>\nCollectSignatureFlow<\/code> rather than the CollectSignaturesFlow<\/code> which is normally used (noticed the \u201cs\u201d missing in the middle). That is due to requiring the Oracle\u2019s signature in the transaction. Calling the CollectSignaturesFlow<\/code> will go off to retrieve signatures from all required signers, including the Oracle. This treats the Oracle like a \u201cnormal\u201d participant. This is not what we want. Instead, we need to get the signature of the recipient and the Oracle individually and somewhat manually. The manual part is the use of transaction.withAdditionalSignature<\/code>.<\/p>\n@Suspendable\nprivate fun collectOracleSignature(\n transaction: SignedTransaction,\n oracle: Party\n): SignedTransaction {\n val filtered = filteredTransaction(transaction, oracle)\n val signature = subFlow(CollectOracleStockPriceSignatureFlow(oracle, filtered))\n return transaction.withAdditionalSignature(signature)\n}\n\nprivate fun filteredTransaction(\n transaction: SignedTransaction,\n oracle: Party\n): FilteredTransaction =\n transaction.buildFilteredTransaction(Predicate {\n when (it) {\n is Command<*> -> oracle.owningKey in it.signers && it.value is GiveAway\n else -> false\n }\n })<\/pre>\n<\/p>\nSignedTransaction<\/code> provides the buildFilteredTransaction<\/code> function that only includes objects that match the predicate passed in. In the example above it filters out everything but the GiveAway<\/code> (command I created) command which must also have the Oracle as a signer.<\/p>\nFilteredTransaction<\/code> which is passed to CollectOracleStockPriceSignatureFlow<\/code>:<\/p>\n@InitiatingFlow\nclass CollectOracleStockPriceSignatureFlow(\n private val oracle: Party,\n private val filtered: FilteredTransaction\n) : FlowLogic<TransactionSignature>() {\n\n @Suspendable\n override fun call(): TransactionSignature {\n val session = initiateFlow(oracle)\n return session.sendAndReceive<TransactionSignature>(filtered).unwrap { it }\n }\n}<\/pre>\n<\/p>\nFilteredTransaction<\/code> to the Oracle and awaits its signature. The code here could be put into the main Flow but it is quite nice to split code out when we can.<\/p>\nTransactionSignature<\/code> returned from the Oracle is added to the transaction in the same way the recipient\u2019s signature was added earlier. At this point, the transaction is ready to be committed as all the required signers have done their part.<\/p>\nOracle side<\/h2>\n
@InitiatedBy(CollectOracleStockPriceSignatureFlow::class)\nclass OracleStockPriceSignatureResponder(private val session: FlowSession) : FlowLogic<Unit>() {\n\n @Suspendable\n override fun call() {\n val transaction = session.receive<FilteredTransaction>().unwrap { it }\n\n val key = key()\n\n val isValid = transaction.checkWithFun { element: Any ->\n when {\n element is Command<*> && element.value is GiveAway -> {\n val command = element.value as GiveAway\n (key in element.signers).also {\n validateStockPrice(\n command.symbol,\n command.price\n )\n }\n }\n else -> false\n }\n }\n\n if (isValid) {\n session.send(serviceHub.createSignature(transaction, key))\n } else {\n throw InvalidStockPriceFlowException(\"Transaction: ${transaction.id} is invalid\")\n }\n }\n\n private fun key(): PublicKey = serviceHub.myInfo.legalIdentities.first().owningKey\n\n private fun validateStockPrice(symbol: String, price: Double) = try {\n serviceHub.cordaService(StockPriceValidator::class.java).validate(symbol, price)\n } catch (e: IllegalArgumentException) {\n throw InvalidStockPriceFlowException(e.message)\n }\n}<\/pre>\n<\/p>\nStockPriceValidator<\/code> which retrieves the external stock price and compares it to the one passed to the Oracle. It doesn\u2019t have much code and its validation is basic so I won\u2019t elaborate on it. As it is short, I might as well show it now:<\/p>\n@CordaService\nclass StockPriceValidator(private val serviceHub: AppServiceHub) :\n SingletonSerializeAsToken() {\n\n fun validate(symbol: String, price: Double) =\n serviceHub.cordaService(StockRetriever::class.java).getCurrent(symbol).let {\n require(price == it.price) { \"The price of $symbol is ${it.price}, not $price\" }\n }\n}<\/pre>\n<\/p>\nOracleStockPriceSignatureResponder<\/code>. Firstly, receive<\/code> is called to get the FilteredTransaction<\/code> that the client sent. It is then checked using its checkWithFun<\/code> function. This is a handy function that looks at each object and expects a Boolean<\/code> in return. Using this, the transaction is deemed valid if all it contains are commands of GiveAway<\/code> where the Oracle is the signer and most importantly checks that the external data contained in the command is correct. If you recall the code from earlier, the correct command and signers were passed in. The only remaining validation is on the external data. If that is all fine then the Oracle will accept the transaction and send its signature back to the client that requested it.<\/p>\nRetrieving external data<\/h3>\n
StockRetriever<\/code> class pop up twice now. It was used in both the requesting party and the Oracle. I have shared this code between both types of nodes (normal nodes and Oracles) but this might not be suitable for your own use-case. Furthermore, how you choose to retrieve your external data is up to you, I am just providing a possible solution.<\/p>\n@CordaService\nclass StockRetriever(serviceHub: AppServiceHub) :\n SingletonSerializeAsToken() {\n\n private val client = OkHttpClient()\n private val mapper = ObjectMapper()\n\n fun getCurrent(symbol: String): Stock {\n val response = client.newCall(request(symbol)).execute()\n return response.body()?.let {\n val json = it.string()\n require(json != \"Unknown symbol\") { \"Stock with symbol: $symbol does not exist\" }\n val tree = mapper.readTree(json)\n Stock(\n symbol = symbol,\n name = tree[\"companyName\"].asText(),\n primaryExchange = tree[\"primaryExchange\"].asText(),\n price = tree[\"latestPrice\"].asDouble()\n )\n } ?: throw IllegalArgumentException(\"No response\")\n }\n\n private fun request(symbol: String) =\n Request.Builder().url(\"https:\/\/api.iextrading.com\/1.0\/stock\/$symbol\/quote\").build()\n}<\/pre>\n<\/p>\nStockRetriever<\/code> is a nice little service that uses an OkHttpClient<\/code> (OkHttp<\/a>) to make a HTTP request to an API (provided by IEX Trading<\/a> using their Java library<\/a>) that returns stock information when a stock symbol is provided. You can use whatever client you want to make the HTTP request. I saw this one in an example CorDapp and have taken it for my own. Personally, I\u2019m too used to Spring so didn\u2019t really know any clients other than their RestTemplate<\/code>.<\/p>\nStock<\/code> object and passed back to the function\u2019s caller. That\u2019s all folks.<\/p>\nConclusion<\/h3>\n
\n
\nTo achieve this, an Oracle will also retrieve the external data and validate it against what the transaction says the data should be. At this point, the Oracle will either sign the transaction or throw an exception and deem it invalid. The implementation side of this is reasonably straightforward as there are not many steps that need to be taken. Retrieve the data, send a FilteredTransaction<\/code> to the Oracle containing the data where it will be validated. Yes, as you have read this post, you will know there is a bit more to it. But, for a basic Flow that is pretty much it. As I said somewhere near the start, how the Oracle does its validation can be as simple or complicated as required. Although, I think most will follow the same sort of process shown here.<\/p>\n