openapi: 3.1.0 info: title: EigenTrust Basic API summary: The EigenTrust Basic API implements the Basic EigenTrust algorithm. version: 0.2.0 servers: - url: 'https://api.k3l.io/basic/v1/' description: | The API server hosted by Karma3 Labs. - url: 'http://localhost:8080/basic/v1' description: | The self-hosted local server, run by `eigentrust serve`. paths: /compute: post: summary: Compute EigenTrust scores description: | Compute EigenTrust scores using the given inputs. A compute request takes four inputs: * Local trust matrix, in sparse form * Pre-trust vector, in sparse form * Pre-trust strength, a floating-point number between 0 and 1 * Error threshold, a floating-point number between 0 and 1 The local trust matrix is required; all others are optional. operationId: compute requestBody: $ref: '#/components/requestBodies/ComputeRequestBody' responses: "200": description: | Successfully computed the EigenTrust scores. The response body refers to the EigenTrust vector. This vector can be sorted in descending order of value (`v`) so as to obtain a trust ranking. content: "application/json": schema: $ref: "#/components/schemas/TrustVectorRef" examples: Simple1: summary: Simple 3-peer example description: | This is the response to the “Simple 3-peer example” request. Peer #2 is the winner with highest trust value, closely followed by peer #0; #1 is the least trusted. value: { "entries": [ { "i": 0, "v": 0.4033293137942772 }, { "i": 1, "v": 0.1707491350775377 }, { "i": 2, "v": 0.4259215511281855 } ], "scheme": "inline", "size": 3 } Simple2: summary: Simple 3-peer example with (unnecessarily) fine epsilon description: | This is the response to the “Simple 3-peer example with (unnecessarily) fine epsilon” request above. Note that the trust values are more or less identical to the previous example, with less than 0.0001% difference, demonstrating the 1e-10 epsilon was an overkill. value: { "entries": [ { "i": 0, "v": 0.40332936981024636 }, { "i": 1, "v": 0.17074910819849826 }, { "i": 2, "v": 0.425921521991256 } ], "scheme": "inline", "size": 3 } "400": $ref: "#/components/responses/InvalidRequest" /compute-with-stats: post: summary: Compute EigenTrust scores, with execution statistics description: | Compute EigenTrust scores using the given inputs. See /compute for details. The only difference is that not just the EigenTrust scores but also statistics and rankings are returned. operationId: computeWithStats requestBody: $ref: '#/components/requestBodies/ComputeRequestBody' responses: "200": $ref: '#/components/responses/ComputeWithStatsResponseOK' "400": $ref: "#/components/responses/InvalidRequest" /local-trust/{id}: put: summary: Update local trust description: | Load and locally cache the local trust from the given local trust reference. operationId: updateLocalTrust parameters: - $ref: "#/components/parameters/LocalTrustIdParam" - name: merge in: query schema: type: boolean description: | Controls behavior if a local trust exists under the same ID. If false (default), the local trust ref contents replaces the existing one under the same ID, if any. If true, the local trust ref contents are merged into the existing one under the same ID. requestBody: description: A local trust ref to load. Can be an inline reference. content: "application/json": schema: $ref: "#/components/schemas/LocalTrustRef" required: true responses: "200": description: The local trust was updated successfully. "201": description: The local trust was created successfully. "400": $ref: "#/components/responses/InvalidRequest" delete: summary: Delete local trust operationId: deleteLocalTrust parameters: - $ref: "#/components/parameters/LocalTrustIdParam" responses: "204": description: The local trust was deleted successfully. "404": description: The local trust does not exist. "400": $ref: "#/components/responses/InvalidRequest" get: summary: Retrieve local trust description: | Return the given locally stored local trust as an inline ref. operationId: getLocalTrust parameters: - $ref: "#/components/parameters/LocalTrustIdParam" responses: "200": description: The requested local trust contents. content: "application/json": schema: $ref: "#/components/schemas/InlineLocalTrust" "404": description: The local trust does not exist. head: summary: Check for existence of local trust description: | Return 204 if the given local trust exists, 404 otherwise. operationId: headLocalTrust parameters: - $ref: "#/components/parameters/LocalTrustIdParam" responses: "204": description: The local trust exists. "404": description: The local trust does not exist. /status: get: summary: Get the health check status operationId: getStatus responses: "200": $ref: "#/components/responses/ServerReady" "500": $ref: "#/components/responses/ServerNotReady" components: parameters: LocalTrustIdParam: summary: Local trust ID description: | `id` denotes the local trust collection in question. name: id in: path required: true schema: $ref: "#/components/schemas/LocalTrustId" schemas: LocalTrustId: description: | Denotes a local trust collection. type: string minLength: 1 LocalTrustRef: description: | refers to a local trust. type: object allOf: - properties: scheme: title: Local trust reference scheme. description: | Local trust reference scheme, akin to URI scheme. type: string enum: - inline - stored - objectstorage required: - scheme - oneOf: - $ref: "#/components/schemas/InlineLocalTrust" - $ref: "#/components/schemas/StoredLocalTrust" - $ref: "#/components/schemas/ObjectStorageLocalTrust" examples: - scheme: inline size: 3 entries: - i: 0 j: 1 v: 1 - i: 0 j: 2 v: 1 - i: 1 j: 2 v: 100 - scheme: inline size: 5 entries: [ ] - scheme: stored id: "3" - scheme: stored id: engagement InlineLocalTrust: description: | Refers to a local trust matrix "inline". Instead of pointing (referencing) to an externally stored local trust, it carries the contents of the local trust matrix within the reference object itself. type: object required: - scheme - size - entries properties: scheme: description: | A fixed string `"inline"`. type: string enum: [ "inline" ] size: description: | Denotes the number of peers in the local trust, i.e. its square dimension. type: integer minimum: 1 entries: description: | Contains the non-zero entries in the local trust matrix. Truster/trustee pairs missing here are assigned zero direct trust, i.e. no trust relationship. type: array items: $ref: "#/components/schemas/InlineLocalTrustEntry" InlineLocalTrustEntry: description: | Represents an entry in the local trust matrix. Denotes that one peer (`i`) places a direct trust in another peer (`j`) by a specific amount (`v`). type: object required: - i - j - v properties: i: description: | Denotes the trusting peer. It is a zero-based index, and must be less than the size (dimension) of the enclosing local trust matrix. type: integer minimum: 0 j: description: | Denotes the trusted peer. It is a zero-based index, and must be less than the size (dimension) of the enclosing local trust matrix. type: integer minimum: 0 v: description: | Represents the (positive) amount of trust placed by peer `i` in peer `j`. type: number format: double minimum: 0 # should really be exclusiveMinimum examples: - i: 0 j: 1 v: 0.5 - i: 1 j: 2 v: 1 StoredLocalTrust: description: | Refers to a local trust stored on the server. Stored local trust is identified with its ID string. type: object required: - scheme - id properties: scheme: description: | A fixed string `"stored"`. type: string enum: [ "stored" ] id: $ref: "#/components/schemas/LocalTrustId" ObjectStorageLocalTrust: description: | Refers to a local trust matrix in a remote object storage service. type: object required: - scheme - url properties: scheme: description: | A fixed string `"objectstorage"`. type: string enum: [ "objectstorage" ] url: description: | URL of the trust matrix file. It must refer to a CSV file, with three columns `i`, `j`, and `v`. Currently the `s3://` URL scheme (AWS S3) is supported. type: string examples: - scheme: objectstorage url: s3://bucket-name/path/to/file.csv TrustVectorRef: description: | Refers to a trust vector. type: object allOf: - properties: scheme: title: Trust vector reference scheme. description: | Trust vector reference scheme, akin to URI scheme. type: string enum: - inline - stored - objectstorage required: - scheme - oneOf: - $ref: "#/components/schemas/InlineTrustVector" - $ref: "#/components/schemas/ObjectStorageTrustVector" InlineTrustVector: description: | Refers to a trust vector "inline". Instead of pointing (referencing) to an externally stored trust vector, it carries the contents of the trust vector within the reference object itself. type: object required: - scheme - size - entries properties: scheme: description: | A fixed string `"inline"` to denote an inline reference. type: string enum: [ "inline" ] size: description: | Denotes the number of peers in the trust vector, i.e. its length. type: integer minimum: 1 entries: description: | Contains the non-zero entries in the trust vector. Peers missing here are assigned zero amount of trust. type: array items: $ref: "#/components/schemas/InlineTrustVectorEntry" examples: - scheme: inline size: 3 entries: - i: 0 v: 0.5 - i: 2 v: 1.0 - scheme: inline size: 5 entries: [ ] InlineTrustVectorEntry: description: | Represents an entry in the local trust matrix. Denotes that a trust is placed in a peer (`i`) by a specific amount (`v`). type: object required: - i - v properties: i: description: | Denotes the peer. It is a zero-based index, and must be less than the length of the enclosing trust vector. type: integer minimum: 0 v: description: | Represents the (positive) amount of trust placed in peer `i`. type: number format: double minimum: 0 # should really be exclusiveMinimum examples: - i: 0 v: 1.0 - i: 2 v: 0.5 ObjectStorageTrustVector: description: | Refers to a trust vector in a remote object storage service. type: object required: - scheme - url properties: scheme: description: | A fixed string `"objectstorage"`. type: string enum: [ "objectstorage" ] url: description: | URL of the trust vector file. It must refer to a CSV file, with two columns `i` and `v`. Currently the `s3://` URL scheme (AWS S3) is supported. type: string examples: - scheme: objectstorage url: s3://bucket-name/path/to/file.csv FlatTailStats: description: Flat-tail algorithm stats and peer ranking. type: object required: - length - threshold - deltaNorm - ranking properties: length: description: | The flat-tail length (say, L, then the last L+1 iterations had the same ranking). This is the number of iterations that could be saved by using flat-tail algorithm (passing flatTail equal to the threshold stat below) while achieving the same result. type: integer minimum: 0 threshold: description: | The suggested minimum threshold parameter (flatTail). It is determined from false flat tails observed. Example: If a ranking pattern ABCDDEEEEFFFFFFFFFF was observed (each letter is a distinct ranking) before epsilon was reached, both DD and EEEE are false flat tails of length 1 and 3 respectively. In this case, Threshold=4 is suggested in order to ignore these false flat tails. type: integer minimum: 0 deltaNorm: description: | The d value as of the head of the last flat-tail. This can be used to fine-tune epsilon even when not using flat-tail algorithm. type: number format: double minimum: 0 ranking: description: | The sorted ranking of peer indices. Peers not found here have zero global trust. type: array items: type: integer minimum: 0 ServerStatus: type: object required: - message properties: message: description: | The server status message. type: string requestBodies: ComputeRequestBody: description: | Parameters for a compute request. required: true content: "application/json": schema: type: object required: - localTrust properties: localTrust: $ref: "#/components/schemas/LocalTrustRef" initialTrust: $ref: "#/components/schemas/TrustVectorRef" preTrust: $ref: "#/components/schemas/TrustVectorRef" alpha: type: number format: double minimum: 0 maximum: 1 default: 0.5 epsilon: type: number format: double minimum: 0 maximum: 1 flatTail: description: | The length of the flat tail (ranking unchanged from previous iteration) that must be seen before terminating the recursion. 0 means a flat tail need not be seen, and the recursion is terminated solely based upon epsilon. type: integer minimum: 0 numLeaders: description: | The number of top-ranking peers to consider for the purpose of flat-tail algorithm. 0 means everyone. type: integer minimum: 0 maxIterations: description: | The maximum number of iterations after which to stop even if other termination criteria are not met. 0 means no limit. type: integer minimum: 0 examples: Simple1: summary: Simple 3-peer example description: | This example passes a local trust of 3 peers (#0–#2), where: - #0 trusts #1, - #0 also trusts #2 – twice as much as #1, - #1 trusts #2, and - #2 trusts #0, i.e. reciprocates #0's trust. #0 and #1 are pre-trusted; #2 is not. #1 is pre-trusted four times more than #0. Pre-trust strength (`alpha`) is 0.1. Iteration threshold (`epsilon`) is absent; then the server uses a default value based upon the number of peers (3). value: localTrust: scheme: "inline" size: 3 entries: - i: 0 j: 1 v: 0.25 - i: 0 j: 2 v: 0.75 - i: 1 j: 2 v: 1.0 - i: 2 j: 0 v: 1.0 preTrust: scheme: "inline" size: 3 entries: - i: 0 v: 0.2 - i: 1 v: 0.8 alpha: 0.1 Simple2: summary: Simple 3-peer example with (unnecessarily) fine epsilon description: | This example is the same as the previous example, except: - Values are scaled differently; - Iteration threshold value (`epsilon`) is given explicitly. That is, the trust levels by the same peer (#0 in this case) do not have to be pre-scaled or canonicalized by the client; only their relative magnitude matters. The explicit iteration threshold (`epsilon=1e-10`, or 0.0000000001) is much finer than the size-based default (`1e-6 / 3`, or 0.000003…), so it will take more iterations than the previous example, but will result in more accurate ranking, especially among lower-ranked peers near the tail. In this example of only 3 peers though, `epsilon=1e-10` is definitely an overkill: The relative ranking among peers #0–#2 will not change after only a few iterations. Developers are encouraged to experiment and tune `epsilon` to their needs, e.g. if only the top few clear winners are needed, a coarser (larger) `epsilon` will likely suffice. value: localTrust: scheme: "inline" size: 3 entries: - i: 0 j: 1 v: 1.0 - i: 0 j: 2 v: 3.0 - i: 1 j: 2 v: 1.0 - i: 2 j: 0 v: 1.0 preTrust: scheme: "inline" size: 3 entries: - i: 0 v: 1.0 - i: 1 v: 4.0 alpha: 0.1 epsilon: 1e-10 MissingLocalTrust: summary: A 3-peer example with missing local trust by a peer description: | In this example, local trust by #2 is missing/unknown. Per EigenTrust algorithm, it is assumed to be the same as the pre-trust. That is, #2 is assumed to trust #0 and #1, trusting #1 four times as much as #0. value: localTrust: scheme: "inline" size: 3 entries: - i: 0 j: 1 v: 1.0 - i: 0 j: 2 v: 3.0 - i: 1 j: 2 v: 1.0 preTrust: scheme: "inline" size: 3 entries: - i: 0 v: 1.0 - i: 1 v: 4.0 alpha: 0.1 MissingLocalTrustAndPreTrust: summary: A 3-peer example with missing local trust and pre-trust description: | In this example, not just #2's local trust but also the pre-trust is missing. Per EigenTrust algorithm, a uniform pre-trust is used if no pre-trust is specified, that is, peers #0–#2 are pre-trusted equally. Then in turn, the missing local trust by #2 is assumed to be the same as the pre-trust, i.e. #2 is assumed to trust everyone equally. value: localTrust: scheme: "inline" size: 3 entries: - i: 0 j: 1 v: 1.0 - i: 0 j: 2 v: 3.0 - i: 1 j: 2 v: 1.0 alpha: 0.1 responses: ComputeWithStatsResponseOK: description: | Successfully computed the EigenTrust scores. The response body contains the computed scores as well as various statistics and rankings (many related to the flat-tail algorithm). content: "application/json": schema: type: object required: - eigenTrust - flatTailStats properties: eigenTrust: $ref: "#/components/schemas/TrustVectorRef" flatTailStats: $ref: "#/components/schemas/FlatTailStats" InvalidRequest: description: | Client sent an invalid request. content: "application/json": schema: type: object required: - message properties: message: description: | Describes the error in a human-readable message. It may be empty. type: string examples: Example1: description: | A parameter validation error. value: message: "cannot load local trust: unknown local trust ref type" ServerReady: description: Server is ready to take requests. content: "application/json": schema: $ref: "#/components/schemas/ServerStatus" ServerNotReady: description: Server is not ready to take requests. content: "application/json": schema: $ref: "#/components/schemas/ServerStatus"