Rust docs (#14)

* Inline comments for the contract * Create rust doc for public methods
archetype-org · Feb 27, 2024 · ce731da · ce731da
1 parent 4590d87
commit ce731da
Show file tree

Hide file tree

Showing 3 changed files with 127 additions and 0 deletions.
diff --git a/doc/doc.md b/doc/doc.md
@@ -0,0 +1,39 @@
+# Documentation
+
+This NEAR contract for the attestation registry contains several components to allow users to submit attestations as well as publish package manifests.
+
+
+## Public Methods
+
+Be sure to check out the inline documentation for detailed descriptions of parameters. One thing to note is that keys for attestations are generated by hashing both the package name and author.
+
+``create_manifest``
+
+This method allows an author to publish a package manifest under a specific package name. The contract uses the lazy-loaded storage available on NEAR. It supports the ability for both predecessor accounts as well as signers to be the key in which others can retrieve manifests.
+Projects such as `bos-workspace` can then use their namespace accounts to forward transactions on behalf of users.
+
+``get_latest_manifest``
+
+Retrieves the last manifest that was published to the registry for a particular package. Transaction will revert if the conditions for retrieval are not satisfied.
+
+``get_manifest``
+
+If a user knows the version of the package manifest they are looking for they can retrieve it from the registry. Given the fact a version may exist at one point in time we return a string "None" when not found in cases in which other contracts may not want to revert when accessing
+documents stored in the registry.
+
+``update_manifest``
+
+An author may update the cid for an existing manifest in the registry. This function does revert if the manifest was not published by a signer. Furthermore, it will revert if the manifest does not exist in the registry prior to updating.
+
+``create_attestation``
+
+When a package manifest has been published for a package name and given author NEAR account ID, another signer may create an attestation object that contains a cid representing a claim.
+
+``get_attestations``
+
+You may then retreive all of the attestations from a particular user if you know the package name and package author the claim is being generated against. This function reverts when claims are not found for a given namespace.
+
+``get_attestation``
+
+If you know the order of attestations submitted to the registry, this method allows you to only retrieve that particular claim. It will revert if the parameters provided are not found.
+
diff --git a/doc/docs.html b/doc/docs.html
@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="generator" content="rustdoc">
+    <title>Documentation</title>
+
+
+
+</head>
+<body class="rustdoc">
+    <!--[if lte IE 8]>
+    <div class="warning">
+        This old browser is unsupported and will most likely display funky
+        things.
+    </div>
+    <![endif]-->
+
+
+    <h1 class="title">Documentation</h1>
+    <nav id="TOC"><ul>
+<li><a href="#public-methods">0.1 Public Methods</a><ul></ul></li></ul></nav><p>This NEAR contract for the attestation registry contains several components to allow users to submit attestations as well as publish package manifests.</p>
+<h2 id="public-methods"><a href="#public-methods">0.1 Public Methods</a></h2>
+<p>Be sure to check out the inline documentation for detailed descriptions of parameters. One thing to note is that keys for attestations are generated by hashing both the package name and author.</p>
+<p><code>create_manifest</code></p>
+<p>This method allows an author to publish a package manifest under a specific package name. The contract uses the lazy-loaded storage available on NEAR. It supports the ability for both predecessor accounts as well as signers to be the key in which others can retrieve manifests.
+Projects such as <code>bos-workspace</code> can then use their namespace accounts to forward transactions on behalf of users.</p>
+<p><code>get_latest_manifest</code></p>
+<p>Retrieves the last manifest that was published to the registry for a particular package. Transaction will revert if the conditions for retrieval are not satisfied.</p>
+<p><code>get_manifest</code></p>
+<p>If a user knows the version of the package manifest they are looking for they can retrieve it from the registry. Given the fact a version may exist at one point in time we return a string “None” when not found in cases in which other contracts may not want to revert when accessing
+documents stored in the registry.</p>
+<p><code>update_manifest</code></p>
+<p>An author may update the cid for an existing manifest in the registry. This function does revert if the manifest was not published by a signer. Furthermore, it will revert if the manifest does not exist in the registry prior to updating.</p>
+<p><code>create_attestation</code></p>
+<p>When a package manifest has been published for a package name and given author NEAR account ID, another signer may create an attestation object that contains a cid representing a claim.</p>
+<p><code>get_attestations</code></p>
+<p>You may then retreive all of the attestations from a particular user if you know the package name and package author the claim is being generated against. This function reverts when claims are not found for a given namespace.</p>
+<p><code>get_attestation</code></p>
+<p>If you know the order of attestations submitted to the registry, this method allows you to only retrieve that particular claim. It will revert if the parameters provided are not found.</p>
+
+
+</body>
+</html>
diff --git a/src/lib.rs b/src/lib.rs
@@ -7,13 +7,16 @@ use near_sdk::{
     AccountId, BorshStorageKey, PublicKey, require
 };
 
+
+// Represents the content being stored into the storage map
 #[derive(BorshSerialize, BorshDeserialize, Clone, Debug)]
 pub struct Manifest {
     pub version: String,
     pub cid: String,
     pub content_type: String
 }
 
+// An attestation for a given manifest
 #[derive(BorshSerialize, BorshDeserialize, Serialize, Deserialize, Clone, Debug)]
 #[serde(crate = "near_sdk::serde")]
 pub struct Attestation {
@@ -36,7 +39,9 @@ pub type Attestations = Vec<Attestation>;
 #[near_bindgen]
 #[derive(BorshDeserialize, BorshSerialize)]
 pub struct Contract {
+    // Each package in the registry is linked by a NEAR Account. Releases are then treated as a list of manifests
     pub packages: LookupMap<AccountId, Releases>,
+    // A signer can submit an attestation for a particular package already in the registry
     pub attestations: LookupMap<AccountId, LookupMap<Namespace, Attestations>>,
 }
 
@@ -58,6 +63,7 @@ impl Contract {
         }
     */
 
+    /* Helper Functions */
     fn generate_key(author: AccountId, package_name: String) -> Namespace {
         let key = author.as_str().to_owned() + package_name.as_str();
         return near_sdk::env::sha256(key.as_bytes());
@@ -83,12 +89,20 @@ impl Contract {
         return at.get(&hash).unwrap();
     }
 
+    /* Public Methods */
+
+    // Create a manifest resource for a package
     pub fn create_manifest(
         &mut self,
+        // A string representing the name of a particular package
         package_name: String,
+        // The version string that can represent either semantic versioning or any other format
         version: String,
+        // Specifies the type of content once resolved via the content id
         content_type: String,
+        // The IPFS content id that contains the package manifest
         cid: String,
+        // If a contract is calling this function the reference key can be the contract account if true or the signers account when false
         is_contract: bool,
     ) {
         let manifest = Manifest {
@@ -123,9 +137,12 @@ impl Contract {
         manifests.insert(&package_name, &versions);
     }
 
+    // Retrieves the last manifest for a particular package
     pub fn get_latest_manifest(
         &self,
+        // An account ID of the author who published the manifest
         account_id: AccountId,
+        // A string representing the name of a particular package
         package_name: String
     ) -> String {
         let manifests = self.safe_package_retrieval(account_id);
@@ -138,10 +155,15 @@ impl Contract {
             .cid.clone();
     }
 
+    // Get a single manifest file given a version and package name
+    // It will return a string saying "None" if no manifest was found
     pub fn get_manifest(
         &self,
+        // An account ID of the author who published the manifest
         account_id: AccountId,
+        // A string representing the name of a particular package
         package_name: String,
+        // The version string that is used to retreive the manifest
         version: String
     ) -> String {
         let manifests = self.safe_package_retrieval(account_id);
@@ -157,11 +179,16 @@ impl Contract {
         return "None".to_string();
     }
 
+    // Update a particular manifest file given the package name and version
     pub fn update_manifest(
         &mut self,
+        // A string representing the name of a particular package
         package_name: String,
+        // The version string that is used to retreive the manifest
         version: String,
+        // The new content type if changed
         content_type: String,
+        // The IPFS content to replace the existing one
         cid: String
     ) {
         let mut manifests = self.safe_package_retrieval(near_sdk::env::signer_account_id());
@@ -182,10 +209,14 @@ impl Contract {
         manifests.insert(&package_name, &v);
     }
 
+    // Add an attestation for a package that exists inside of the registry
     pub fn create_attestation(
         &mut self,
+        // A string representing the name of a particular package
         package_name: String,
+        // An account ID of the author who published the manifest
         author: AccountId,
+        // An IPFS content ID that contains the attestation data
         cid: String
     ) {
         let manifests = self.safe_package_retrieval(author.clone());
@@ -219,10 +250,15 @@ impl Contract {
         at.insert(&hash, &user_atts);
     }
 
+    // Retrieve all of the attestations for a given package and signer account ID
+    // Returns a list of attestation objects if they exist in the registry, otherwise reverts
     pub fn get_attestations(
         &mut self,
+        // The author of the attestation
         attestor: AccountId,
+        // The package name that the attestor has made a claim against
         package_name: String,
+        // The author for a particular package
         author: AccountId
     ) -> Attestations {
         let manifests = self.safe_package_retrieval(author.clone());
@@ -235,11 +271,18 @@ impl Contract {
         );
     }
 
+
+    // Retrieve a single attestation at a particular index
+    // Returns an attestation object if an index is known in advance
     pub fn get_attestation(
         &mut self,
+        // The author of the attestation
         attestor: AccountId,
+        // The package name that the attestor has made a claim against
         package_name: String,
+        // The author for a particular package
         author: AccountId,
+        // An index containing an attestation object
         index: usize
     ) -> Attestation {
         let at = self.get_attestations(attestor, package_name, author);