-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
The pre-release of DSNP on Frequency https://github.com/LibertyDSNP/spec/milestone/3
- Loading branch information
Showing
10 changed files
with
217 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Identity | ||
|
|
||
| ## Purpose | ||
|
|
||
| 1. Specify how DSNP Identifiers map to Frequency. | ||
| 1. Specify how the DSNP delegation maps to Frequency. | ||
| 1. Detail how Frequency matches the ownership requirements of DSNP. | ||
|
|
||
| ## Details | ||
|
|
||
| DSNP uses [Message Source Accounts (MSAs)](https://libertydsnp.github.io/frequency/pallet_msa/index.html) that map directly to a DSNP Identity. | ||
|
|
||
| ## Identifier | ||
|
|
||
| MSAs each receive a unique unsigned 64 bit identifier that is used as the DSNP Id. | ||
| These MSAs are pseudo-anonymous identifiers that are associated with one or more public keys. | ||
| MSAs can be created by the user or on behalf of the user using a signed authorization. | ||
|
|
||
| ### Creating a DSNP User Id | ||
|
|
||
| 1. Generate a [compatible key pair](https://wiki.polkadot.network/docs/learn-keys) in your wallet. | ||
| 1. Create a Message Source Account (MSA) on Frequency using one of the `create` extrinsics. | ||
| 1. Wait for the transaction to process. | ||
|
|
||
| ### Retrieving a DSNP User Id from a Public Key | ||
|
|
||
| 1. Use the Frequency RPC call `msa_getMsaId` to retrieve the MSA Id from the public key generated in step 1. | ||
| 1. The MSA Id is the DSNP Id and can be used to generate the [DSNP User URI](../DSNP/Identifiers.md#dsnp-user-uri). | ||
|
|
||
| ## Ownership | ||
|
|
||
| Frequency has a strong ownership model for MSAs. | ||
| Ownership of an MSA is controlled by the associated keys. | ||
| MSAs are the source for [Messages](https://libertydsnp.github.io/frequency/pallet_messages/index.html) either directly or via delegation. | ||
|
|
||
| ## Delegation | ||
|
|
||
| Frequency allows for delegation to others called [Providers](https://libertydsnp.github.io/frequency/pallet_msa/index.html). | ||
| Delegation comes with permissions that grant publishing of specific Schemas to a provider. | ||
| Since each [Announcement Type](../DSNP/Announcements.md) has a [set Schema Id](./Publishing.md), a user may permission specific Announcement Types. | ||
|
|
||
| When a user delegates to a Provider, that delegation is either validated on-chain or can be validated off-chain using the `msa_checkDelegations` RPC call. | ||
| Users can revoke a delegation at anytime without any fees, and revocation is locked to the point the transaction is included in a block. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # Frequency DSNP Implementation (Pre-Release) | ||
| __Version pre-1.0.0__ | ||
|
|
||
| _Final release is pending release of [Frequency v1.0.0](https://github.com/LibertyDSNP/frequency)_ | ||
|
|
||
| DSNP on Frequency is built using Message Source Accounts (MSAs) for identity and delegation with Schemas defined for each Announcement Type. | ||
| Frequency uses Schemas to define how to create and pass messages. | ||
|
|
||
| ## Links | ||
|
|
||
| - [Frequency Documentation](https://libertydsnp.github.io/frequency/) | ||
| - [Frequency GitHub](https://github.com/LibertyDSNP/frequency) | ||
|
|
||
| ## Schemas | ||
|
|
||
| Official DSNP Schemas may be found in [GitHub](https://github.com/LibertyDSNP/schemas). | ||
|
|
||
| ## Libraries | ||
| <!-- yaspeller ignore:start --> | ||
| | Name | Language(s) | | ||
| | --- | --- | | ||
| | [TODO]() | JavaScript/TypeScript | | ||
| <!-- yaspeller ignore:end --> | ||
|
|
||
| <!--- Uncomment for pre-release changes and prefix the version with `pre-[next version]` | ||
| ## Prerelease Changelog | ||
| - [DIP-###](https://github.com/LibertyDSNP/spec/issues/###) | ||
| ---> | ||
| ## Releases | ||
|
|
||
| | Version | Description | DSNP Compatibility | Release Date | Changelog | | ||
| | --- | --- | --- | --- | --- | | ||
| | `pre-1.0.0` | Pre-Release | 1.1.x | 2022-09-19 | N/A | | ||
| <!-- | ||
| | [1.0.0](https://github.com/LibertyDSNP/spec/tree/Frequency-v1.0.0) | Initial Release | 1.1.x | 2022-10-15 | [Changelog](https://github.com/LibertyDSNP/spec/releases/tag/Frequency-v1.0.0) | | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| # Announcement Publishing | ||
|
|
||
| On Frequency, [Announcements](../DSNP/Announcements.md) are mapped to schemas which in turn publish Frequency Messages. | ||
| Frequency Messages are either direct Graph Changes from a particular user, or a Batch Publication with a multitude of users possible. | ||
|
|
||
| <!-- Links to https://libertydsnp.github.io/frequency should be updated with links to docs.frequency.xyz when able to be --> | ||
|
|
||
| | Announcement Type Enum | Announcement | Batched | Schema Id Mainnet | Schema Id Rococo | Frequency Model Type | Frequency Payload Location | | ||
| | --- | --- | --- | --- | --- | --- | --- | | ||
| | 0 | [Tombstone](../DSNP/Types/Tombstone.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
| | 1 | [Graph Change](../DSNP/Types/GraphChange.md) | no | TBD | TBD | [`AvroBinary`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.AvroBinary) | [`OnChain`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.OnChain) | | ||
| | 2 | [Broadcast](../DSNP/Types/Broadcast.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
| | 3 | [Reply](../DSNP/Types/Reply.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
| | 4 | [Reaction](../DSNP/Types/Reaction.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
| | 5 | [Profile](../DSNP/Types/Profile.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
| | 6 | [Update](../DSNP/Types/Update.md) | YES | TBD | TBD | [`Parquet`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.ModelType.html#variant.Parquet) | [`IPFS`](https://libertydsnp.github.io/frequency/common_primitives/schema/enum.PayloadLocation.html#variant.IPFS) | | ||
|
|
||
| Source code for each schema is also located in the [LibertyDSNP/schemas](https://github.com/LibertyDSNP/schemas) repository. | ||
|
|
||
| ## DSNP Non-Batched Announcements | ||
|
|
||
| Frequency uses an on-chain data structure for storage of `GraphChange` Announcements. | ||
| Each individual announcement is submitted using the [`add_onchain_message`](https://libertydsnp.github.io/frequency/pallet_messages/pallet/enum.Call.html#variant.add_onchain_message) extrinsic. | ||
|
|
||
| ## DSNP Batched Announcements | ||
|
|
||
| Frequency uses [DSNP Batch Publications](../DSNP/BatchPublications.md) for Announcements that are batched. | ||
| The parquet file is stored on [IPFS](https://ipfs.io/), but it is discovered through the Frequency Message. | ||
|
|
||
| Frequency Messages maintain the metadata of where and when the Batch Publication was published and which Provider MSA published it. | ||
| It is the publisher's responsibility to maintain the [IPFS pin](https://docs.ipfs.tech/concepts/glossary/#pinning) so that the batch file is continuously available. | ||
|
|
||
| DSNP Batch Publications [MUST be validated](./Validation.md) upon fetching to ensure data and permission integrity. | ||
|
|
||
| ## Ordering | ||
|
|
||
| Frequency Messages are well ordered within a Schema | ||
|
|
||
| 1. Frequency: Block number ascending | ||
| 2. Frequency: Block index ascending | ||
| 3. DSNP Standard: Order Announcements in a Batch Publication File by row appearance order | ||
|
|
||
| ### Ordering Across Schemas | ||
|
|
||
| Frequency provides complete ordering metadata for Messages across Schemas. | ||
| Block index is unique per Message within the same block. | ||
|
|
||
| ### Human Order | ||
|
|
||
| Due to the asynchronous nature of networks and batching, it is possible that the canonical ordering of Announcements is wrong from a human viewpoint. | ||
| With dependent Announcements, where one Announcement refers to another Announcement, the order may be inferred differently than the canonical ordering. | ||
| It is left to user interfaces to handle these situations. | ||
|
|
||
|
|
||
| ## Retrieval | ||
|
|
||
| Frequency nodes provide an RPC interface [`get_messages_by_schema`](https://libertydsnp.github.io/frequency/pallet_messages_rpc/trait.MessagesApiClient.html#method.get_messages_by_schema) with paginated responses that differ based on the Schema. | ||
|
|
||
| Frequency nodes can provide a websocket interface that will emit an event for each block that has one or more messages of a given schema in that block. | ||
| The [`MessagesStored`](https://libertydsnp.github.io/frequency/pallet_messages/pallet/enum.Event.html#variant.MessagesStored) event can be used to know when to call the RPC interface to retrieve the messages. | ||
|
|
||
| See the [Frequency Documentation](https://libertydsnp.github.io/frequency/pallet_messages_rpc/trait.MessagesApiClient.html#method.get_messages_by_schema) for more details on Message retrieval. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # Announcement Validation | ||
|
|
||
| DSNP Announcements are validated differently depending on the type of Announcement. | ||
| Batched Announcements are off-chain and MUST be validated at read time. | ||
| Non-batched Announcements (example: Graph Change), are on-chain and are validated at write time and do not need to be re-validated at read time. | ||
|
|
||
| ## On-chain Announcements | ||
|
|
||
| Creation of an Announcement as an on-chain Frequency Message requires that the delegation be validated before adding the message to the chain. | ||
| Thus, any Graph Change Announcements read from a trusted node, can be trusted to have been made by the DSNP identity or a delegate of the identity at the time the Frequency Message was sent. | ||
|
|
||
| ### On-Chain Announcement Types | ||
| - Graph Change | ||
|
|
||
|
|
||
| ## Batch Publication Announcements | ||
|
|
||
| DSNP Announcements that are in a Batch Publication MUST be validated at read time. | ||
|
|
||
| ### Batched Announcement Types | ||
| - Tombstone | ||
| - Broadcast | ||
| - Reply | ||
| - Reaction | ||
| - Profile | ||
|
|
||
| <!-- Links to https://libertydsnp.github.io/frequency should be updated with links to docs.frequency.xyz when able to be --> | ||
|
|
||
| ## Batch Publication Frequency Message Validation | ||
|
|
||
| The [Frequency Message](https://libertydsnp.github.io/frequency/common_primitives/messages/struct.MessageResponse.html) for a Batch Publication has several important fields for validation: | ||
|
|
||
| | Field | Description | | ||
| | ----- | ----------- | | ||
| | `provider_msa_id` | MSA Id of the provider sending the message | | ||
| | `cid` | The [Content IDentifier v1](https://github.com/multiformats/cid/) for IPFS content | | ||
| | `payload_length` | Expected length of the content from IPFS | | ||
| | `block_number` | Block number that the message was recorded on the chain. | | ||
|
|
||
| ### File Validation | ||
|
|
||
| 1. Retrieve the file from the IPFS network using the `cid`. | ||
| 1. (Required for non-trusted IPFS nodes) Verify the file hash by [comparing it to the hash included in the `cid`](https://docs.ipfs.tech/concepts/hashing/). | ||
| 1. Verify that the byte length of the retrieved file matches the `payload_length`. | ||
|
|
||
| ### Publication Announcements Validation | ||
|
|
||
| 1. Collect the unique set of `fromId` values. | ||
| 1. Use the [Custom RPC `msa_checkDelegations`](https://libertydsnp.github.io/frequency/pallet_msa_rpc/trait.MsaApiClient.html#method.check_delegations) with the `fromId` values as the `delegator_msa_ids` and the `provider_msa_id` at the `block_number`. | ||
| 1. The `fromId` values that `msa_checkDelegations` verifies as having a delegation at `block_number` are valid Announcements. | ||
|
|
||
| ## Announcement Duplicates | ||
|
|
||
| Duplicate Announcements MUST be rejected or ignored. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,4 @@ | ||
| # DSNP Implementations | ||
|
|
||
| - [Ethereum/EVM Compatible](Ethereum/Overview.md) (Official) | ||
| - [Frequency](Frequency/Overview.md) (Official) | ||
| - [Ethereum/EVM Compatible](Ethereum/Overview.md) (Deprecated) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters