diff --git a/ProjectPlugins/CodexPlugin/CodexPlugin.csproj b/ProjectPlugins/CodexPlugin/CodexPlugin.csproj index 19c3b60..47899a0 100644 --- a/ProjectPlugins/CodexPlugin/CodexPlugin.csproj +++ b/ProjectPlugins/CodexPlugin/CodexPlugin.csproj @@ -7,7 +7,23 @@ + + + + + + + + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + diff --git a/ProjectPlugins/CodexPlugin/openapi.yaml b/ProjectPlugins/CodexPlugin/openapi.yaml new file mode 100644 index 0000000..adfc887 --- /dev/null +++ b/ProjectPlugins/CodexPlugin/openapi.yaml @@ -0,0 +1,717 @@ +openapi: 3.0.3 + +info: + version: 0.0.1 + title: Codex API + description: "List of endpoints and interfaces available to Codex API users" + +security: + - { } + +components: + schemas: + MultiAddress: + type: string + description: Address of node as specified by the multi-address specification https://multiformats.io/multiaddr/ + example: /ip4/127.0.0.1/tcp/8080 + + PeerId: + type: string + description: Peer Identity reference as specified at https://docs.libp2p.io/concepts/fundamentals/peers/ + example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N + + Id: + type: string + description: 32bits identifier encoded in hex-decimal string. + example: 0x... + + BigInt: + type: string + description: Integer represented as decimal string + + Cid: + type: string + description: Content Identifier as specified at https://github.com/multiformats/cid + example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N + + SlotId: + type: string + description: Keccak hash of the abi encoded tuple (RequestId, slot index) + example: 268a781e0db3f7cf36b18e5f4fdb7f586ec9edd08e5500b17c0e518a769f114a + + LogLevel: + type: string + description: "One of the log levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL" + example: DEBUG + + EthereumAddress: + type: string + description: Address of Ethereum address + + Reward: + type: string + description: The maximum amount of tokens paid per second per slot to hosts the client is willing to pay + + Duration: + type: string + description: The duration of the request in seconds as decimal string + + ProofProbability: + type: string + description: How often storage proofs are required as decimal string + + Expiry: + type: string + description: A timestamp as seconds since unix epoch at which this request expires if the Request does not find requested amount of nodes to host the data. + default: 10 minutes + + ErasureParameters: + type: object + properties: + totalChunks: + type: number + + PoRParameters: + description: Parameters for Proof of Retrievability + type: object + properties: + u: + type: string + publicKey: + type: string + name: + type: string + + Content: + type: object + description: Parameters specifying the content + properties: + cid: + $ref: "#/components/schemas/Cid" + erasure: + $ref: "#/components/schemas/ErasureParameters" + por: + $ref: "#/components/schemas/PoRParameters" + + DebugInfo: + type: object + properties: + id: + $ref: "#/components/schemas/PeerId" + addrs: + type: array + items: + $ref: "#/components/schemas/MultiAddress" + repo: + type: string + description: Path of the data repository where all nodes data are stored + spr: + type: string + description: Signed Peer Record to advertise DHT connection information + + SalesAvailability: + type: object + properties: + id: + $ref: "#/components/schemas/Id" + totalSize: + type: string + description: Total size of availability's storage in bytes as decimal string + duration: + $ref: "#/components/schemas/Duration" + minPrice: + type: string + description: Minimum price to be paid (in amount of tokens) as decimal string + maxCollateral: + type: string + description: Maximum collateral user is willing to pay per filled Slot (in amount of tokens) as decimal string + + SalesAvailabilityREAD: + allOf: + - $ref: "#/components/schemas/SalesAvailability" + - type: object + properties: + freeSize: + type: string + description: Unused size of availability's storage in bytes as decimal string + + SalesAvailabilityCREATE: + allOf: + - $ref: "#/components/schemas/SalesAvailability" + - required: + - totalSize + - minPrice + - maxCollateral + - duration + + Slot: + type: object + properties: + id: + $ref: "#/components/schemas/SlotId" + request: + $ref: "#/components/schemas/StorageRequest" + slotIndex: + type: string + description: Slot Index as hexadecimal string + + Reservation: + type: object + properties: + id: + $ref: "#/components/schemas/Id" + availabilityId: + $ref: "#/components/schemas/Id" + size: + $ref: "#/components/schemas/BigInt" + requestId: + $ref: "#/components/schemas/Id" + slotIndex: + type: string + description: Slot Index as hexadecimal string + + StorageRequestCreation: + type: object + required: + - reward + - duration + - proofProbability + - collateral + - expiry + properties: + duration: + $ref: "#/components/schemas/Duration" + reward: + $ref: "#/components/schemas/Reward" + proofProbability: + $ref: "#/components/schemas/ProofProbability" + nodes: + type: number + description: Minimal number of nodes the content should be stored on + default: 1 + tolerance: + type: number + description: Additional number of nodes on top of the `nodes` property that can be lost before pronouncing the content lost + default: 0 + collateral: + type: string + description: Number as decimal string that represents how much collateral is asked from hosts that wants to fill a slots + expiry: + type: string + description: Number as decimal string that represents expiry time of the request (in unix timestamp) + + StorageAsk: + type: object + required: + - reward + properties: + slots: + type: number + description: Number of slots (eq. hosts) that the Request want to have the content spread over + slotSize: + type: string + description: Amount of storage per slot (in bytes) as decimal string + duration: + $ref: "#/components/schemas/Duration" + proofProbability: + $ref: "#/components/schemas/ProofProbability" + reward: + $ref: "#/components/schemas/Reward" + maxSlotLoss: + type: number + description: Max slots that can be lost without data considered to be lost + + StorageRequest: + type: object + properties: + id: + type: string + description: Request ID + client: + $ref: "#/components/schemas/EthereumAddress" + ask: + $ref: "#/components/schemas/StorageAsk" + content: + $ref: "#/components/schemas/Content" + expiry: + $ref: "#/components/schemas/Expiry" + nonce: + type: string + description: Random data + + Purchase: + type: object + properties: + state: + type: string + description: Description of the Request's state + error: + type: string + description: If Request failed, then here is presented the error message + request: + $ref: "#/components/schemas/StorageRequest" + + DataList: + type: object + properties: + content: + type: array + items: + $ref: "#/components/schemas/DataItem" + + DataItem: + type: object + properties: + cid: + $ref: "#/components/schemas/Cid" + manifest: + $ref: "#/components/schemas/ManifestItem" + + ManifestItem: + type: object + properties: + rootHash: + $ref: "#/components/schemas/Cid" + description: "Root hash of the content" + originalBytes: + type: number + description: "Length of original content in bytes" + blockSize: + type: number + description: "Size of blocks" + protected: + type: boolean + description: "Indicates if content is protected by erasure-coding" + + Space: + type: object + properties: + totalBlocks: + type: number + description: "Number of blocks stored by the node" + quotaMaxBytes: + type: number + description: "Maximum storage space used by the node" + quotaUsedBytes: + type: number + description: "Amount of storage space currently in use" + quotaReservedBytes: + type: number + description: "Amount of storage space reserved" + +servers: + - url: "http://localhost:8080/api/codex/v1" + +tags: + - name: Marketplace + description: Marketplace information and operations + - name: Data + description: Data operations + - name: Node + description: Node management + - name: Debug + description: Debugging configuration + +paths: + "/connect/{peerId}": + get: + summary: "Connect to a peer" + description: | + If `addrs` param is supplied, it will be used to dial the peer, otherwise the `peerId` is used + to invoke peer discovery, if it succeeds the returned addresses will be used to dial. + tags: [ Node ] + operationId: connectPeer + parameters: + - in: path + name: peerId + required: true + schema: + $ref: "#/components/schemas/PeerId" + description: Peer that should be dialed. + - in: query + name: addrs + schema: + type: array + nullable: true + items: + $ref: "#/components/schemas/MultiAddress" + description: | + If supplied, it will be used to dial the peer. + The address has to target the listening address of the peer, + which is specified with the `--listen-addrs` CLI flag. + + responses: + "200": + description: Successfully connected to peer + "400": + description: Peer either not found or was not possible to dial + + "/data": + get: + summary: "Lists manifest CIDs stored locally in node." + tags: [ Data ] + operationId: listData + responses: + "200": + description: Retrieved list of content CIDs + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DataList" + "400": + description: Invalid CID is specified + "404": + description: Content specified by the CID is not found + "500": + description: Well it was bad-bad + post: + summary: "Upload a file in a streaming manner. Once finished, the file is stored in the node and can be retrieved by any node in the network using the returned CID." + tags: [ Data ] + operationId: upload + requestBody: + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + "200": + description: CID of uploaded file + content: + text/plain: + schema: + type: string + "500": + description: Well it was bad-bad and the upload did not work out + + "/data/{cid}": + get: + summary: "Download a file from the local node in a streaming manner. If the file is not available locally, a 404 is returned." + tags: [ Data ] + operationId: downloadLocal + parameters: + - in: path + name: cid + required: true + schema: + $ref: "#/components/schemas/Cid" + description: File to be downloaded. + + responses: + "200": + description: Retrieved content specified by CID + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + description: Invalid CID is specified + "404": + description: Content specified by the CID is unavailable locally + "500": + description: Well it was bad-bad + + "/data/{cid}/network": + get: + summary: "Download a file from the network in a streaming manner. If the file is not available locally, it will be retrieved from other nodes in the network if able." + tags: [ Data ] + operationId: downloadNetwork + parameters: + - in: path + name: cid + required: true + schema: + $ref: "#/components/schemas/Cid" + description: "File to be downloaded." + responses: + "200": + description: Retrieved content specified by CID + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + description: Invalid CID is specified + "404": + description: Content specified by the CID is not found + "500": + description: Well it was bad-bad + + "/space": + get: + summary: "Gets a summary of the storage space allocation of the node." + tags: [ Data ] + operationId: space + responses: + "200": + description: "Summary of storage allocation" + content: + application/json: + schema: + $ref: "#/components/schemas/Space" + + "500": + description: "It's not working as planned" + + "/sales/slots": + get: + summary: "Returns active slots" + tags: [ Marketplace ] + operationId: getActiveSlots + responses: + "200": + description: Retrieved active slots + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Slot" + + "503": + description: Sales are unavailable + + "/sales/slots/{slotId}": + get: + summary: "Returns active slot with id {slotId} for the host" + tags: [ Marketplace ] + operationId: getActiveSlotById + parameters: + - in: path + name: slotId + required: true + schema: + $ref: "#/components/schemas/Cid" + description: File to be downloaded. + responses: + "200": + description: Retrieved active slot + content: + application/json: + schema: + $ref: "#/components/schemas/Slot" + + "400": + description: Invalid or missing SlotId + + "404": + description: Host is not in an active sale for the slot + + "503": + description: Sales are unavailable + + "/sales/availability": + get: + summary: "Returns storage that is for sale" + tags: [ Marketplace ] + operationId: getOfferedStorage + responses: + "200": + description: Retrieved storage availabilities of the node + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/SalesAvailability" + "500": + description: Error getting unused availabilities + "503": + description: Sales are unavailable + + post: + summary: "Offers storage for sale" + operationId: offerStorage + tags: [ Marketplace ] + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SalesAvailabilityCREATE" + responses: + "201": + description: Created storage availability + content: + application/json: + schema: + $ref: "#/components/schemas/SalesAvailabilityREAD" + "400": + description: Invalid data input + "422": + description: Not enough node's storage quota available + "500": + description: Error reserving availability + "503": + description: Sales are unavailable + "/sales/availability/{id}": + patch: + summary: "Updates availability" + description: | + The new parameters will be only considered for new requests. + Existing Requests linked to this Availability will continue as is. + operationId: updateOfferedStorage + tags: [ Marketplace ] + parameters: + - in: path + name: id + required: true + schema: + type: string + description: ID of Availability + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SalesAvailability" + responses: + "204": + description: Availability successfully updated + "400": + description: Invalid data input + "404": + description: Availability not found + "422": + description: Not enough node's storage quota available + "500": + description: Error reserving availability + "503": + description: Sales are unavailable + + "/sales/availability/{id}/reservations": + patch: + summary: "Get availability's reservations" + description: Return's list of Reservations for ongoing Storage Requests that the node hosts. + operationId: getReservations + tags: [ Marketplace ] + parameters: + - in: path + name: id + required: true + schema: + type: string + description: ID of Availability + responses: + "200": + description: Retrieved storage availabilities of the node + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Reservation" + "400": + description: Invalid Availability ID + "404": + description: Availability not found + "500": + description: Error getting reservations + "503": + description: Sales are unavailable + + "/storage/request/{cid}": + post: + summary: "Creates a new Request for storage" + tags: [ Marketplace ] + operationId: createStorageRequest + parameters: + - in: path + name: cid + required: true + schema: + $ref: "#/components/schemas/Cid" + description: CID of the uploaded data that should be stored + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/StorageRequestCreation" + responses: + "200": + description: Returns the Request ID as decimal string + "400": + description: Invalid or missing Request ID + "404": + description: Request ID not found + "503": + description: Purchasing is unavailable + + "/storage/purchases": + get: + summary: "Returns list of purchase IDs" + tags: [ Marketplace ] + operationId: getPurchases + responses: + "200": + description: Gets all purchase IDs stored in node + content: + application/json: + schema: + type: array + items: + type: string + "503": + description: Purchasing is unavailable + + "/storage/purchases/{id}": + get: + summary: "Returns purchase details" + tags: [ Marketplace ] + operationId: getPurchase + parameters: + - in: path + name: id + required: true + schema: + type: string + description: Hexadecimal ID of a Purchase + responses: + "200": + description: Purchase details + content: + application/json: + schema: + $ref: "#/components/schemas/Purchase" + "400": + description: Invalid or missing Purchase ID + "404": + description: Purchase not found + "503": + description: Purchasing is unavailable + + "/debug/chronicles/loglevel": + post: + summary: "Set log level at run time" + tags: [ Debug ] + operationId: setDebugLogLevel + + parameters: + - in: query + name: level + required: true + schema: + $ref: "#/components/schemas/LogLevel" + + responses: + "200": + description: Successfully log level set + "400": + description: Invalid or missing log level + "500": + description: Well it was bad-bad + + "/debug/info": + get: + summary: "Gets node information" + operationId: getDebugInfo + tags: [ Debug ] + responses: + "200": + description: Node's information + content: + application/json: + schema: + $ref: "#/components/schemas/DebugInfo"