-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
34 lines (27 loc) · 23.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<!DOCTYPE html><html class="default" lang="en"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@0glabs/0g-serving-broker - v0.2.0</title><meta name="description" content="Documentation for @0glabs/0g-serving-broker"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@0glabs/0g-serving-broker - v0.2.0</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@0glabs/0g-serving-broker - v0.2.0</h1></div><div class="tsd-panel tsd-typography"><a id="md:0g-serving-broker-documentation" class="tsd-anchor"></a><h1 class="tsd-anchor-link">0G Serving Broker Documentation<a href="#md:0g-serving-broker-documentation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><a id="md:overview" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Overview<a href="#md:overview" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This document provides an overview of the 0G Serving Broker, including setup and usage instructions.</p>
<a id="md:setup-and-usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Setup and Usage<a href="#md:setup-and-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>To integrate the 0G Serving Broker into your project, follow these steps</p>
<a id="md:step-1-install-the-dependency" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Step 1: Install the dependency<a href="#md:step-1-install-the-dependency" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>To get started, you need to install the <code>@0glabs/0g-serving-broker</code> package:</p>
<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@0glabs/0g-serving-broker</span>
</code><button type="button">Copy</button></pre>
<a id="md:step-2-initialize-a-broker-instance" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Step 2: Initialize a Broker Instance<a href="#md:step-2-initialize-a-broker-instance" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The broker instance is initialized with a <code>signer</code>. This signer is an instance that implements the ethers.js Signer interface and is used to sign transactions for a specific Ethereum account. Developers can create this instance using their private key via the ethers.js library or use a wallet framework tool like <a href="https://wagmi.sh/react/guides/ethers" target="_blank" class="external">wagmi</a> to initialize the signer.</p>
<pre><code class="typescript"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">createZGServingNetworkBroker</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">'@0glabs/0g-serving-broker'</span><br/><br/><span class="hl-5">/**</span><br/><span class="hl-5"> * createZGServingNetworkBroker is used to initialize ZGServingUserBroker</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">signer</span><span class="hl-5"> - Signer from ethers.js.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">contractAddress</span><span class="hl-5"> - 0G Serving contract address, use default address if not provided.</span><br/><span class="hl-5"> * </span><span class="hl-6">@returns</span><span class="hl-5"> broker instance.</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if the broker cannot be initialized.</span><br/><span class="hl-5"> */</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">broker</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">createZGServingNetworkBroker</span><span class="hl-1">(</span><span class="hl-4">signer</span><span class="hl-1">)</span>
</code><button type="button">Copy</button></pre>
<a id="md:step-3-list-available-services" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Step 3: List Available Services<a href="#md:step-3-list-available-services" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>You can retrieve a list of services offered:</p>
<pre><code class="typescript"><span class="hl-5">/**</span><br/><span class="hl-5"> * Retrieves a list of services from the contract.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@returns</span><span class="hl-5"> </span><span class="hl-8">{Promise<ServiceStructOutput[]>}</span><span class="hl-5"> A promise that resolves to an array of ServiceStructOutput objects.</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if the service list cannot be retrieved.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * type ServiceStructOutput = {</span><br/><span class="hl-5"> * provider: string; // Address of the provider</span><br/><span class="hl-5"> * name: string; // Name of the service</span><br/><span class="hl-5"> * serviceType: string;</span><br/><span class="hl-5"> * url: string;</span><br/><span class="hl-5"> * inputPrice: bigint;</span><br/><span class="hl-5"> * outputPrice: bigint;</span><br/><span class="hl-5"> * updatedAt: bigint;</span><br/><span class="hl-5"> * model: string;</span><br/><span class="hl-5"> * };</span><br/><span class="hl-5"> */</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">services</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">broker</span><span class="hl-1">.</span><span class="hl-0">listService</span><span class="hl-1">()</span>
</code><button type="button">Copy</button></pre>
<a id="md:step-4-manage-accounts" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Step 4: Manage Accounts<a href="#md:step-4-manage-accounts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Before using the provider's services, you need to create an account specifically for the chosen provider. The provider checks the account balance before responding to requests. If the balance is insufficient, the request will be denied.</p>
<a id="md:41-create-an-account" class="tsd-anchor"></a><h4 class="tsd-anchor-link">4.1 Create an Account<a href="#md:41-create-an-account" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-5">/**</span><br/><span class="hl-5"> * Adds a new account to the contract.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * This function performs the following steps:</span><br/><span class="hl-5"> * 1. Creates and stores a key pair for the given provider address.</span><br/><span class="hl-5"> * 2. Adds the account to the contract using the provider address, the generated public pair, and the specified balance.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">providerAddress</span><span class="hl-5"> - The address of the provider for whom the account is being created.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">balance</span><span class="hl-5"> - The initial balance to be assigned to the new account.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if the account creation fails.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@remarks</span><br/><span class="hl-5"> * When creating an account, a key pair is also created to sign the request.</span><br/><span class="hl-5"> */</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">broker</span><span class="hl-1">.</span><span class="hl-0">addAccount</span><span class="hl-1">(</span><span class="hl-4">providerAddress</span><span class="hl-1">, </span><span class="hl-4">balance</span><span class="hl-1">)</span>
</code><button type="button">Copy</button></pre>
<a id="md:42-deposit-funds-into-the-account" class="tsd-anchor"></a><h4 class="tsd-anchor-link">4.2 Deposit Funds into the Account<a href="#md:42-deposit-funds-into-the-account" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-5">/**</span><br/><span class="hl-5"> * Deposits a specified amount of funds into the given account.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-8">{string}</span><span class="hl-5"> </span><span class="hl-4">account</span><span class="hl-5"> - The account identifier where the funds will be deposited.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-8">{string}</span><span class="hl-5"> </span><span class="hl-4">amount</span><span class="hl-5"> - The amount of funds to be deposited.</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if the deposit fails.</span><br/><span class="hl-5"> */</span><br/><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">broker</span><span class="hl-1">.</span><span class="hl-0">depositFund</span><span class="hl-1">(</span><span class="hl-4">providerAddress</span><span class="hl-1">, </span><span class="hl-4">amount</span><span class="hl-1">)</span>
</code><button type="button">Copy</button></pre>
<a id="md:step-5-use-the-providers-services" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Step 5: Use the Provider's Services<a href="#md:step-5-use-the-providers-services" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><a id="md:51-process-requests" class="tsd-anchor"></a><h4 class="tsd-anchor-link">5.1 Process Requests<a href="#md:51-process-requests" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>Requests to 0G Serving must include specific headers with signature and fee information. Only valid requests will be processed by the provider. The <code>processRequest</code> function generates these headers.</p>
<pre><code class="typescript"><span class="hl-5">/**</span><br/><span class="hl-5"> * processRequest generates billing-related headers for the request</span><br/><span class="hl-5"> * when the user uses the provider service.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * In the 0G Serving system, a request with valid billing headers</span><br/><span class="hl-5"> * is considered a settlement proof and will be used by the provider</span><br/><span class="hl-5"> * for contract settlement.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">providerAddress</span><span class="hl-5"> - The address of the provider.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">svcName</span><span class="hl-5"> - The name of the service.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">content</span><span class="hl-5"> - The content being billed. For example, in a chatbot service, it is the text input by the user.</span><br/><span class="hl-5"> * </span><span class="hl-6">@returns</span><span class="hl-5"> headers. Records information such as the request fee and user signature.</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if errors occur during the processing of the request.</span><br/><span class="hl-5"> */</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">headers</span><span class="hl-1"> = </span><span class="hl-4">broker</span><span class="hl-1">.</span><span class="hl-4">requestProcessor</span><span class="hl-1">.</span><span class="hl-0">processRequest</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-4">providerAddress</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-4">serviceName</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-4">content</span><br/><span class="hl-1">)</span>
</code><button type="button">Copy</button></pre>
<a id="md:52-process-responses" class="tsd-anchor"></a><h4 class="tsd-anchor-link">5.2 Process Responses<a href="#md:52-process-responses" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>After receiving a response from a provider's service, use <code>processResponse</code> to extract necessary information from the response and records it in localStorage for generating billing headers for subsequent requests.</p>
<p>Additionally, if the service is verifiable, input the chat ID from the response and <code>processResponse</code> will determine the validity of the returned content by checking the
provider service's response and corresponding signature corresponding to the chat ID.</p>
<pre><code class="typescript"><span class="hl-5">/**</span><br/><span class="hl-5"> * processResponse is used after the user successfully obtains a response from the provider service.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * processResponse extracts necessary information from the response and records it</span><br/><span class="hl-5"> * in localStorage for generating billing headers for subsequent requests.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * Additionally, if the service is verifiable, input the chat ID from the response and</span><br/><span class="hl-5"> * processResponse will determine the validity of the returned content by checking the</span><br/><span class="hl-5"> * provider service's response and corresponding signature corresponding to the chat ID.</span><br/><span class="hl-5"> *</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">providerAddress</span><span class="hl-5"> - The address of the provider.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">svcName</span><span class="hl-5"> - The name of the service.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">content</span><span class="hl-5"> - The main content returned by the service. For example, in the case of a chatbot service,</span><br/><span class="hl-5"> * it would be the response text.</span><br/><span class="hl-5"> * </span><span class="hl-6">@param</span><span class="hl-5"> </span><span class="hl-4">chatID</span><span class="hl-5"> - Only for verifiable service. You can fill in the chat ID obtained from response to</span><br/><span class="hl-5"> * automatically download the response signature. The function will verify the reliability of the response</span><br/><span class="hl-5"> * using the service's signing address.</span><br/><span class="hl-5"> * </span><span class="hl-6">@returns</span><span class="hl-5"> A boolean value. True indicates the returned content is valid, otherwise it is invalid.</span><br/><span class="hl-5"> * </span><span class="hl-6">@throws</span><span class="hl-5"> An error if errors occur during the processing of the response.</span><br/><span class="hl-5"> */</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">valid</span><span class="hl-1"> = </span><span class="hl-4">broker</span><span class="hl-1">.</span><span class="hl-0">processResponse</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-4">providerAddress</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-4">serviceName</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-4">content</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-4">chatID</span><br/><span class="hl-1">)</span>
</code><button type="button">Copy</button></pre>
<a id="md:interface" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Interface<a href="#md:interface" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Access the more details of interfaces via opening <a href="media/index.html">index.html</a> in browser.</p>
<p>By following the above steps, you will set up the 0G Serving Broker in your project correctly. Refer to the <a href="https://github.com/Ravenyjh/serving-demo" target="_blank" class="external">example</a> and <a href="https://raven.neetorecord.com/watch/3a4f134d-2c52-4cb7-b4ce-e02a8cefc2f1" target="_blank" class="external">video</a> for detailed usage instructions and additional information.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#md:0g-serving-broker-documentation"><span>0<wbr/>G <wbr/>Serving <wbr/>Broker <wbr/>Documentation</span></a><ul><li><a href="#md:overview"><span>Overview</span></a></li><li><a href="#md:setup-and-usage"><span>Setup and <wbr/>Usage</span></a></li><li><ul><li><a href="#md:step-1-install-the-dependency"><span>Step 1: <wbr/>Install the dependency</span></a></li><li><a href="#md:step-2-initialize-a-broker-instance"><span>Step 2: <wbr/>Initialize a <wbr/>Broker <wbr/>Instance</span></a></li><li><a href="#md:step-3-list-available-services"><span>Step 3: <wbr/>List <wbr/>Available <wbr/>Services</span></a></li><li><a href="#md:step-4-manage-accounts"><span>Step 4: <wbr/>Manage <wbr/>Accounts</span></a></li><li><ul><li><a href="#md:41-create-an-account"><span>4.1 <wbr/>Create an <wbr/>Account</span></a></li><li><a href="#md:42-deposit-funds-into-the-account"><span>4.2 <wbr/>Deposit <wbr/>Funds into the <wbr/>Account</span></a></li></ul></li><li><a href="#md:step-5-use-the-providers-services"><span>Step 5: <wbr/>Use the <wbr/>Provider's <wbr/>Services</span></a></li><li><ul><li><a href="#md:51-process-requests"><span>5.1 <wbr/>Process <wbr/>Requests</span></a></li><li><a href="#md:52-process-responses"><span>5.2 <wbr/>Process <wbr/>Responses</span></a></li></ul></li></ul></li><li><a href="#md:interface"><span>Interface</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current"><svg class="tsd-kind-icon" viewBox="0 0 24 24"><use href="assets/icons.svg#icon-1"></use></svg><span>@0glabs/0g-serving-broker - v0.2.0</span></a><ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base="."><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>