convex.lab.oracle.cvx Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of convex-core Show documentation
Convex core libraries and common utilities
The newest version!
'convex.oracle

(call *registry*
      (register {:description ["API for simple oracle actors that depend on a trusted set of addresses who may provide results."
                               "Default actor used is `convex.trusted-oracle.actor`."
                               "At first, a key (any arbitrary value) is registered via `register`."
                               "When ready, a result for that key is provided via `provide` by a trusted account."
                               "Consumers can fetch data about keys using `data`, check if a result is provided using `finalized?`, and read results using `read`."
                               "Implementating a simple oracle actor requires defining callable function versions of:"
                               "- `(data key)`"
                               "- `(finalized? key)`"
                               "- `(read key)`"
                               "- `(register key result)`"
                               "- `(provide key result)`"]
                 :name        "Trusted oracle API"}))

(import convex.trusted-oracle.actor :as default-actor)

;;;;;;;;;; API

(defn data
  ^{:doc {:description "Returns data registered for `key`."
          :examples    [{:code "(data :foo)"}]
          :signature   [{:params [key]}
                        {:params [actor key]}]}}
  ([key]
   (recur default-actor
        key))
  ([actor key]
    (call actor (data key))))

(defn finalized?
  ^{:callable true
    :doc       {:description "Returns a boolean indicating if a results has been provided for `key`."
                :examples    [{:code "(finalized? :foo)"}]
                :signature   [{:params [key]}
                              {:params [actor key]}]}}
  ([key]
    (recur default-actor key))
  ([actor key]
    (call actor(finalized? key))))

(defn read
  ^{:callable true
    :doc       {:description "Returns the result for `key`."
                :examples    [{:code "(read :foo)"}]
                :signature   [{:params [key]}
                              {:params [actor key]}]}}
  ([key]
    (recur default-actor key))
  ([actor key]
    (call actor 
      (read key))))

(defn register
  ^{:callable true
    :doc       {:description ["Callable function for registering a new oracle key."
                              "Returns true if successful, false if key already exists."
                              "Data should be a map containg at least `:trust`, a set of addresses trusted for using `provide` on that key."
                              "Without `:trust`, a result cannot be delivered."]
                :examples    [{:code "(register :foo {:trust #{*address*}})"}]
                :signature   [{:params [key data]}
                              {:params [actor key data]}]}}
  ([key data]
    (recur default-actor
      key
      data))
  ([actor key data]
    (call actor
      (register key data))))

(defn provide
  ^{:callable true
    :doc       {:description ["Provides a result for a key registered using `register`."
                              "Does not change anything if a resulted has already been provided for that key."
                              "Returns the result associated with that key."]
                :errors      {:STATE "When key does not exist"
                              :TRUST "When caller is untrusted"}
                :examples    [{:code "(provide :foo 42)"}]
                :signature   [{:params [key result]}
                              {:params [actor key result]}]}}
  ([key result]
   (provide default-actor
            key
            result))
  ([actor key result]
    (call actor
      (provide key result))))