mirror of
https://github.com/codex-storage/nim-codex.git
synced 2025-01-09 20:45:38 +00:00
ccf349bd14
* [marketplace] reservations module - add de/serialization for Availability - add markUsed/markUnused in persisted availability - add query for unused - add reserve/release - reservation module tests - split ContractInteractions into client contracts and host contracts - remove reservations start/stop as the repo start/stop is being managed by the node - remove dedicated reservations metadata store and use the metadata store from the repo instead - Split ContractInteractions into: - ClientInteractions (with purchasing) - HostInteractions (with sales and proving) - compilation fix for nim 1.2 [repostore] fix started flag, add tests [marketplace] persist slot index For loading the sales state from chain, the slot index was not previously persisted in the contract. Will retrieve the slot index from the contract when the sales state is loaded. * Revert repostore changes In favour of separate PR https://github.com/status-im/nim-codex/pull/374. * remove warnings * clean up * tests: stop repostore during teardown * change constructor type identifier Change Contracts constructor to accept Contracts type instead of ContractInteractions. * change constructor return type to Result instead of Option * fix and split interactions tests * clean up, fix tests * find availability by slot id * remove duplication in host/client interactions * add test for finding availability by slotId * log instead of raiseAssert when failed to mark availability as unused * move to SaleErrored state instead of raiseAssert * remove unneeded reverse It appears that order is not preserved in the repostore, so reversing does not have the intended effect here. * update open api spec for potential rest endpoint errors * move functions about available bytes to repostore * WIP: reserve and release availabilities as needed WIP: not tested yet Availabilities are marked as used when matched (just before downloading starts) so that future matching logic does not match an availability currently in use. As the download progresses, batches of blocks are written to disk, and the equivalent bytes are released from the reservation module. The size of the availability is reduced as well. During a reserve or release operation, availability updates occur after the repo is manipulated. If the availability update operation fails, the reserve or release is rolled back to maintain correct accounting of bytes. Finally, once download completes, or if an error occurs, the availability is marked as unused so future matching can occur. * delete availability when all bytes released * fix tests + cleanup * remove availability from SalesContext callbacks Availability is no longer used past the SaleDownloading state in the state machine. Cleanup of Availability (marking unused) is handled directly in the SaleDownloading state, and no longer in SaleErrored or SaleFinished. Likewise, Availabilities shouldn’t need to be handled on node restart. Additionally, Availability was being passed in SalesContext callbacks, and now that Availability is only used temporarily in the SaleDownloading state, Availability is contextually irrelevant to the callbacks, except in OnStore possibly, though it was not being consumed. * test clean up * - remove availability from callbacks and constructors from previous commit that needed to be removed (oopsie) - fix integration test that checks availabilities - there was a bug fixed that crashed the node due to a missing `return success` in onStore - the test was fixed by ensuring that availabilities are remaining on the node, and the size has been reduced - change Availability back to non-ref object and constructor back to init - add trace logging of all state transitions in state machine - add generally useful trace logging * fixes after rebase 1. Fix onProve callbacks 2. Use Slot type instead of tuple for retrieving active slot. 3. Bump codex-contracts-eth that exposes getActivceSlot call. * swap contracts branch to not support slot collateral Slot collateral changes in the contracts require further changes in the client code, so we’ll skip those changes for now and add in a separate commit. * modify Interactions and Deployment constructors - `HostInteractions` and `ClientInteractions` constructors were simplified to take a contract address and no overloads - `Interactions` prepared simplified so there are no overloads - `Deployment` constructor updated so that it takes an optional string parameter, instead `Option[string]` * Move `batchProc` declaration `batchProc` needs to be consumed by both `node` and `salescontext`, and they can’t reference each other as it creates a circular dependency. * [reservations] rename `available` to `hasAvailable` * [reservations] default error message to inner error msg * add SaleIngored state When a storage request is handled but the request does match availabilities, the sales agent machine is sent to the SaleIgnored state. In addition, the agent is constructed in a way that if the request is ignored, the sales agent is removed from the list of active agents being tracked in the sales module.
410 lines
11 KiB
YAML
410 lines
11 KiB
YAML
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
|
|
|
|
Cid:
|
|
type: string
|
|
description: Content Identifier as specified at https://github.com/multiformats/cid
|
|
example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N
|
|
|
|
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 hexadecimal string
|
|
|
|
ProofProbability:
|
|
type: string
|
|
description: How often storage proofs are required as hexadecimal 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
|
|
required:
|
|
- size
|
|
- minPrice
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Hexadecimal identifier of the availability
|
|
size:
|
|
type: string
|
|
description: Size of available storage in bytes as hexadecimal string
|
|
duration:
|
|
$ref: "#/components/schemas/Duration"
|
|
minPrice:
|
|
type: string
|
|
description: Minimum price to be paid (in amount of tokens) as hexadecimal string
|
|
|
|
StorageRequestCreation:
|
|
type: object
|
|
required:
|
|
- reward
|
|
- duration
|
|
- proofProbability
|
|
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
|
|
|
|
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 hexadecimal 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:
|
|
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"
|
|
|
|
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
|
|
|
|
"/download/{cid}":
|
|
get:
|
|
summary: "Download a file from the node in a streaming manner"
|
|
tags: [ Data ]
|
|
operationId: download
|
|
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
|
|
|
|
"/upload":
|
|
post:
|
|
summary: "Upload a file in a streaming manner"
|
|
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
|
|
|
|
"/sales/availability":
|
|
get:
|
|
summary: "Returns storage that is for sale"
|
|
tags: [ Marketplace ]
|
|
operationId: getsOfferedStorage
|
|
responses:
|
|
"200":
|
|
description: Retrieved content specified by CID
|
|
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/SalesAvailability"
|
|
responses:
|
|
"200":
|
|
description: Created storage availability
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SalesAvailability"
|
|
"500":
|
|
description: Error reserving availablility
|
|
"503":
|
|
description: Sales are 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:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Purchase"
|
|
"400":
|
|
description: Invalid or missing Purchase ID
|
|
"404":
|
|
description: Purchase not found
|
|
"503":
|
|
description: Purchasing is 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 hexadecimal string
|
|
"400":
|
|
description: Invalid or missing Request ID
|
|
"404":
|
|
description: Request ID 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"
|