Skip to content

Commit 292fd33

Browse files
ross-spencerChristian-MK
ross-spencer
and
Christian-MK
authored
creation of Archived section for historical versions eg v0 (#15)
* creation of Archived section for historical versions eg v0 * seperation of content into policies & resources per feeedback * header correction * archived-resources, context for policies * Update archived-resources.md addition of incidents repo links * markdown corrections and fixed links * fixed utxo-1 link * addition of start/end date context * Update roadmap.md Remove old timeline graphic * Add files via upload upload updated roadmap graphic * removal of COOP and replace with Orcfax Protocol * roadmap update * correction of headings * second attempt to fix headings * Rollback docusaurus dependency * removal of coop & replaced with orcfax protocol * removal of coop references * addition of policy IDs and contextual info * addition of policy ids and context * fix markdown * stubborn lists --------- Co-authored-by: Christian-MK <[email protected]>
1 parent a3ee0fb commit 292fd33

File tree

2 files changed

+356
-0
lines changed

2 files changed

+356
-0
lines changed

‎docs/developer-manual/archived-resources.md

+266
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
---
2+
id: archived resources
3+
sidebar_position: 4
4+
slug: /archived-resources
5+
---
6+
7+
# Archived Orcfax resources
8+
9+
This section contains links, instructions, and commentary relating to Orcfax
10+
solution versions and/or components **which are no longer in operation**. This
11+
information has been left as an educational resource and as a testament to the
12+
development journey of the Orcfax oracle solution.
13+
14+
## v0
15+
16+
The v0 solution offered by Orcfax on Cardano mainnet was released in 2023 and
17+
utilized the Cardano Open Oracle Protocol ([COOP][coop-1]) to format and publish
18+
information on-chain. The protocol constituted a set of technical guidelines
19+
that specified a process, and format, for the publication and consumption of
20+
off-chain data by smart contracts on the Cardano blockchain.
21+
22+
The Orcfax team developed the Cardano Open Oracle Protocol as a Catalyst funded
23+
research project that aimed to maximize the [eUTXO][utxo-1] model and leveraged design
24+
principles, [CIP-31][cip-31], and [CIP-32][cip-32] to prioritize a
25+
cost-sensitive, post-Vasil native method for publishing secure, signed, datums
26+
on-chain for Reference Input consumption by Cardano dApps.
27+
28+
The initial version of COOP was developed in collaboration with [MLabs][mlabs-1]
29+
consultancy. The guidelines and specification in COOP are free, open-source, and
30+
can be implemented by any other project seeking to develop their own Cardano
31+
oracle feeds.
32+
33+
Shortly after this version was released, IOG discontinued support for both
34+
the Plutus Application Backend (PAB) and Plutus-Chain-Index. Both were critical
35+
components in the COOP v0 stack. Aware of the discontinued support, the Orcfax
36+
team partnered with technical consultants through MLabs to replace the
37+
components. Unfortunately, the plutus-chain-index component failed before a
38+
replacement could be rolled-out.
39+
40+
And so v0 was suspended in May of 2024.
41+
42+
More information pertaining to this failure can be found in both the
43+
[public announcement][medium-1] and in the subsequent incident
44+
[report][incident-35].
45+
46+
Additionally, users and developers may find it informative to review the entire
47+
v0 [Incidents][incidentRepo-1] repository as it contains many critical learnings
48+
from the implementation of v0.
49+
50+
[coop-1]: https://github.com/mlabs-haskell/cardano-open-oracle-protocol/
51+
[utxo-1]: https://docs.cardano.org/learn/eutxo-explainer/
52+
[cip-31]: https://docs.cardano.org/about-cardano/evolution/upgrades/vasil/#reference-inputs-cip-31
53+
[cip-32]: https://docs.cardano.org/about-cardano/evolution/upgrades/vasil/#inline-datums-cip-32
54+
[mlabs-1]: https://mlabs.city/
55+
[medium-1]: https://medium.com/@orcfax/orcfax-feed-suspension-and-protocol-upgrade-a45709dafb56
56+
[incident-35]: https://github.com/orcfax/Incidents/issues/38
57+
[incidentRepo-1]: https://github.com/orcfax/Incidents
58+
59+
### v0 Mainnet
60+
61+
Policy ID:
62+
63+
```text
64+
2cccc05192920ff1eb02bcfa7bb2a1fc5352ce58391d7ba3c66a555b
65+
```
66+
67+
On [cexplorer][cexplorer-1].
68+
69+
[cexplorer-1]: https://cexplorer.io/policy/2cccc05192920ff1eb02bcfa7bb2a1fc5352ce58391d7ba3c66a555b
70+
71+
Smart contract address:
72+
73+
```text
74+
addr1w8tcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgq7lqh2
75+
```
76+
77+
On [cexplorer][cexplorer-2].
78+
79+
[cexplorer-2]: https://cexplorer.io/address/addr1w8tcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgq7lqh2
80+
81+
### v0 Preprod
82+
83+
Policy ID:
84+
85+
```text
86+
104d51dd927761bf5d50d32e1ede4b2cff477d475fe32f4f780a4b21
87+
```
88+
89+
On [preprod.cexplorer][preprod-1].
90+
91+
[preprod-1]: https://preprod.cexplorer.io/policy/104d51dd927761bf5d50d32e1ede4b2cff477d475fe32f4f780a4b21/mint
92+
93+
Smart contract address:
94+
95+
```text
96+
addr_test1wrtcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgmktuc0
97+
```
98+
99+
On [preprod.cexplorer][preprod-2].
100+
101+
[preprod-2]: https://preprod.cexplorer.io/address/addr_test1wrtcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgmktuc0
102+
103+
### In use
104+
105+
Minting policy identifiers were critical as fact statements were to be verified
106+
as having come from a known source. These identifiers also provided the ability
107+
to filter all of the UTxO at a given smart contract address and to filter out
108+
those sent by others to the same address.
109+
110+
Users were required to use the following information to identify the latest
111+
facts published.
112+
113+
* Minting policy ID.
114+
* Datum format, including:
115+
* Most recent (`ValueReference -> PropertyValue[1] -> value)`, i.e. the
116+
largest POSIX timestamp compared to other fact statement datum,
117+
* Feed name, e.g. "ADA-USD".
118+
119+
> Note: Users on preprod will find a volume of test data that was not ever
120+
> retired as Orcfax previously used this space as a testing sandbox.
121+
122+
In this model, unconsumed reference inputs were those still available for smart
123+
contracts to use on-chain. Spending a UTxO with a reference input would render
124+
it unusable in a smart contract (though the data was still visible in the
125+
historical transaction). This process of consuming reference inputs is also
126+
referred to as _garbage collection_ or the _retiring_ of fact statements.
127+
128+
At the time of this version, Orcfax committed to a mainnet policy whereby two
129+
unspent fact UTxO would remain on-chain at all times in order to provide
130+
continuous datum coverage.
131+
132+
> Note: maintaining at least two datum on-chain gave smart contracts (and their
133+
> developers) access to the most current datum and the datum before that for
134+
> inspection. The POSIX timestamps denoting a valid-from and valid-through
135+
> period could be inspected to ensure that they were still within a valid
136+
> window.
137+
138+
For more information about the use of reference inputs and the inline datum
139+
utilized in COOP v0, see the relevant COOP [design document][coop-design-1].
140+
141+
[coop-design-1]: https://github.com/mlabs-haskell/cardano-open-oracle-protocol/blob/9e9c9aedba84d32e424b1dd116b4734e1a42f3bc/coop-docs/00-design.md#cardano-features-enabling-oracles
142+
143+
### v0 datum structure
144+
145+
All fact statements were structured as [JSON-LD](https://json-ld.org/) objects
146+
before being serialized into the Concise Binary Object Representation
147+
([CBOR](https://cbor.io/)) used in Cardano transactions.
148+
149+
![Fact Statement](/img/2023-09-30--Orcfax--fact-statement.jpg)
150+
151+
#### v0 JSON-LD schema
152+
153+
The Orcfax V0 datum was translated to on-chain CBOR from the following JSON
154+
schema (example given is from Sep 28, 2023):
155+
156+
```json
157+
{
158+
"@context": "https://schema.org",
159+
"type": "PropertyValue",
160+
"name": "ADA-USD|USD-ADA",
161+
"value": [0.249495, 4.008096354636367],
162+
"valueReference": [
163+
{
164+
"@type": "PropertyValue",
165+
"name": "validFrom",
166+
"value": 1695939870811
167+
},
168+
{
169+
"@type": "PropertyValue",
170+
"name": "validThrough",
171+
"value": 1695943470811
172+
}
173+
],
174+
"identifier": {
175+
"propertyID": "Arkly Identifier",
176+
"type": "PropertyValue",
177+
"value": "urn:orcfax:4ae10640-10b9-4c23-af1d-c4a9dbd8938d"
178+
},
179+
"_:contentSignature": "40330ff2597c399ddaaab6c1dbaab52173ef82bf7f08d3ca84585ab5e76429a0"
180+
}
181+
```
182+
183+
### Reading v0 datum on-chain
184+
185+
Orcfax fact statement datum were readable on-chain as Cardano
186+
[Reference Inputs](https://github.com/perturbing/vasil-tests/blob/main/reference-inputs-cip-31.md).
187+
188+
To have read the `ADA-USD|USD-ADA` Mainnet feed, users were encouraged to check
189+
the latest transaction issued by the
190+
[feed smart contract](https://cexplorer.io/address/addr1w8tcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgq7lqh2/tx#data).
191+
192+
### Reading v0 datum off-chain
193+
194+
The [PyCardano](https://pycardano.readthedocs.io/) SDK provided convenient
195+
helper functions for converting on-chain CBOR.
196+
197+
The Orcfax team created an open-source PyCardano
198+
[demo script](https://github.com/orcfax/datum-demo/tree/main#readme) to assist
199+
users in reading and parsing the on-chain Orcfax datum.
200+
201+
This script converted the Cardano transaction's CBOR serialization to human and
202+
machine-readable JSON while simultaneously logging various details about the
203+
Datum as it went.
204+
205+
It's very easy to customize the configuration options of this script to match
206+
the requirements of another dApp.
207+
208+
This resource was made freely available under an open-source Apache
209+
v2.0 license so that users could test, integrate, and extend their own solutions
210+
by integrating Orcfax fact statement feeds.
211+
212+
<!-- markdownlint-disable MD013 -->
213+
214+
_demo script output:_
215+
216+
```text
217+
2023-09-28T16:24:13Z INFO :: read_datum.py:264:read_datum() :: entering this script...
218+
2023-09-28T16:24:13Z INFO :: read_datum.py:265:read_datum() :: oracle smart contract: addr_test1wrtcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgmktuc0
219+
2023-09-28T16:24:15Z INFO :: read_datum.py:226:get_latest_utxo() :: inspecting '862' UTxOs
220+
2023-09-28T16:24:15Z WARNING :: read_datum.py:254:get_latest_utxo() :: '7.00' hours since datum was published (1695943470811)
221+
2023-09-28T16:24:15Z INFO :: read_datum.py:191:validate_utxo() :: inspecting the utxo for valid auth tokens
222+
2023-09-28T16:24:15Z INFO :: read_datum.py:217:validate_utxo() :: the utxo is valid, it contains the correct auth token
223+
2023-09-28T16:24:15Z INFO :: read_datum.py:79:display_utxo() :: (input) transaction id: 078d548b0ed91b95164d0baaf2b486161e06aab84483d99ed01a2180090ab0f3
224+
2023-09-28T16:24:15Z INFO :: read_datum.py:80:display_utxo() :: (output) transaction addr: addr_test1wrtcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgmktuc0
225+
2023-09-28T16:24:15Z INFO :: read_datum.py:81:display_utxo() :: (output) datum cbor:
226+
227+
590207d8799fa74840636f6e746578745268747470733a2f2f736368656d612e6f7267525f3a636f6e74656e745369676e61747572655840343033333066663235393763333939646461616162366331646261616235323137336566383262663766303864336361383435383561623565373634323961304a6964656e746966696572a34a70726f706572747949445041726b6c79204964656e74696669657244747970654d50726f706572747956616c75654576616c7565582f75726e3a6f72636661783a34616531303634302d313062392d346332332d616631642d633461396462643839333864446e616d654f4144412d5553447c5553442d41444144747970654d50726f706572747956616c75654576616c75659fd87c9f1a0003ce971bfffffffffffffffaffd87c9f1b000e3d57a771924e1bfffffffffffffff1ffff4e76616c75655265666572656e63659fa34540747970654d50726f706572747956616c7565446e616d654976616c696446726f6d4576616c75651b0000018adde4c05ba34540747970654d50726f706572747956616c7565446e616d654c76616c69645468726f7567684576616c75651b0000018ade1baedbff5820303443413030303148424559394b4b34343950314345513850483744544a5954d87a9f1b0000018ade1baedbff581c90b121aa6b689200adf7ed115040a96375d2b68e23633d6864c53a91ff
228+
229+
2023-09-28T16:24:15Z INFO :: read_datum.py:84:display_utxo() :: (output) Tx cost: 3.42214 ADA
230+
2023-09-28T16:24:15Z INFO :: read_datum.py:151:decode_utxo() ::
231+
232+
{
233+
"@context": "https://schema.org",
234+
"type": "PropertyValue",
235+
"name": "ADA-USD|USD-ADA",
236+
"value": [
237+
0.249495,
238+
4.008096354636367
239+
],
240+
"valueReference": [
241+
{
242+
"@type": "PropertyValue",
243+
"name": "validFrom",
244+
"value": 1695939870811
245+
},
246+
{
247+
"@type": "PropertyValue",
248+
"name": "validThrough",
249+
"value": 1695943470811
250+
}
251+
],
252+
"identifier": {
253+
"propertyID": "Arkly Identifier",
254+
"type": "PropertyValue",
255+
"value": "urn:orcfax:4ae10640-10b9-4c23-af1d-c4a9dbd8938d"
256+
},
257+
"_:contentSignature": "40330ff2597c399ddaaab6c1dbaab52173ef82bf7f08d3ca84585ab5e76429a0"
258+
}
259+
260+
2023-09-28T16:24:15Z INFO :: read_datum.py:152:decode_utxo() :: oracle datum identifier (internal): b'04CA0001HBEY9KK449P1CEQ8PH7DTJYT'
261+
2023-09-28T16:24:15Z INFO :: read_datum.py:157:decode_utxo() :: oracle datum timestamp: 2023-09-28T23:24:30Z (1695943470811)
262+
2023-09-28T16:24:15Z INFO :: read_datum.py:170:pretty_log_value() :: ADA-USD: 0.249495
263+
2023-09-28T16:24:15Z INFO :: read_datum.py:170:pretty_log_value() :: USD-ADA: 4.008096354636367
264+
```
265+
266+
<!-- markdownlint-restore -->

‎docs/developer-manual/policies.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
id: orcfax policies
3+
sidebar_position: 3
4+
slug: /policies
5+
---
6+
7+
# Orcfax policies
8+
9+
A list of Orcfax oracle policy IDs.
10+
11+
## Current policies
12+
13+
### v1
14+
15+
The upgraded v1 protocol is currently under development. While mainnet details
16+
are unavailable, integrators can find details regarding Preprod and Preview
17+
below.
18+
19+
#### v1 Mainnet
20+
21+
Policy ID: TBA
22+
23+
* Smart contract address: TBA
24+
25+
* Date of appearance: TBA
26+
* Slot Number: TBA
27+
* block: TBA
28+
* Explorer view: TBA
29+
30+
#### v1 Preprod
31+
32+
Policy ID: TBA
33+
34+
#### v1 Preview
35+
36+
Fact Statement Pointer:
37+
```e06133fc651dccdaedf8f9cb50e5a94fc5d38fd97a7cae9cc81016893dd86f8d```
38+
39+
* [Explorer view](https://preview.cexplorer.io/tx/e06133fc651dccdaedf8f9cb50e5a94fc5d38fd97a7cae9cc81016893dd86f8d)
40+
41+
Policy ID:
42+
```900d528f3c1864a1376db1afc065c9b293a2235f39b00a67455a6724```
43+
44+
```text
45+
NB
46+
The Preview Testnet policy is not yet static and will move as the smart
47+
contracts involved in Orcfax publish are improved on the way to mainnet. Because
48+
Orcfax is currently under active development, we reserve the ability to update
49+
the protocol’s publishing logic.
50+
```
51+
52+
## Legacy policies
53+
54+
### v0
55+
56+
<!-- V0 used a legacy datum format, see [archived resources][archive-1] for how to
57+
interpret the data published on-chian using this version.
58+
59+
[archive-1]: archived-resources#in-use
60+
Branch must first be merged
61+
-->
62+
63+
#### v0 Mainnet
64+
65+
Policy ID:
66+
```2cccc05192920ff1eb02bcfa7bb2a1fc5352ce58391d7ba3c66a555b```
67+
68+
Smart contract address:
69+
```addr1w8tcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgq7lqh2```
70+
71+
* Date of appearance: 28.9.2023
72+
* Slot Number: 104,327,334
73+
* block: `81394cd019daf9d2575b04d902735cbfe5d8b14e33242f6810664b911fe81798`
74+
* [Explorer view](https://cexplorer.io/tx/51f35f76b06923344e8bfb5743b6ab8e65e2afdce8ef578ccf979cb0ffcb1bab)
75+
76+
* Date of deprecation: 14.5.2024
77+
* Slot Number: 124,114,551
78+
* block: ```c508478bbb1b63070c45e6bd6d813eef060915ebf0ccfa325e1fe194a03f664f```
79+
* [Explorer view](https://cexplorer.io/tx/63e6f7b3f1ca150213be192f09ef14701336962d555ac0eeac49650e08d2a61c)
80+
81+
* Arweave wallet: ```Our6d4__QbpvIWDz2GTbnKdyunVcrLSA2OfFxJpXdzQ```
82+
* [Explorer view](https://arscan.io/address/Our6d4__QbpvIWDz2GTbnKdyunVcrLSA2OfFxJpXdzQ)
83+
84+
#### v0 Preprod
85+
86+
Policy ID:
87+
```104d51dd927761bf5d50d32e1ede4b2cff477d475fe32f4f780a4b21```
88+
89+
Smart contract address:
90+
```addr_test1wrtcecfy7np3sduzn99ffuv8qx2sa8v977l0xql8ca7lgkgmktuc0```

0 commit comments

Comments
 (0)