IRISnet Documents

Service

Service module allows you to define, bind, invoke services on the IRIS Hub. Read more about iService.

Available Commands

NameDescription
defineDefine a new service
definitionQuery a service definition
bindBind a service
bindingQuery a service binding
bindingsQuery all bindings of a service definition
set-withdraw-addrSet a withdrawal address for a provider
withdraw-addrQuery the withdrawal address of a provider
update-bindingUpdate an existing service binding
disableDisable an available service binding
enableEnable an unavailable service binding
refund-depositRefund all deposit from a service binding
callInitiate a service call
requestQuery a request by the request ID
requestsQuery active requests by the service binding or request context ID
respondRespond to a service request
responseQuery a response by the request ID
responsesQuery active responses by the request context ID and batch counter
request-contextQuery a request context
updateUpdate a request context
pausePause a running request context
startStart a paused request context
killTerminate a request context
feesQuery the earned fees of a provider
withdraw-feesWithdraw the earned fees of a provider
schemaQuery the system schema by the schema name
paramsQuery values set as service parameters.

iris tx service define

Define a new service.

iris tx service define [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--nameService nameYes
--descriptionService description
--author-descriptionService author description
--tagsService tags
--schemasContent or file path of service interface schemasYes

define a service

iris tx service define \
    --name=<service name> \
    --description=<service description> \
    --author-description=<author description>
    --tags=tag1,tag2 \
    --schemas=<schemas content or path/to/schemas.json> \
    --chain-id=irishub \
    --from=<key-name> \
    --fees=0.3iris

Schemas content example

{
    "input": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "BioIdentify service input body",
        "description": "BioIdentify service input body specification",
        "type": "object",
        "properties": {
            "id": {
                "description": "id",
                "type": "string"
            },
            "name": {
                "description": "name",
                "type": "string"
            },
            "data": {
                "description": "data",
                "type": "string"
            }
        },
        "required": [
            "id",
            "data"
        ]
    },
    "output": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "BioIdentify service output body",
        "description": "BioIdentify service output body specification",
        "type": "object",
        "properties": {
            "data": {
                "description": "result data",
                "type": "string"
            }
        },
        "required": [
            "data"
        ]
    }
}

iris query service definition

Query a service definition.

iris query service definition [service-name] [flags]

Query a service definition

Query the detailed info of the service definition with the specified service name.

iris query service definition <service name>

iris tx service bind

Bind a service.

iris tx service bind [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--service-nameService nameYes
--depositDeposit of the bindingYes
--pricingPricing content or file path, which is an instance of Irishub Service Pricing JSON SchemaYes
--qosMinimum response timeYes
--optionsNon-functional requirements optionsYes
--providerProvider address, default to the owner

Bind an existing service definition

The deposit needs to satisfy the minimum deposit requirement, which is the maximal one between price * MinDepositMultiple and MinDeposit (MinDepositMultiple and MinDeposit are the system parameters, which can be modified through the governance).

iris tx service bind \
    --service-name=<service name> \
    --deposit=10000iris \
    --pricing=<pricing content or path/to/pricing.json> \
    --qos=50 \
    --options=<non-functional requirements options content or path/to/options.json> \
    --chain-id=irishub \
    --from=<key-name> \
    --fees=0.3iris

Pricing content example

{
    "price": "1iris"
}

iris query service binding

Query a service binding.

iris query service binding <service name> <provider>

iris query service bindings

Query all bindings of a service definition.

iris query service bindings [service-name] [flags]

Query service binding list

iris query service bindings <service name> <owner address>

iris tx service update-binding

Update a service binding.

iris tx service update-binding [service-name] [provider-address] [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--depositDeposit added for the binding, not updated if empty
--pricingPricing content or file path, which is an instance of Irishub Service Pricing JSON Schema, not updated if empty
--qosMinimum response time, not updated if set to 0
--optionsNon-functional requirements options

Update an existing service binding

The following example updates the service binding with the additional 10 IRIS deposit

iris tx service update-binding <service-name> <provider-address> \
    --deposit=10iris \
    --options=<non-functional requirements options content or path/to/options.json> \
    --pricing='{"price":"1iris"}' \
    --qos=50 \
    --chain-id=<chain-id> \
    --from=<key name> \
    --fees=0.3iris

iris tx service set-withdraw-addr

Set a withdrawal address for a provider.

iris tx service set-withdraw-addr [withdrawal-address] [flags]

iris query service withdraw-addr

Query the withdrawal address of a provider.

iris query service withdraw-addr [provider] [flags]

iris tx service disable

Disable an available service binding.

iris tx service disable [service-name] [provider-address] [flags]

iris tx service enable

Enable an unavailable service binding.

iris tx service enable [service-name] [provider-address] [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--depositdeposit added for enabling the binding

Enable an unavailable service binding

The following example enables an unavailable service binding with the additional 10 IRIS deposit.

iris tx service enable <service name> <provider-address> --chain-id=irishub --from=<key-name> --fees=0.3iris --deposit=10iris

iris tx service refund-deposit

Refund all deposits from a service binding.

iris tx service refund-deposit [service-name] [provider-address] [flags]

Refund all deposits from an unavailable service binding

Before refunding, you should disable the service binding first.

iris tx service refund-deposit <service name> <provider-address> --chain-id=irishub --from=<key-name> --fees=0.3iris

iris tx service call

Initiate a service call.

iris tx service call [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--service-nameService nameYes
--providersProvider list to requestYes
--service-fee-capMaximum service fee to pay for a single requestYes
--dataContent or file path of the request input, which is an Input JSON Schema instanceYes
--timeoutRequest timeoutYes
--repeatedfalseIndicate if the reqeust is repetitive (Temporarily disabled in irishub-v1.0.0, will be activated after a few versions)
--frequencyRequest frequency when repeated, default to timeout
--totalRequest count when repeated, -1 means unlimited

Initiate a service invocation request

iris tx service call \
    --service-name=<service name> \
    --providers=<provider list> \
    --service-fee-cap=1iris \
    --data=<request input or path/to/input.json> \
    --timeout=100 \
    --repeated \
    --frequency=150 \
    --total=100 \
    --chain-id=irishub \
    --from=<key name> \
    --fees=0.3iris

Input example

{
    "header": {
        ...
    },
    "body": {
        "id": "1",
        "name": "irisnet",
        "data": "facedata"
    }
}

iris query service request

Query a request by the request ID.

iris query service request [request-id] [flags]

Query a service request

iris query service request <request-id>

TIP

You can retrieve the request-id in [Query request_id through rpc interface](#Query request_id through rpc interface) or [iris query service requests](#iris query service requests).

Query request_id through rpc interface

Query block_results according to block height through rpc interface, find new_batch_request_provider in end_block_events, decode the result with base64 to get request_id.

curl -X POST -d '{"jsonrpc":"2.0","id":1,"method":"block_results","params":["10604"]}' http://localhost:26657

iris query service requests

Query active requests by the service binding or request context ID.

iris query service requests [service-name] [provider] | [request-context-id] [batch-counter] [flags]

Query active requests of a service binding

iris query service requests <service name> <provider>

Query service requests by the request context ID and batch counter

iris query service requests <request-context-id> <batch-counter>

iris tx service respond

Respond to a service request.

iris tx service respond [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--request-idID of the request to respond toYes
--resultContent or file path of the response result, which is an instance of Irishub Service Result JSON SchemaYes
--dataContent or file path of the response output, which is an Output JSON Schema instance

Respond to a service request

iris tx service respond \
    --request-id=<request-id> \
    --result=<response result or path/to/result.json> \
    --data=<response output or path/to/output.json>
    --chain-id=irishub \
    --from=<key-name> \
    --fees=0.3iris

TIP

You can retrieve the request-id in [Query request_id through rpc interface](#Query request_id through rpc interface) or [iris query service requests](#iris query service requests).

Result example

{
    "code": 200,
    "message": ""
}

Output example

{
    "header": {
        ...
    },
    "body": {
        "data": "userdata"
    }
}

iris query service response

Query a service response.

iris query service response [request-id] [flags]

TIP

You can retrieve the request-id in [Query request_id through rpc interface](#Query request_id through rpc interface) or [iris query service requests](#iris query service requests).

iris query service responses

Query active responses by the request context ID and batch counter.

iris query service responses [request-context-id] [batch-counter] [flags]

Query responses by the request context ID and batch counter

iris query service responses <request-context-id> <batch-counter>

iris query service request-context

Query a request context.

iris query service request-context [request-context-id] [flags]

Query a request context

iris query service request-context <request-context-id>

TIP

You can retrieve the request-context-id in the result of service call

iris tx service update

Update a request context.

iris tx service update [request-context-id] [flags]

Flags:

Name, shorthandDefaultDescriptionRequired
--providersProvider list to request, not updated if empty
--service-fee-capMaximum service fee to pay for a single request, not updated if empty
--timeoutRequest timeout, not updated if set to 0
--frequencyRequest frequency, not updated if set to 0
--totalRequest count, not updated if set to 0

Update a request context

iris tx service update <request-context-id> \
    --providers=<provider list> \
    --service-fee-cap=1iris \
    --timeout=0 \
    --frequency=150 \
    --total=100 \
    --chain-id=irishub \
    --from=<key name> \
    --fees=0.3iris

iris tx service pause

Pause a running request context.

iris tx service pause [request-context-id] [flags]

Pause a running request context

iris tx service pause <request-context-id>

iris tx service start

Start a paused request context.

iris tx service start [request-context-id] [flags]

Start a paused request context

iris tx service start <request-context-id>

iris tx service kill

Terminate a request context.

iris tx service kill [request-context-id] [flags]

Kill a request context

iris tx service kill <request-context-id>

iris query service fees

Query the earned fees of a provider.

iris query service fees [provider] [flags]

iris tx service withdraw-fees

Withdraw the earned fees of a provider.

iris tx service withdraw-fees [provider-address] [flags]

iris query service schema

Query the system schema by the schema name, only pricing and result allowed.

iris query service schema [schema-name] [flags]

Query the service pricing schema

iris query service schema pricing

Query the response result schema

iris query service schema result

iris query service params

Query values set as service parameters.

iris query service params [flags]