feat(all): project initiation and architecture

README.md

@@ -1,2 +1,3 @@
 # Rarity
+
 An algorithm to calculate rarity of NFT(how special it is), based on Jaccard Distance.

package.json

@@ -0,0 +1,20 @@
+{
+  "name": "gorarity",
+  "version": "1.0.0",
+  "description": "An algorithm to calculate rarity of NFT(how special it is), based on Jaccard Distance.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NFTGo/GoRarity.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/NFTGo/GoRarity/issues"
+  },
+  "homepage": "https://github.com/NFTGo/GoRarity#readme"
+}

src/index.ts

@@ -0,0 +1,2 @@
+export * from "./models";
+export * from "./rarity-ranker";

src/models/collection.ts

@@ -0,0 +1,26 @@
+import { Token } from "./token";
+import { StringAttribute } from "./token-metadata";
+import { TokenStandard } from "./token-standard";
+
+export type CollectionAttribute = {
+  attribute: StringAttribute,
+  totalTokens: number,
+}
+
+export class Collection {
+  name: string;
+  tokens: Token[];
+
+  constructor(dict: { name: string, tokens: Token[] }) {
+    this.name = dict.name;
+    this.tokens = dict.tokens;
+  }
+
+  tokenStandards(): TokenStandard[] {
+    const tokenStandards = new Set<TokenStandard>();
+    this.tokens.forEach(item => {
+      tokenStandards.add(item.tokenStandard);
+    })
+    return Array.from(tokenStandards.values())
+  }
+}

src/models/index.ts

@@ -0,0 +1,6 @@
+export * from "./collection";
+export * from "./token";
+export * from "./token-identifier";
+export * from "./token-metadata";
+export * from "./token-rarity";
+export * from "./token-standard";

src/models/token-identifier.ts

@@ -0,0 +1,24 @@
+export class EVMContractTokenIdentifier {
+  public contractAddress: string;
+  public tokenId: number;
+
+  constructor(contractAddress: string, tokenId: number) {
+    this.contractAddress = contractAddress;
+    this.tokenId = tokenId;
+  }
+
+  get() {
+    return `Contract(${this.contractAddress}) #${this.tokenId}`;
+  }
+
+  static fromDict(dict: { contractAddress: string, tokenId: number }) {
+    return new EVMContractTokenIdentifier(dict.contractAddress, dict.tokenId);
+  }
+
+  toDict() {
+    return {
+      "contractAddress": this.contractAddress,
+      "tokenId": this.tokenId,
+    };
+  }
+}

src/models/token-metadata.ts

@@ -0,0 +1,34 @@
+import { normalizeAttributeString } from "./utils/attribute-utils";
+
+type AttributeName = string;
+type AttributeValue = string;
+
+export class StringAttribute {
+  public name: AttributeName;
+  public value: AttributeValue;
+
+  constructor(name: AttributeName, value: AttributeValue) {
+    this.name = normalizeAttributeString(name);
+    this.value = normalizeAttributeString(value);
+  }
+}
+
+export class TokenMetadata {
+  public stringAttributes: Map<AttributeName, StringAttribute> | undefined = new Map();
+
+  constructor(
+    stringAttributes: Map<AttributeName, StringAttribute>,
+  ) {
+    if (!stringAttributes) { throw new Error('null stringAttributes') }
+    this.stringAttributes = TokenMetadata.normalizeAttributes<StringAttribute>(stringAttributes);
+  }
+
+  private static normalizeAttributes<T>(attributes: Map<AttributeName, T>) {
+    const normalizedAttributes = new Map<AttributeName, T>();
+    attributes.forEach((attribute, attributeName) => {
+      const normalizedAttributeName = normalizeAttributeString(attributeName);
+      normalizedAttributes.set(normalizedAttributeName, attribute)
+    });
+    return normalizedAttributes
+  }
+}

src/models/token-ranking-features.ts

@@ -0,0 +1,4 @@
+export type TokenRankingFeatures = {
+  // count of unique attributes in the token
+  uniqueAttributeCount: number,
+}

src/models/token-rarity.ts

@@ -0,0 +1,9 @@
+import { Token } from "./token"
+import { TokenRankingFeatures } from "./token-ranking-features"
+
+export type TokenRarity = {
+  score: number,
+  tokenFeatures: TokenRankingFeatures,
+  token: Token,
+  rank: number,
+}

src/models/token-standard.ts

@@ -0,0 +1,4 @@
+export enum TokenStandard {
+  ERC721 = "erc721",
+  ERC1155 = "erc1155",
+}

src/models/token.ts

@@ -0,0 +1,15 @@
+import { EVMContractTokenIdentifier } from "./token-identifier";
+import { TokenMetadata } from "./token-metadata";
+import { TokenStandard } from "./token-standard";
+
+export class Token {
+  public tokenIdentifier: EVMContractTokenIdentifier;
+  public tokenStandard: TokenStandard;
+  public metadata: TokenMetadata;
+
+  constructor(tokenIdentifier: EVMContractTokenIdentifier, tokenStandard: TokenStandard, metadata: TokenMetadata) {
+    this.tokenIdentifier = tokenIdentifier;
+    this.tokenStandard = tokenStandard;
+    this.metadata = metadata;
+  }
+}

src/models/utils/attribute-utils.ts

@@ -0,0 +1,3 @@
+export function normalizeAttributeString(value: string): string {
+  return value.toLowerCase().trim();
+}

src/rarity-ranker.ts

@@ -0,0 +1,26 @@
+import { Collection, TokenRarity } from "./models";
+import { Scorer } from "./scoring";
+
+export class RarityRanker {
+  private static defaultScorer = new Scorer();
+
+  constructor() { }
+
+  static rankCollection(collection: Collection, score: Scorer = RarityRanker.defaultScorer): TokenRarity[] {
+    if (!collection || !collection.tokens || collection.tokens.length === 0) return [];
+
+    const tokens = collection.tokens;
+    const scores = score.scoreTokens(collection, tokens);
+    if (scores.length !== tokens.length) { throw new Error(`dimension of scores doesn't match dimension of tokens`) }
+
+    const tokenRarities: TokenRarity[] = []
+
+    // TODO
+
+    return RarityRanker.setRarityRanks(tokenRarities);
+  }
+
+  static setRarityRanks(tokenRarities: TokenRarity[]): TokenRarity[] {
+    return [];
+  }
+}

src/scoring/handlers/index.ts

@@ -0,0 +1 @@
+export * from "./jaccard-distance-scoring-handler";

src/scoring/handlers/jaccard-distance-scoring-handler.ts

@@ -0,0 +1,9 @@
+import { Collection, Token } from "../../models";
+import { IScoringHandler } from "../scoring-handler";
+
+export class JaccardDistanceScoringHandler implements IScoringHandler {
+
+  scoreTokens(collection: Collection, tokens: Token[]): number[] {
+    return [];
+  }
+}

src/scoring/index.ts

@@ -0,0 +1,2 @@
+export * from "./handlers";
+export * from "./scorer";

src/scoring/scorer.ts

@@ -0,0 +1,26 @@
+import { Collection, Token, TokenStandard } from "../models";
+import { JaccardDistanceScoringHandler } from "./handlers";
+import { IScoringHandler } from "./scoring-handler";
+
+export class Scorer {
+
+  private handler: IScoringHandler;
+
+  constructor() {
+    this.handler = new JaccardDistanceScoringHandler();
+  }
+
+  validateCollection(collection: Collection) {
+    const allowedStandards = [TokenStandard.ERC721, TokenStandard.ERC1155];
+
+    // TODO validate collection with the rules
+    //
+    collection.tokenStandards().every(val => allowedStandards.includes(val))
+  }
+
+  scoreTokens(collection: Collection, tokens: Token[]): number[] {
+
+    this.validateCollection(collection);
+    return this.handler.scoreTokens(collection, tokens);
+  }
+}

src/scoring/scoring-handler.ts

@@ -0,0 +1,5 @@
+import { Collection, Token } from "../models";
+
+export interface IScoringHandler {
+  scoreTokens(collection: Collection, tokens: Token[]): number[],
+}

tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "commonjs",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "composite": true
+  }
+}