search

api3dao / old-api3-docs

Documentation for the API3 Project
https://docs.api3.org/
MIT License
57 stars 29 forks source link

dAPI BBP: best practices page #970

Closed wkande closed 1 year ago

wkande commented 2 years ago

dAPI best practices page for dApp developers. There needs to be significant research on this. A list of "things" we wish to express would be a good start. There is already another issue #959 that fits in this realm but will most likely be its own page.

wkande commented 2 years ago

@Umersin61 Can you provide any "sites" (that you had mentioned before) that might show subject matter as an example. Are there any items you feel should be addressed?

jgcogsystematictrading commented 2 years ago

Things I wanted to add but did not have all the available info. were:

umersin61 commented 2 years ago

@umersin61 Can you provide any "sites" (that you had mentioned before) that might show subject matter as an example. Are there any items you feel should be addressed?

Sorry this flew by me but it's essentially things that people should be aware of while using dAPIs/Beacons. for reference other projects have similar things here: https://docs.chain.link/docs/using-chainlink-reference-contracts/#monitoring-data-feeds https://docs.chain.link/docs/selecting-data-feeds/

wkande commented 2 years ago

@umersin61 @bbenligiray - I looked through the Chainlink docs for best practices. I can see some good topics. They do however go on-and-on-and-on. It just never ends. Seems to be overwhelming. But some people do like that sort of thing.

Such a complex model as Chainlink's makes for a difficult task with regards to the new dAPIs Best Practices page. In our last few core development team meetings the concern was that less documentation was better while having some movement to more guides. The insight document from Ben and Tamera suggests that guides and more documentation is what developers want. However they only spoke to 11 developers and they have experience with Chainlink. Not sure that is meaningful with developers new to oracles. You just a feeling of complexity in the Chainlink docs.

I will start by keeping the dAPIs best practices page simple and only address simple concepts that get developers up and running quickly, and instill some confidence in them.

  1. ease of use, readDataFeedWithDapiName(\_dapiName)
  2. explain how to monitor feeds they might wish use, we do not have tools for this at this time
  3. give them confidence in the dAPI data security model

Can anyone think of others (dAPIs related) to add to the list above. They are easy enough to add. Each will be short section in keeping with, less content and get to the point. If anyone does not agree speak up please. And we can add new sections to the page if you come across any ideas in the future. I just do not want to jump developers all over the place like Chainlink.

Back to guides, guides are good and so is a great Getting Started section which is independent to our projects (Airnode, dAPIs, OID, e.t.c.). I can see any best practices page or pages moving into the Getting started section of the next generation of the docs. I am hoping to have an early preview of this "concept" in a week or so. Nothing big but it should help with discussion around the insights document and suggestions from the core development team.

wkande commented 2 years ago

@jgcogsystematictrading

Things I wanted to add but did not have all the available info. were:

  • A minimum # of RPC providers that data providers running Beacons must use, and if the core tech team runs their own node for each blockchain as backup.

API3 does not run Airnodes, only API provider owns and operate Airnodes. As such API3 cannot intercept and change data. API providers determine the number of RPC provider used. See chains.providers

  • The procedures in place that prevent the actor performing the Airnode/Airkeeper integration for providers from compromising it.

secrets.env is owned and maintained by the Airnode operator. An API provider self describes an apiKey (in secrets.env) that is used by their Airnode to access their APIs. If that info gets out the API provider has an issue. Maybe that can be mentioned. Here I think the actor would have to be a member of the core dev team if they had access to secrets.env. Or can you think of a different scenario?

  • Information on the dAPI monitoring software and measures.

Right now the dAPP developer needs to access the values on-chain from an off-chain piece of code. The same way I believe Chainlink recommends.

jgcogsystematictrading commented 2 years ago

@jgcogsystematictrading

Things I wanted to add but did not have all the available info. were:

  • A minimum # of RPC providers that data providers running Beacons must use, and if the core tech team runs their own node for each blockchain as backup.

API3 does not run Airnodes, only API provider owns and operate Airnodes. As such API3 cannot intercept and change data. API providers determine the number of RPC provider used. See chains.providers

  • The procedures in place that prevent the actor performing the Airnode/Airkeeper integration for providers from compromising it.

secrets.env is owned and maintained by the Airnode operator. An API provider self describes an apiKey (in secrets.env) that is used by their Airnode to access their APIs. If that info gets out the API provider has an issue. Maybe that can be mentioned. Here I think the actor would have to be a member of the core dev team if they had access to secrets.env. Or can you think of a different scenario?

  • Information on the dAPI monitoring software and measures.

Right now the dAPP developer needs to access the values on-chain from an off-chain piece of code. The same way I believe Chainlink recommends.

When I say node I was referring to actual blockchain nodes, not Airnodes. The core tech team does operate some of these for certain chains. I know that RPCs are parameters for providers but we have had rules in place in the past for minimum #s of these they must use to support beacons.

What about on Airseeker deployments where whoever is deploying has access to api keys to the corresponding Airnodes?

Im referring to the monitoring software and measures in place from the core tech team to respond to issues such as the slack channel messages.

jgcogsystematictrading commented 2 years ago

@umersin61 @bbenligiray - I looked through the Chainlink docs for best practices. I can see some good topics. They do however go on-and-on-and-on. It just never ends. Seems to be overwhelming. But some people do like that sort of thing.

Such a complex model as Chainlink's makes for a difficult task with regards to the new dAPIs Best Practices page. In our last few core development team meetings the concern was that less documentation was better while having some movement to more guides. The insight document from Ben and Tamera suggests that guides and more documentation is what developers want. However they only spoke to 11 developers and they have experience with Chainlink. Not sure that is meaningful with developers new to oracles. You just a feeling of complexity in the Chainlink docs.

I will start by keeping the dAPIs best practices page simple and only address simple concepts that get developers up and running quickly, and instill some confidence in them.

  1. ease of use, readDataFeedWithDapiName(\_dapiName)
  2. explain how to monitor feeds they might wish use, we do not have tools for this at this time
  3. give them confidence in the dAPI data security model

Can anyone think of others (dAPIs related) to add to the list above. They are easy enough to add. Each will be short section in keeping with, less content and get to the point. If anyone does not agree speak up please. And we can add new sections to the page if you come across any ideas in the future. I just do not want to jump developers all over the place like Chainlink.

Back to guides, guides are good and so is a great Getting Started section which is independent to our projects (Airnode, dAPIs, OID, e.t.c.). I can see any best practices page or pages moving into the Getting started section of the next generation of the docs. I am hoping to have an early preview of this "concept" in a week or so. Nothing big but it should help with discussion around the insights document and suggestions from the core development team.

Can my origial points from https://github.com/api3dao/api3-docs/issues/959 make it into this page to start?

wkande commented 2 years ago

This issue is EOL. There are so many questions and it is getting congested. Not all belong in the Best Practices page for dAPIs. I will attempt to break this into new issues, (1) question (request) per issue. If I miss one please feel free to create a new issue. Please detail the request/question if you do.

umersin61 commented 2 years ago

@jgcogsystematictrading this document is supposed to be a best practice document for developers to integrate data feeds. What this entails is things like checking the update time for a beacon and if that's older than the defined heartbeat in the operations repository, contracts should not accept reading a value.

Monitoring for dApps using this can be done by using RPC providers and simply querying the contract for the respective value. The API endpoint we have for that is not a given and might not be kept public.

Similarly how we run the infrastructure (how many rpc providers etc) is beyond the scope of this document. We're talking about what developers should consider in their contracts when implementing this, not a 101 of how our data feeds work.

@wkande as discussed this can be pushed down in priority and also won't include any information about how providers & we run infrastructure in this document. It is beyond scope.

bbenligiray commented 1 year ago

Should this be closed?

wkande commented 1 year ago

The new docs has many guides that help with best practices.