Essential Rest Server

一个轻量级的 HTTP REST 服务器，旨在方便与 Essential 协议交互。该服务器充当客户端与 Essential 声明式协议之间的接口，允许轻松集成和 Essential 生态系统中的通信。

运行服务器

Nix

内存数据库

nix run .#essential-rest-server

Rqlite

在已运行 rqlite 服务器的环境中

nix run .#essential-rest-server -- --db rqlite -r ${server_address}

运行 rqlite 服务器和 essential-rest-server

nix run .#server-with-rqlite -- /path/to/rqlite/data/dir

Cargo

cargo run -p essential-rest-server --release -- --help

API

请注意，这个 API 很可能改变，因为它目前是一个 WIP。

POST /deploy-contract

请求体：JSON 格式的 SignedPredicates
响应：JSON 格式的 ContentAddress

示例

curl --http2-prior-knowledge -X POST -H "Content-Type: application/json" \
    -d '{"contract":{"predicates":[{"state_read":[],"constraints":[],"directive":"Satisfy"}],"salt":"0000000000000000000000000000000000000000000000000000000000000000"},"signature":"D7B64C906BD6CA28DB9F02F21A295A96E134C13DB31F86E6A8A9BA5680A073D61ED8039FA47C26F24D5ED08808854332723BA274D9E0BDE5276D79DE82C25C9901"}' \
    https://127.0.0.1:59498/deploy-contract

GET /get-contract/:address

参数

• :address = [u8; 32] 作为十六进制字符串。这是合约的内容地址。

响应：JSON 格式的 Option<SignedContract>

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" https://127.0.0.1:59498/get-contract/EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236

GET /get-predicate/:contract/:address

参数

• :contract = [u8; 32] 作为十六进制字符串。这是合约的内容地址。
• :address = [u8; 32] 作为十六进制字符串。这是谓词的内容地址。

返回值: Option<Predicate> 作为 JSON

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" https://127.0.0.1:59498/get-predicate/EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236/709E80C88487A2411E1EE4DFB9F22A861492D20C4765150C0C794ABD70F8147C

GET /list-contracts

查询参数

• 可选 { start: u64, end: u64 }。这是列出合约的时间范围。包括起始时间，不包括结束时间。
• 可选 { page: u64 }。这是列出合约的页码。默认为 0。

返回值: Vec<Contract> 作为 JSON

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/list-contracts?start=0&end=1&page=0"

GET /subscribe-contracts

此 API 是服务器发送事件 API。
这允许您订阅新部署的合约。查询参数

• 可选 { start: u64 }。这是开始返回合约的时间。
• 可选 { page: u64 }。这是返回合约的页码。默认为 0。

返回值: Stream<Item = Result<Contract>> 其中结果和合约都是 JSON 格式。

示例

curl --http2-prior-knowledge -N -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/subscribe-blocks?start=0&end=1&page=0&block=0"

POST /submit-solution

请求体: Solution 作为 JSON
返回值: Hash 作为 JSON

示例

curl --http2-prior-knowledge -X POST -H "Content-Type: application/json" -d '{"data":[{"predicate_to_solve":{"contract":"EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236","predicate":"709E80C88487A2411E1EE4DFB9F22A861492D20C4765150C0C794ABD70F8147C"},"decision_variables":[],"transient_data":[],"state_mutations":[]}]}' https://127.0.0.1:59498/submit-solution

GET /list-solutions-pool

查询参数

• 可选 { page: u64 }。这是列出合约的页码。默认为 0。

返回值: Vec<Solution> 作为 JSON

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/list-solutions-pool" 

GET /query-state/:address/:key

参数

• :address = [u8; 32] 作为十六进制字符串。这是合约的内容地址。
• :key = Vec<u8> 作为十六进制字符串。这是状态的键。

返回值: Option<Word> 作为 JSON

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" https://127.0.0.1:59498/query-state/EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236/00

GET /list-blocks

查询参数

• 可选 { start: u64, end: u64 }。这是列出块的时问范围。包括起始时间，不包括结束时间。
• 可选 { page: u64 }。这是列出块的页码。默认为 0。
• 可选 { block: u64 }。这是列出块的块号。

返回: Vec<Block> 作为 JSON

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/list-blocks?start=0&end=1&page=0&block=0"

GET /subscribe-blocks

此 API 是服务器发送事件 API。
这允许您订阅新块，当它们被添加到链中时。

• 可选 { start: u64 }。这是开始返回块的时间。
• 可选 { page: u64 }。这是要返回块的页码。默认为 0。
• 可选 { block: u64 }。这是要返回块的块号。

返回: Stream<Item = Result<Block>> 其中结果和块是 JSON。

示例

curl --http2-prior-knowledge -N -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/subscribe-blocks?start=0&end=1&page=0&block=0"

GET /solution-outcome/:hash

参数

• :hash = [u8; 32] 作为十六进制字符串。这是解决方案的哈希。

返回: Vec<SolutionOutcome> 作为 JSON

pub enum SolutionOutcome {
    Success(u64),
    Fail(String),
}

示例

curl --http2-prior-knowledge -X GET -H "Content-Type: application/json" "https://127.0.0.1:59498/solution-outcome/11CAD716457F6D6524EF84FBA73D11BB5E18658F6EE72EBAC8A14323B37A68FC

POST /check-solution

检查解决方案与已部署合约是否一致，不改变状态。
这是解决方案的试运行。
请求体: Solution 作为 JSON
返回: CheckSolutionOutput 作为 JSON

pub struct CheckSolutionOutput {
    pub utility: f64,
    pub gas: u64,
}

示例

curl --http2-prior-knowledge -X POST -H "Content-Type: application/json" -d '{"data":[{"predicate_to_solve":{"contract":"EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236","predicate":"709E80C88487A2411E1EE4DFB9F22A861492D20C4765150C0C794ABD70F8147C"},"decision_variables":[],"transient_data":[],"state_mutations":[]}]}' https://127.0.0.1:59498/check-solution

POST /check-solution-with-contracts

检查解决方案与所有合约是否一致，不改变状态。
这是解决方案的试运行。
正文: CheckSolution 作为 JSON \

struct CheckSolution {
    solution: Solution,
    contract: Contract,
}

返回: CheckSolutionOutput 作为 JSON

pub struct CheckSolutionOutput {
    pub utility: f64,
    pub gas: u64,
}

示例

curl --http2-prior-knowledge -X POST -H "Content-Type: application/json" -d '{"solution":{"data":[{"predicate_to_solve":{"contract":"EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236","predicate":"709E80C88487A2411E1EE4DFB9F22A861492D20C4765150C0C794ABD70F8147C"},"decision_variables":[],"transient_data":[],"state_mutations":[]}]},"contracts":[{"predicates":[{"state_read":[],"constraints":[],"directive":"Satisfy"}],"salt":"0000000000000000000000000000000000000000000000000000000000000000"}]}' https://127.0.0.1:59498/check-solution-with-contracts

POST /query-state-reads

使用状态读取程序在状态上运行查询，
这允许您使用您的 pint 程序的状态读取部分来查询状态。
这对于调试时获取解决方案的前置状态也很有用。
正文: QueryStateReads 作为 JSON \

pub struct QueryStateReads {
    pub state_read: Vec<StateReadBytecode>,
    pub index: SolutionDataIndex,
    pub solution: Solution,
    pub request_type: StateReadRequestType,
}

返回: QueryStateReadsOutput 作为 JSON

pub enum QueryStateReadsOutput {
    Reads(BTreeMap<ContentAddress, Vec<(Key, Value)>>),
    Slots(Slots),
    All(BTreeMap<ContentAddress, Vec<(Key, Value)>>, Slots),
    Failure(String),
}

这些类型定义在此存储库中 essential-server-types 载体的 essential-server-types。
示例

curl --http2-prior-knowledge -X POST -H "Content-Type: application/json" -d '{"state_read":[],"index":0,"solution":{"data":[{"predicate_to_solve":{"contract":"EE3F28F3E0396EEE29613AF73E65D2BA52AE606E5FFD14D5EBD02A0FB5B88236","predicate":"709E80C88487A2411E1EE4DFB9F22A861492D20C4765150C0C794ABD70F8147C"},"decision_variables":[],"transient_data":[],"state_mutations":[]}]},"request_type":{"All":"All"}}' https://127.0.0.1:59498/query-state-reads