Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove mistakenly merged files. Add code references, make title consi… #4

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Remove mistakenly merged files. Add code references, make title consi… #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion themis/cred-def.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,5 +92,9 @@ When claims are issued and/or revoked, the revocation registry needs to be updat
}
```

## Code references to ledger objects
## Code references to ledger objects (some of below might be different from above mentioned structure, the above structure should be considered the correct representation)
1. [CLAIM_DEF](https://github.com/hyperledger/indy-sdk/blob/778a38d92234080bb77c6dd469a8ff298d9b7154/libindy/src/services/ledger/types.rs#L234)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be CRED_DEF?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so you'll make that change?

2. [Primary public key](https://github.com/hyperledger/indy-crypto/blob/fc078a014a6b72ede838b79696258d3ee56f87d4/libindy-crypto/src/cl/mod.rs#L161)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem like protocol level documentation. Maybe this should be in the indy-crypto repo itself?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, why a credential definition has primary and revocation sections go in this protocol repo and the details of the structure of each of the objects go in the respective source code repo (indy-crypto, indy-sdk, indy-node)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed!

3. [Revocation public key](https://github.com/hyperledger/indy-crypto/blob/fc078a014a6b72ede838b79696258d3ee56f87d4/libindy-crypto/src/cl/mod.rs#L202)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These links will work forever, which is great.
Problem is, if that object evolves, then the documentation won't show that.
The reason for having the link is we can jump to the current code representation of that object.

Maybe we should move some of this lower level stuff to the source code repo and reference the documentation from this repo?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, if we move the sections describing the structure of Cred def, etc to respective source repos, then these can be converted to links to master (active) branch and can be updated with the code

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I like that.

4. [Revocation Registry Definition](https://github.com/hyperledger/indy-crypto/blob/fc078a014a6b72ede838b79696258d3ee56f87d4/libindy-crypto/src/cl/mod.rs#L229)
5. [Revocation Registry Entry](https://github.com/hyperledger/indy-crypto/blob/fc078a014a6b72ede838b79696258d3ee56f87d4/libindy-crypto/src/cl/mod.rs#L249)
7 changes: 5 additions & 2 deletions themis/cred-offer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# CRED_OFFER
# Credential Offer

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need both long names (e.g., Credential Offer) as well as msg types (e.g., CRED_OFFER) right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently there is nothing called a CRED_OFFER in the open source codebase atleast

A credential offer is sent from an issuer to a potential holder. It
communicates the type of credential on offer, and possibly its proposed
Expand All @@ -13,4 +13,7 @@ credential is issued.
```

Credential offers sent to a potential holder are typically followed by
[credential request](cred-request.md) that flow the other direction.
[credential request](cred-request.md) that flow the other direction.

## Code reference (some of below might be different from above mentioned structure, the above structure should be considered the correct representation)
1. [Credential Offer](https://github.com/hyperledger/indy-sdk/blob/ad77c94a1116d2540bc6365cdb4f22ebfc899401/libindy/src/domain/credential_offer.rs#L7)
3 changes: 3 additions & 0 deletions themis/cred-request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,6 @@ to them.

## Credential Notice
When an issuer is making a change that affects its credential holders, it should let them know of the change. This could be because that the Issuer is updating its Credentials to a new schema, or rotating its public keys, or some breach was detected and credentials issued between a certain date period need to be reissued, or a particular credential was revoked (e.g, driver privileges suspended due to court order). This is done by sending the credential holder(s) a Credential Notice message.

## Code reference (some of below might be different from above mentioned structure, the above structure should be considered the correct representation)
1. [Credential Request](https://github.com/hyperledger/indy-sdk/blob/ad77c94a1116d2540bc6365cdb4f22ebfc899401/libindy/src/domain/credential_request.rs#L12)
58 changes: 0 additions & 58 deletions themis/non-public-objects.md
View file
Open in desktop

This file was deleted.

4 changes: 4 additions & 0 deletions themis/proof-request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,7 @@ The message sent by the relying party to the holder describing the verifiable at
"nonce": "<a nonce acting as request id>"
}
```


## Code reference (some of below might be different from above mentioned structure, the above structure should be considered the correct representation)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why might it be different? It seems that the code would be more correct.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code would (and in some cases "should") be refactored.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so what should we do when we have documentation that is ahead of the code structure? I think the documentation should mention both the current version, and the future version, right?

1. [Proof Request](https://github.com/hyperledger/indy-sdk/blob/ad77c94a1116d2540bc6365cdb4f22ebfc899401/libindy/src/domain/proof_request.rs#L11)
5 changes: 4 additions & 1 deletion themis/proof.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Proof Format
# Proof

A proof is a JSON document that derives from one or more credentials. It
demonstrates in a cryptographic/mathematical way that attributes within
Expand Down Expand Up @@ -36,3 +36,6 @@ data is at rest.
The formats of `proofs` and `aggregated_proof` are documented and governed
by indy-sdk.


## Code reference (some of below might be different from above mentioned structure, the above structure should be considered the correct representation)
1. [Proof](https://github.com/hyperledger/indy-sdk/blob/ad77c94a1116d2540bc6365cdb4f22ebfc899401/libindy/src/domain/proof.rs#L9)
191 changes: 0 additions & 191 deletions themis/public-objects.md
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion themis/zklang.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# ZKLang
__Taken from [ZKLang Meeting Notes](https://docs.google.com/document/d/1CwVljF8fS5NwF6NAppCvD4jLtH9t2m1rkut54hYGLm0/edit). That is a meeting notes doc so should not be referenced__
A typical interaction between an identity owner and relying party (which has asked for proof) looks like this.
1. Relying party asks for proof using Proof Request.
2. Identity owner examines the proof request and decides what credential definitions need to be used for creating the proof. The resulting object is called a proof resolution.
Expand Down