Reputation Service

Introduction

The Reputation Service is a sophisticated system designed to collect otmoic swap data on chain and evaluate reputations for users and liquidity providers (LPs). It consists of several key components that work together to ensure the integrity and reliability of reputation data. The main components of the system are the Connector, Points, and Agent.

Connector

The Connector is responsible for interfacing with various blockchain networks. It handles the communication with chain clients, retrieves blockchain data, and processes block updates. The Connector ensures that the system stays synchronized with the blockchain by managing block heights and handling historical data requests. Key functionalities include:

• Initialization: The Connector initializes by loading the current block height from the storage and setting up callback URLs for block height updates.

• Block Updates: It processes block updates by handling incoming data from the blockchain and updating the system's state accordingly.

• Historical Data Requests: The Connector can request historical blockchain data to ensure that the system has a complete and accurate record of past transactions.

Points

The Points component is responsible for managing and calculating reputation points within the system. Unlike the Connector, the Points component does not interact directly with the blockchain. Instead, it reads data from the Connector's database and uses this information to calculate reputation points for users and liquidity providers (LPs). Key functionalities include:

• Reputation Management: The Points component manages the addition, subtraction, and querying of reputation scores for both users and LPs. It ensures that reputation data is accurately calculated and stored based on the information retrieved from the Connector's database.

• Data Retrieval： It retrieves necessary data from the Connector's database, such as transaction records, complaints, and swap agreements. This data is then used to calculate the reputation points.

• Reputation Calculation:：The Points component calculates reputation scores based on predefined rules and criteria. For example, it may deduct points for violations or complaints and add points for successful transactions and positive behaviors.

• API Endpoints: The Points component provides several API endpoints to query reputation data. These endpoints include:

  • GET /user-point: Retrieves the reputation points for a specific user.

  • GET /lp-point: Retrieves the reputation points for a specific LP.

  • GET /user-deduction-records: Retrieves the deduction records for a specific user.

  • GET /lp-deduction-records: Retrieves the deduction records for a specific LP.

  • GET /complaint: Retrieves the complaint details for a specific bid.

Detailed Reputation arbitor rules

1. Case 0: Invalid Complaint

   • The complaint is invalid if the user's or liquidity provider's (LP) signature is not authentic.

2. Case 1: User Violation

   • After reaching a swap agreement, the user fails to initiate the swap by not sending the transferOut.

3. Case 2: User Violation

   • The parameters of the user's transferOut do not match the agreement parameters.

4. Case 3: LP Violation

   • The LP fails to respond with transferIn after the user initiates a transferOut.

5. Case 4: LP Violation

   • The parameters of the LP's transferIn do not match the user's transferOut request.

6. Case 5: User Violation

   • The user has not confirmed transferOut or did not confirm it within the allowed time (3 times the expected single step time).

7. Case 6: LP Violation

   • The LP has not confirmed transferIn or did not confirm it within the allowed time (3 times the expected single step time plus 1 times tolerant single step time).

8. Case 7: User Violation

   • The user cheats by unlocking confirmIn before confirmOut.

9. Normal Swap

   • The swap process follows a normal sequence: transferOut, transferIn, confirmOut, confirmIn, with average response time calculated.

10. Other Cases: Unknown Status

    • If none of the above conditions are met, the status is marked as unknown.

These cases help determine whether the actions of the user or LP are in violation of the agreed terms or if the swap process is proceeding normally.

Detailed Reputation calculation rules

User Reputation Points

• Basis Points:

  • Every user starts with a basis point of 2.
  • If the user is a KYC-verified user, the basis point is increased to 5.

• Deductions:

  • For each user violation within the last 3 months, 0.1 point is deducted from the basis point.
  • A user's reputation points cannot fall below 0.

LP (Liquidity Provider) Reputation Points

• Basis Points:

  • The basis points for LPs are determined based on their performance over the last 3 months, considering the total number of transactions, success rate, and average response time.

  • The following criteria are used:

    Total Transactions	Success Rate	Average Response Time	Basis Points
    >= 720	>= 99%	< 1 minute	5
    >= 150	>= 95%	< 5 minutes	4
    >= 30	>= 90%	< 15 minutes	3
    >= 6	>= 80%	< 1 hour	2
    >= 1.2	>= 60%	< 24 hours	1

• Deductions:

  • For each LP violation within the last 3 months, 0.1 point is deducted from the basis point.
  • An LP's reputation points cannot fall below 0.

These rules ensure that both users and LPs are incentivized to maintain good practices and provide reliable services.

Agent

The Agent component is a proxy application that plays a crucial role in handling complaint submissions and interacting with blockchain smart contracts to store complaint data on-chain.

Installation

To install the project dependencies, run:

npm install

Configuration

To configure the Reputation Service, you need to set up the config.toml file and environment variables. Below is an example configuration:

config.toml

n8nUrl = ""

[point]
port = 1235
relayAdminUrl = "https://xxxxxx"
didSupportUrl = "https://xxxxxx"
refreshInterval = 60000 # 60 seconds

[agent]
port = 1237
rpc = "https://sepolia.optimism.io"
priv = ""
contractAddr = "0xe69257d83b2c50b2d7496348d053d76c744753e4"

[connector]
port = 1234
callbackUrl = "http://localhost:1234"

[rpc-urls]
9006 = "https://bsc-testnet.blockpi.network/v1/rpc/public"
614 = "https://optimism.llamarpc.com"
501 = "https://api.mainnet-beta.solana.com"

[[chainClients]]
url = "http://localhost:9100"
historyUrl = "http://localhost:9100"
initBlockHeight = 291676000
chainId = "501" # solana
nativeChainId = "501"
registerPath = "/support/register"
historyPath = "/support/history"

# Uncomment and configure additional chain clients as needed
# [[chainClients]]
# url = "http://localhost:9101"
# historyUrl = "http://localhost:9101"
# initBlockHeight = 42966090
# chainId = "9006" # bsc
# nativeChainId = "97" # bsc
# registerPath = "/support/register"
# historyPath = "/support/history"

Environment Variables

Set the following environment variables in an env.sh file or directly in your environment:

export DBHOST="localhost"
export DBPORT="5432"
export DBUSER="postgres"
export DBPASS="postgrespassword"
export DBNAME="otmoic_reputation"
export MONGO_HOST="localhost"
export MONGO_PORT="27017"
export MONGO_USER="root"
export MONGO_PASS="root"
export MONGO_DB="Otmoic-Points-TestNet"

Loading Environment Variables

To load the environment variables from the env.sh file, run the following command in your terminal:

source env.sh

Ensure that the config.toml file is placed in the root directory of the project and that the environment variables are correctly set before running the services.

Usage

Starting the Services

To start the various services, use the following commands:

• Start Connector: npm run start-connector
• Start Points: npm run start-points
• Start Agent: npm run start-agent

Scripts

The following scripts are available in the package.json file:

• test: Run the tests using Jest.
• build: Compile the TypeScript code.
• format: Format the code using Prettier.
• start-connector: Start the connector service.
• start-points: Start the points service.
• start-agent: Start the agent service.

Testing

To run the tests, use:

npm test