ExternalService.proto

syntax = "proto3";

package integration.framework.openlaw;

// ExternalService definition parsed by the Protoc Compiler. It must be extended by the server implementation,
// so it can respond to gRPC requests from OpenLaw Integration Framework.
service ExternalService {
    
    // Gets the Ethereum Public Address from the service which is 
    // used to verify events sent from the service to OpenLaw VM.
    rpc GetEthereumAddress (Empty) returns (EthereumAddressResponse) { }

    // Gets the server Markup Interface definition which is used in a OpenLaw Agreement with ExternalCall or ExternalSignature variable types.
    // The expected Markup Interface definition must follow the standard:
    //  - [[Input:Structure(inputField1: <Type>; inputField2: <Type>; inputFieldN: <Type>)]] [[Output:Structure(outputField1: <Type>; outputField2: <Type>; outputFieldN: <Type>)]]
    //  - <Type> - can be replaced by: Text, Number and Date.
    // Basic Markup Interface for the Coin Market Cap service can be defined as a String of value:
    //  - "[[Input:Structure(fromCurrency: Text; toCurrency: Text; amount: Number)]] [[Output:Structure(currency: Text; price: Number; lastUpdate: Text)]]"
    // The standard Markup Interface for any e-Signature service is defined by the following String value:
    //  - "[[Input:Structure(signerEmail: Text; contractContentBase64: Text; contractTitle: Text)]] [[Output:Structure(signerEmail: Text; signature: Text; recordLink: Text)]]"
    // Any e-Signature service must use the exact same Markup Interface as described above, otherwise the e-Signature will not be validated by the OpenLaw VM.
    rpc GetMarkupInterface (Empty) returns (MarkupInterfaceResponse) { }

    // Executes the request from OpenLaw Integrator Framework and waits for the External Service response.
    rpc Execute (ExecuteRequest) returns (ExecuteResponse) { }

}

// The Ethereum Address response message.
message EthereumAddressResponse {
    //The Ethereum public address generated by the External Service.
    string address = 1;
}

// The Markup Interface response message.
message MarkupInterfaceResponse {
    // The Markup Interface definition that matches the 
    // OpenLaw Input/Output structures.
    string definition = 1;
}

// The Request message to be processed by the External Service.
message ExecuteRequest {
    // The contractId or flowId string value generated by OpenLaw.
    // e.g: 1a86c0ab-7895-497c-babb-a3c089df1203
    string callerId = 1;
    // The actionId string value which is an arbitrary content that 
    // represents the action that happened in OpenLaw VM. 
    string actionId = 2;
    // The requestId string value that represents the request in 
    // Integrator Framework.
    string requestId = 3;
    // The inputJson string value that matches the Input type defined 
    // in the Markup Interface. It must be converted from string to
    // json value in order to access its properties.
    string inputJson = 4;
    // The ethereum public address from the External Service as 
    // provided in the EthreumAddressResponse.
    string servicePublicAddress = 5;
}

// The Response message obtained from the executed call.
message ExecuteResponse {
    // The contractId or flowId string value generated by OpenLaw.
    // e.g: 1a86c0ab-7895-497c-babb-a3c089df1203
    string callerId = 1;
    // The actionId string value which is an arbitrary content that 
    // represents the action that happened in OpenLaw VM. 
    string actionId = 2;
    // The requestId string value that represents the request in 
    // Integrator Framework.
    string requestId = 3;
    // The outputJson as string value that matches the Output type 
    // defined in the Markup Interface. All values of the json must 
    // be String and the json must have no spaces.
    // e.g: 
    // - {"currency":"BRL","price":"29.03","update":"2019-09-10T16:31:00.000Z"}
    // - {"param1":"value1","param2":"value2","paramN":"valueN"}
    string outputJson = 4;
    // The output signature string which represents the signature of 
    // the outputJson field. The stringified version of the outputJson
    // must be used for signature.
    string outputSignature = 5;
    // The possible statuses of the response after the execution is 
    // terminated.
    enum Status {
        FAILURE = 0;
        SUCCESS = 1;
    }
    // The status of the execution. If not provided, the default is FAILURE. 
    Status status = 6;
    // The message returned by the External Service to indicate if the 
    // execution was completed with success or not. It can be an error 
    // message as well.
    string message = 7;
    // The ethereum public address from the External Service as provided
    // in the EthereumAddressResponse.
    string servicePublicAddress = 8;

    // Optional attribute to indicate the HTTP status code that must be handled differently
    // by the OpenLaw Integration Framework. For instance, if a storage service attempts to read
    // a file and the file doesn't exist one can return 404 to indicate that operation has failed with
    // a specific cause, so the integration service will propagate that error to OpenLaw platform.
    uint32 statusCode = 9;
}

// The Empty request message to indicate no data in the request.
message Empty {}