Client API for spender application

gnulib commented 5 years ago

This is the Phase I of #45 iteration 7.

Objective

Demonstrate REST API based transaction submission and query on a DLT stack based native application.

Acceptance Criteria

Extend the native go implementation of spendr application to provide REST API based access for following operations:

submit a resource creation transaction
submit a value transfer transaction
query a resource value
API should define language independent specs for correct serialization/deserialization of transaction signatures in payload
DAG protocol specs should work with hashing and encryption schemes that can be generally supported by common languages
build a Java based client for spendr application

gnulib commented 5 years ago

API Spec: Create Resource

Fetch the payload for "Create Resource" operation from Spendr's Op: Request Resource Creation Payload
Request an anchor from Spendr's Op: Request Anchor
Sign the payload using submitter's private key and submitter sequence as provided in Anchor
Submit transaction using Spendr's Op: Submit Transaction

API Spec: Value Transfer

Fetch the payload for "Value Transfer" operation from Spendr's Op: Request Value Transfer Payload
Request an anchor from Spendr's Op: Request Anchor
Sign the payload using submitter's private key and submitter sequence as provided in Anchor
Submit transaction using Spendr's Op: Submit Transaction

Op: Query Resource Value

This is a simple GET of specific resource by its key:

GET /resources/{key}

And response would consist of resource information as following:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Resource",
  "description": "A world state resource for spendr application",
  "type": "object",
  "properties": {
    "key": {
      "description": "The unique identifier for a resource within spendr application",
      "type": "string"
    },
    "owner": {
      "description": "130 char hex encoded identity of the owner of resource",
      "type": "string"
    },
    "value": {
      "description": "64 bit unsigned integer value for resource at the time of query",
      "type": "integer"
    }
  },
  "required": [ "key", "owner", "value" ]
}

gnulib commented 5 years ago

Op: Request Anchor

Request a new anchor for creating transaction:

POST /anchors

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AnchorRequest",
  "description": "Request to create a new anchor",
  "type": "object",
  "properties": {
    "submitter": {
      "description": "130 char hex encoded public id of the submitter",
      "type": "string"
    },
    "last_tx": {
      "description": "128 char hex encoded id of the last transaction from submitter",
      "type": "string"
    },
    "next_seq": {
      "description": "64 bit unsigned integer value for next transaction sequence from submitter",
      "type": "integer"
    }
  },
  "required": [ "submitter", "last_tx", "next_seq" ]
}

Above request should return a signed anchor response as following:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Anchor",
  "description": "A verified and signed anchor response from application's node",
  "type": "object",
  "properties": {
    "node_id": {
      "description": "130 char hex encoded public id/key of the node issuing this anchor",
      "type": "string"
    },
    "shard_id": {
      "description": "a hex encoded string uniquely identifying the shard of the application",
      "type": "string"
    },
    "shard_parent": {
      "description": "128 char hex encoded id of the parent tip for this anchor within shard DAG",
      "type": "string"
    },
    "shard_uncles": {
      "description": "list of 128 char hex encoded ids of other tips for this anchor within shard DAG",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "shard_seq": {
      "description": "64 bit unsigned integer value for sequence of this anchor in the shard DAG",
      "type": "integer"
    },
    "weight": {
      "description": "64 bit unsigned integer value for weight of this anchor in the shard DAG",
      "type": "integer"
    },
    "submitter": {
      "description": "130 char hex encoded public id of the submitter",
      "type": "string"
    },
    "last_tx": {
      "description": "128 char hex encoded id of the last transaction from submitter",
      "type": "string"
    },
    "submitter_seq": {
      "description": "64 bit unsigned integer value for anchor's transaction sequence from submitter",
      "type": "integer"
    },
    "anchor_signature": {
      "description": "a base64 encoded ECDSA secpk256 signature using private key of issuing node",
      "type": "string"
    }
  },
  "required": [ "node_id", "shard_id", "shard_parent", "submitter", "shard_seq", "weight",  "last_tx", "submitter_seq", "anchor_signature" ]
}

gnulib commented 5 years ago

Op: Request Resource Creation Payload

Request payload as per application's syntax/semantics for transaction payloads, for creating a new resource:

POST /opCode/create

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Resource",
  "description": "A world state resource for spendr application",
  "type": "object",
  "properties": {
    "key": {
      "description": "The unique identifier for a resource within spendr application",
      "type": "string"
    },
    "value": {
      "description": "64 bit unsigned integer value for resource at creation",
      "type": "integer"
    }
  },
  "required": [ "key", "value" ]
}

Or, create a dynamic endpoint for all opcodes?

GET /payload/{opCode}?arg1=<val1>&arg2=<val2>...

It seems strongly typed endpoints for specific opCode are safer, so will use the POST option

Successful response for above will return following:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Payload",
  "description": "a base64 encoded string for serialized (and optionally encrypted) payload as per application syntax/semantics",
  "type": "string"
}

gnulib commented 5 years ago

Op: Submit Transaction

Submit a new application transaction using a valid anchor and payload provided by application based on application's schema/semantic:

POST /transactions

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SubmitRequest",
  "description": "Request to submit a new transaction",
  "type": "object",
  "properties": {
    "anchor": {
      "description": "A verified and signed anchor response from application's node",
      "type": "object",
      "properties": {
        "node_id": {
          "description": "130 char hex encoded public id of the node issuing this anchor",
          "type": "string"
        },
        "shard_id": {
          "description": "a hex encoded string uniquely identifying the shard of the application",
          "type": "string"
        },
        "shard_parent": {
          "description": "130 char hex encoded id of the parent tip for this anchor within shard DAG",
          "type": "string"
        },
        "shard_uncles": {
          "description": "list of 130 char hex encoded ids of other tips for this anchor within shard DAG",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "shard_seq": {
          "description": "64 bit unsigned integer value for sequence of this anchor in the shard DAG",
          "type": "integer"
        },
        "weight": {
          "description": "64 bit unsigned integer value for weight of this anchor in the shard DAG",
          "type": "integer"
        },
        "submitter": {
          "description": "130 char hex encoded public id of the submitter",
          "type": "string"
        },
        "last_tx": {
          "description": "130 char hex encoded id of the last transaction from submitter",
          "type": "string"
        },
        "submitter_seq": {
          "description": "64 bit unsigned integer value for anchor's transaction sequence from submitter",
          "type": "integer"
        },
        "anchor_signature": {
          "description": "a base64 encoded ECDSA secpk256 signature using public id of issuing node",
          "type": "string"
        }
      }
    },
    "payload": {
      "description": "a base64 encoded payload for application",
      "type": "string"
    },
    "tx_signature": {
      "description": "a base64 encoded ECDSA secpk256 signature of seq+payload using private key of submitter",
      "type": "string"
    }
  },
  "required": [ "anchor", "payload", "tx_signature" ]
}

Above request should return a success response for transaction submission as following:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SubmitResponse",
  "description": "Response to successful transaction submission",
  "type": "object",
  "properties": {
    "tx_id": {
      "description": "130 char hex encoded id of the submitted transaction",
      "type": "string"
    }
  },
  "required": [ "tx_id"]
}

gnulib commented 5 years ago

Op: Request Value Transfer Payload

Request payload as per application's syntax/semantics for transaction payloads, for transferring value from owned resource to another resource:

POST /opcode/xfer

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OpCodeXferValueRequest",
  "description": "A spendr application OpCode request to transfer value from owned resource",
  "type": "object",
  "properties": {
    "source": {
      "description": "The unique identifier for an owned resource within spendr application",
      "type": "string"
    },
    "destination": {
      "description": "The unique identifier for destination resource within spendr application",
      "type": "string"
    },
    "value": {
      "description": "64 bit unsigned integer value to transfer from owned resource to destination resource",
      "type": "integer"
    }
  },
  "required": [ "source", "destination", "value" ]
}

Successful response for above will return the Payload as defined in Op: Request Resource Creation Payload

gnulib commented 5 years ago

Make protocol's encryption language independent

Current implementation performs following 2 things that make the implementation incompatible with other client implementations:

signature is serialized and deserialized using gob -- this needs to change to a standard 64 byte signature that can be serialized/deserialized in language independent manner
digest function used is SHA-512, which is not compatible with common ethereum based libraries -- need to use SHA-256

gnulib commented 5 years ago

Java client

A Java client for spendr application is posted at dag-lib-java

trust-net / dag-lib-go