Assess Reputation for Your dApp Users

An SDK to integrate Orange to your dApp

The "algorithm" and "AP" in method and variable names refer to "model" and "MP" respectively.

You can invoke the models of your choice available via Orange by sending invocation requests from your dApp to the system using the Orange Server SDK.

The general sequence in which you would call the methods to send an invocation request by specifying an model and a dataset is:

1. Call GetAlgorithmProviders and GetDataProviders to go through the available model and data providers.

2. Choose an MP and DP, and call GetAlgorithmMethods and GetDataMethods to fetch the method details on available models and datasets.

3. Choose an MP method and a DP method ensuring the schemas match, then call RequestOrangeScore to send an invocation request along with authorized and signed wallet information.

4. Call GetUserTask to fetch the invocation results, or the status of a task.

The results can be exported in the form of Verifiable Credentials. Refer to the verifiable credential docs here for more details on how that can be implemented.

SDK intro

The Orange server uses GraphQL for its interface design. You can use the methods defined below to perform actions such as fetching MP and DP schema details and sending calculation requests using a model-data pair for specific wallets and DIDs.

To use the SDK you need a DID for your dApp. You can get one by creating a wallet using ONTO app.

Initialization

Add this dependency in the go.mod file in your project.

github.com/orange-protocol/orange-sdk-go latest

Schema definition

The major schemas defined for the interface are described below.

type AlgorithmProvider{
    name:String!
    type:String!
    introduction:String!
    did:String!
    createTime:Int!
    title:String!
    provider:String!
    invokeFrequency:Int!
    apiState:Int!
    author:String!
    popularity:Int!
    delay:Int!
    icon:String!
}

type DataProvider {
    name:String!
    type:String!
    introduction:String!
    did:String!
    createTime:Int!
    title:String!
    provider:String!
    invokeFrequency:Int!
    apiState:Int!
    author:String!
    popularity:Int!
    delay:Int!
    icon:String!
}

type ProviderMethod {
    name:String!
    paramSchema:String!
    resultSchema:String!
}

type UserTasks {
    taskId:String!
    userDID:String!
    apDID:String!
    apName:String!
    apMethod:String!
    dpDID:String!
    dpName:String!
    dpMethod:String!
    createTime:String!
    updateTime:String!
    taskStatus:String!
    taskResult:String
    resultFile:String
    issueTxhash:String
}

input RequestOrangeScoreReq{
    appdid:String!
    data:RequestOrangeScoreData!
    sig:String!
}
input RequestOrangeScoreData {
    userdid:String!
    apdid:String!
    apmethod:String!
    dpdid:String!
    dpmethod:String!
    overwriteOld:Boolean!
    wallets:[UserWallet!]!
}
input UserWallet{
    chain:String!
    address:String!
    pubkey:String!
    sig:String!
}

# Currently defined queries
type Query {
  getAllAlgorithmProviders:[AlgorithmProvider!]!
  getAllDataProviders:[DataProvider!]!
  getAlgorithmMethods(did:String!):[ProviderMethod!]!
  getDataMethods(did:String!):[ProviderMethod!]!
  getUserTask(key:String!,taskId:Int!):UserTasks
}

type Mutation {
  requestOrangeScore(input:RequestOrangeScoreReq):Int!
}

Interface methods

1. Fetch details for all available MPs

Returns the details of all the currently registered model providers.

Method: GetAlgorithmProviders

Parameters: none

Returns: []*AlgorithmProvider

type AlgorithmProvider struct {
    Name            string `json:"name"`
    Type            string `json:"type"`
    Introduction    string `json:"introduction"`
    Did             string `json:"did"`
    CreateTime      int64  `json:"createTime"`
    Title           string `json:"title"`
    Provider        string `json:"provider"`
    InvokeFrequency int64  `json:"invokeFrequency"`
    APIState        int64  `json:"apiState"`
    Author          string `json:"author"`
    Popularity      int64  `json:"popularity"`
    Delay           int64  `json:"delay"`
    Icon            string `json:"icon"`
}

2. Fetch available methods for an MP

Returns all the currently available models and the associated schemas as defined by an MP.

Method: GetAlgorithmMethods

Parameters

• apdid- The DID of specified MP

Returns: []*ProviderMethod

type ProviderMethod struct {
    Name         string `json:"name"`
    ParamSchema  string `json:"paramSchema"`
    ResultSchema string `json:"resultSchema"`
}

3. Fetch details for all available DPs

Returns the details of all the currently registered data providers.

Method: GetDataProviders

Parameters: none

Returns: []*DataProvider

type DataProvider struct {
    Name            string `json:"name"`
    Type            string `json:"type"`
    Introduction    string `json:"introduction"`
    Did             string `json:"did"`
    CreateTime      int64  `json:"createTime"`
    Title           string `json:"title"`
    Provider        string `json:"provider"`
    InvokeFrequency int64  `json:"invokeFrequency"`
    APIState        int64  `json:"apiState"`
    Author          string `json:"author"`
    Popularity      int64  `json:"popularity"`
    Delay           int64  `json:"delay"`
    Icon            string `json:"icon"`
}

4. Fetch available data methods for a DP

Returns all the currently available datasets and the associated schemas as defined by a DP.

Method: GetDataMethods

Parameters

• dpdid- The DID of specified DP

Returns: []*ProviderMethod

type ProviderMethod struct {
    Name         string `json:"name"`
    ParamSchema  string `json:"paramSchema"`
    ResultSchema string `json:"resultSchema"`
}

5. Send a request to run the model with selected data

Sends a request to generate the score or report for the specified wallet addresses using the specified model and dataset, or MP and DP method respectively. Returns a taskId.

Calculation requests are handled asynchronously. You can use the returned task ID to fetch the generated result. Please note that certain types of data or volume may take some time to fetch, and so the calculation may take up to an hour in certain extreme cases after a request is sent successfully.

Method: RequestOrangeScore

Parameters

• *RequestOrangeScoreReq- defined below

type RequestOrangeScoreReq struct {
	AppDid string            `json:"appDid"`                    // DID of your dApp
	Data   RequestOrangeScoreData `json:"data"`                 // request data, specified as below
	Sig    string            `json:"sig"`                       // signature: dApp's DID signed with its private key  
}

type RequestOrangeScoreData struct {
    Userdid      string        `json:"userDid"`                 // DID of the user
    Apdid        string        `json:"apdid"`                   // DID of the MP
    Apmethod     string        `json:"apmethod"`                // MP method name
    Dpdid        string        `json:"dpdid"`                   // DID of the DP
    Dpmethod     string        `json:"dpmethod"`                // DP method name
    overwriteOld bool          `json:"overwriteOld"`            // whether override existing task
    Wallets      []*UserWallet `json:"wallets"`                 // user's wallet details, specified as below

}
type UserWallet struct {
	Chain   string `json:"chain"`                               // name of the chain
	Address string `json:"address"`                             // linked wallet address
	Pubkey  string `json:"pubkey"`                              // wallet public key
	Sig     string `json:"sig"`                                 // signature: user's DID signed with their private key
}

Returns: int64

6. Fetch result/status for a task

Method: GetUserTask

Parameters

• key- API key

• taskId - task ID

Returns: *UserTasks

type UserTasks struct {
    TaskID      string  `json:"taskId"`
    UserDid     string  `json:"userDID"`
    ApDid       string  `json:"apDID"`
    ApName      string  `json:"apName"`
    ApMethod    string  `json:"apMethod"`
    DpDid       string  `json:"dpDID"`
    DpName      string  `json:"dpName"`
    DpMethod    string  `json:"dpMethod"`
    CreateTime  string  `json:"createTime"`
    UpdateTime  string  `json:"updateTime"`
    TaskStatus  string  `json:"taskStatus"`
    TaskResult  *string `json:"taskResult"`                             // score points
    ResultFile  *string `json:"resultFile"`                             // credential file
    IssueTxhash *string `json:"issueTxhash"`                            // transaction hash for the credential on ontology
}

Sample invocation

Refer to the sample code below that invokes the GetAlgorithmProviders method.

func TestOrangeSDK_GetAlgorithmProviders(t *testing.T) {
	sdk, err := NewOrangeSDK("http://localhost:8080/query")
	assert.Nil(t, err)
	aps, err := sdk.GetAlgorithmProviders()
	assert.Nil(t, err)
	assert.NotNil(t, aps)
	assert.Greater(t, len(aps), 0)
}