hyperledger / iroha-2-docs Goto Github PK
View Code? Open in Web Editor NEWHome Page: https://hyperledger.github.io/iroha-2-docs/
License: Apache License 2.0
Home Page: https://hyperledger.github.io/iroha-2-docs/
License: Apache License 2.0
Need to add section on
Question: with the current generation tool/setup, is that possible to create internal links without hardcoding them (e.g. similar to ref
from restructuredtext?)
Aleksandr Petrosyan, [25.07.22 19:41]
That being said, we should document that convention too.
rust
module_name__method_name
StructName__inherent_fn
TraitName__assoc_fn_name
…
Marin, [25.07.22 19:56]
[In reply to Aleksandr Petrosyan]
1. module__name::__method_name -> we do this for functions that have the same API but are implemented on different types. Namely this is for trait impls, i.e. poor man's generics like Clone
2. yes
3. no, it's actually StructName__trait_method_name at the moment, but, in my opinion, should be reduced to 1. after 2488 (https://github.com/hyperledger/iroha/issues/2488)
Marin, [25.07.22 19:58]
1. for Clone in iroha_crypto gen_ffi_impl will create iroha_crypto::__clone in that library equivalent of Clone::clone
Aleksandr Petrosyan, [25.07.22 19:59]
This looks like we're mangling by hand.
Marin, [25.07.22 19:59]
which one?
Aleksandr Petrosyan, [25.07.22 20:00]
[In reply to Marin]
This one
Aleksandr Petrosyan, [25.07.22 20:00]
Under the circumstances I doubt we can do much better
Marin, [25.07.22 20:01]
I edited the comment
Aleksandr Petrosyan, [25.07.22 20:02]
[In reply to Marin]
Got it.
It'd be better to avoid statements about plans for future releases, new functionality, etc altogether, but for the ones that are essential, the ones that the users really should know about, we need to find a way to mark these in text so it'd be easy to regularly check their relevance and update the statements once the related features are implemented.
For example: add the same comment to each statement about ongoing work/future plans, so it'd be easy to find and check them each release. Plus would be good to have links to the open issues so we'd not spend time figuring out whether that feature was implemented or not.
https://hyperledger.github.io/iroha-2-docs/#tutorial-updates:
We will also cover peer management in greater detail: adding and removing peers, maintaining a healthy network, and troubleshooting the issues that you might have in your real-world application.
If we'll try the bash tutorial, it is missing what to do after we've minted the tokens.
I'd expect some part about exchanging those, for example, like this:
./iroha_client_cli asset transfer --from mad_hatter@looking_glass --to white_rabbit@looking_glass --asset-id tea#looking_glass --quantity 5
That part is missing. Moreover, even if I'll try, I'll have no permissions to do that:
Pipeline(
Event {
entity_kind: Transaction,
status: Rejected(
Transaction(
NotPermitted(
NotPermittedFail {
reason: "Failed to pass first check with Can't transfer assets of the other account. and second check with Account does not have the needed permission token: PermissionToken { name: \"can_transfer_user_assets\", params: {\"asset_id\": Id(AssetId(Id { definition_id: DefinitionId { name: \"tea\", domain_id: Id { name: \"looking_glass\" } }, account_id: Id { name: \"mad_hatter\", domain_id: Id { name: \"looking_glass\" } } }))} }..",
},
),
),
),
hash: { Hash(d9a5e5099dfccba677edeb3b4b15cd30c9d6d206aac9b3de8a9a71dc9a731d70) },
},
)
Sections to improve:
We need to mention ours done repository of JS project which customers will do to clone and use from the box.
git clone https://github.com/hyperledger/iroha-javascript.git --branch iroha2
RAML or Swagger based Interactive API to try out in real time in a web browser
My notes regarding this:
Some sections should be renamed (e.g., "conclusions"), some information should be moved around and grouped differently presenting the contents of the tutorial in a logical way.
Most of the info in Appendix shouldn't be there at all, because it's not something additional to the tutorial, it's the essential part of the tutorial. This might be a question of renaming the chapter and splitting it in a one or two other chapters.
Address this question: do we think there are a lot of people who are interested in iroha 1 vs. iroha 2 comparison before they learn what this tutorial can offer them? My proposal is to highlight this comparison but not put it at the very beginning.
The section should explain
This should be done after the main merges into the iroha2-stable
branch are finished.
Update the Web-assembly guide to include changes made in #2164
The tutorial used to say that discussing metadata is outside of its scope but we might want to add something on this because there were questions from the community about this. #95 (comment)
from @6r1d:
we'll need to discuss what
Value
types might be there [in asset metadata], how those are used and add proper examples
The documentation should include:
CLI documentation (check that it is updated)
Tutorial description how to connect to the Test Network
Technical description of the network
Official notification for the community with links, details about the network and invitation to test
There was a question in Hyperledger Iroha Community Telegram.
I'll need to add a note on the compatibility between Iroha 1 and Iroha 2, so the users understand the general transition process.
Can someone upgrade to iroha2 from 1. Will the two be compatible?
Compatibility between the two is analogous to Bitcoin and ethereum, so generally, no
Cryptography and account structures are different between 1 and 2, so all users would have to generate new keys and link to their old account through a centralized service. None of the data from Iroha v1 would be accessible in v2 either
Domain-scoped triggers were introduced in hyperledger/iroha#2418.
The branch is iroha2 no longer exists. Now iroha2-stable is used instead. We need to rename wherever iroha2 branch is mentioned. For example here https://hyperledger.github.io/iroha-2-docs/guide/build-and-install.html#install-iroha-from-github .
We wan to have a separation of concerns in this repo so as not to ping someone unnecessarily I propose adding
@0x009922 as the code owner of the **/**.js
@outoftardis, @WRRicht3r as the code owner of **/**.md
and myself as the code owner of **
.
In triggers.md
there are two statements that have to be verified. They are marked with the <!-- Q: still true? -->
comment:
### Event Triggers
As we have said previously, all triggers are, in a sense, event triggers.
However, this category includes the largest variety of triggers: an account
got registered, an asset got transferred, the Queen of Hearts decided to
burn all of her assets. These types of events account for the vast majority
of triggers in Ethereum, and were the first to be implemented. As of today
we only support un-scoped system-wide triggers with no permission
validation. <!-- Q: still true? --> Work is ongoing to make the triggers
safer and more reliable, but the process is time-consuming and
work-intensive.
::: info
Be mindful of the limitations. Currently triggers don't check for
permissions <!-- Q: still true? -->, so they can do things your account
wouldn't be allowed to. Since the triggers are not scoped, every trigger
processes _every_ event, and the amount of work grows quadratically.
:::
Found when RC3 mentions were removed from the text (#55).
The fix in #2371 might require changes in the tutorial.
See comment: hyperledger/iroha#2371 (comment)
The intention is to make the tutorial easily scannable and just readable. This is better be done after #42
@Mingela Identified a potential misbehaviour in pagination, and also requested that we document the filtering and sorting behaviour in-detail.
We should create an advanced topic (or subsection in the existing queries), that explains how to create the required QueryBox
object from the SDK, and how it's interpreted.
We should document the sorting behaviour (the fact that there isn't any), and give a couple of examples of
Block
s) by timestamp.We'll have to update an asset definition example with metadata that is currently possible to add.
Current example:
import iroha2.data_model.asset as asset
time = asset.Definition(
value_type=asset.ValueType.Quantity,
id=asset.DefinitionId(name="time", domain_name="looking_glass"),
# Here
metadata={},
mintable=False
)
According to @QuentinI, the proper keys for metadata have to be the Values and defined like that:
from iroha2.sys.iroha_data_model import Value
time = asset.Definition(
value_type=asset.ValueType.Quantity,
id=asset.DefinitionId(name="time", domain_name="looking_glass"),
# Here
metadata={"a": Value.U32(10)},
mintable=False
)
This seems to work properly, judging by the Hyperledger Iroha Community Telegram.
I believe we'll need to discuss what Value
types might be there, how those are used and add proper examples.
There's a question in Hyperledger Iroha Community Telegram:
Does Iroha2 have something similar to
SetAccountDetail
orGetAccountDetail
?
According to @appetrosyan, we have API
in Iroha 2 allowing to do this; accounts are the objects in the Blockchain, and each such object is allowed to contain metadata. Those objects work like key
-value
stores with values supporting each variant of the Value
enum: numbers, strings, etc.
Assets may be transferred one-by-one, or in bulk using a WASM
transaction.
Moreover, there's an asset called Store
, specifically designed to be a package of data. It is designed for the situations when you don’t really need an asset, but instead a storage of key
-value
pairs.
UPD: according to @Arjentix, there are SetKeyValue
and RemoveKeyValue
Iroha Special Instructions.
One can also get the key value using FindAccountKeyValueByIdAndKey
Iroha Query.
It doesn't close the issue completely, we'll need to provide the examples, but it explains some aspects.
We'll need to document the details for those API
features in each supported SDK
.
Build guide doesn't work because we don't have openssl installation command.
Today, @baziorek asked a question in community about permission types that would be implemented for Iroha.
Current documentation explains we can add permission and that there's a FindPermissionTokensByAccountId
query, but provides a limited information otherwise. Iroha 1 documentation, on the other hand, has a list of permissions that are typically available.
I think we should add more details: a list of permissions if we've got the same set or more details on how to define permissions.
UPD: according to @Arjentix, "the list of Iroha2 permissions is different and not specified anywhere outside code. In future users will be able to create there own permissions and validators using WASM".
@appetrosyan I'd need to add these queries to the tutorial, right?
Originally posted by @outoftardis in hyperledger/iroha#2453 (comment)
Three suggestions:
We need mention:
npm i @iroha2/crypto-target-node
npm i hada
npm i tsx -g
After that we need mention than .ts
script should locate near node_modules
And after that we need mention than script run by command tsx example.ts
Whenever a new issue is created it should receive the iroha2
and documentation
labels automatically.
We need to support three versions of Iroha simultaneously:
We need to annotate features only present in dev
and deprecated since lts
.
Have a custom vitepress environment e.g.
::: Dev-only
for features which are only available in Dev. Another environment for deprecated features (e.g. avaialable in LTS only
) and one for difference in behaviour e.g.
::: Diff LTS Dev
In LTS this does X,
But on `iroha2-dev` it does Y.
:::
The "account registration" part of the manual contains a constant public key: ed0120a753146e75b910ae5e2994dc8adea9e7d87e5d53024cfa310ce992f17106f92c
.
The source and the generation method of that key would need to be recorded in the documentation.
We need to perform QA testing on the Iroha 2 documentation to ensure the quality and accuracy of the content. https://hyperledger.github.io/iroha-2-docs/
Please go through each section and article, ensuring the content is accurate, clear, and easy to understand. Report any issues, inconsistencies, or errors that you find during the testing process. The following sections and article titles should be reviewed and tested:
Now we support
RegisterBox::new(Account::new( … ))
Add info about the chain of runtime validators.
Based on hyperledger/iroha#2641.
(stable version)
Onboarding guide for software devs to contribute to Iroha v2
With the merge of hyperledger/iroha#2314 we've added a complex infrastructure of FFI bindgen, that needs to be followed closely. @mversic has created an excellent graphic that should be included in our tutorials if possible.
TikZ or SVG fine. Prefer TikZ.
Some code snippets rely on the unsupported pre-rc.4
We should create and maintain a schematic representing object hierarchies in an Iroha blockchain. Specifically
Domain
has a Account
TimeTrigger
is a EventTrigger
etc.
Should write echo "@iroha2:registry=https://nexus.iroha.tech/repository/npm-group/" > .npmrc
instead
@iroha2:registry=https://nexus.iroha.tech/repository/npm-group/
https://hyperledger.github.io/iroha-2-docs/#tutorial-updates:
In the future this tutorial will have sections dedicated to:
- [ ] permissions
- [ ] multi-signature accounts and transactions
- [ ] custom permission validators
- [ ] permission groups
We will also cover peer management in greater detail: adding and removing peers, maintaining a healthy network, and troubleshooting the issues that you might have in your real-world application.
In-keeping with the style of the text and the prevalence of execute @outoftardis suggested that we add some Alice in Wonderland-styled graphics.
We need something very schematic, preferably in the style of a book illustration that could be put as a watermark on the page, rather than a graphic.
Drawings that we need
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.