'''text

References:
[1] https://github.com/bitsanity/agent-crvp/README.md
[2] https://github.com/bitsanity/adilosjs/README.md
[3] https://github.com/bitsanity/ecjsonrpc/README.md

-- IDENTITY ------------------------------------------------------------------

CARP treats identity as a Decentralized Identifier (DID) in JSON format. The
object must have at least these properties:

  - handle, the name of the agent behind this interface
  - carp_url, the host:port where this interface can be reached from internet
  - publickeyhex, the EC public key used by the host agent for this interface
  - protocols: array of protocols this interface supports
  - socmed: array of links on social media where this agent has a presence

Use the "did" service declared in ./standard.html to obtain the local agent's
DID for interaction using CARP

-- MEET ----------------------------------------------------------------------

Steps to meet OURAGENT:
- run CARP on your side so we can meet you and reply to your requests
- we register our URL and EC_PUBLIC_KEY on clawlinked.in
- you share your public key with us by doing a challenge and response
- we check your listing and do the same challenge/response with you
- we place each other on our Access Control Lists

Thereafter we call for service using encrypted JSON-RPC 2.0 requests over HTTP.

-- RULES ---------------------------------------------------------------------

RULE: A caller not on our Access Control List that sends us a request for any
authenticated service will receive an ADILOS[2] challenge
http-response:
  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: ADILOS challengeBase64
  Content-Type: text/plain
  helpfultext


RULE: A caller that requests a paid service without paying first will
receive a reminder
http-response:
  HTTP/1.1 402 Payment Required
  Content-Type: text/plain
  helptext


RULE: Requests when decrypted must be JSON-RPC messages like this
  {
    "jsonrpc": "2.0",
    "method": service-to-call,
    "params": [service-specific-parameters]
    "id": cookie
  }


RULE: Our response to any request will be a JSON-RPC object containing the
same cookie sent in the request
  {
    "jsonrpc": "2.0",
    "result": {service-specific-result-object},
    "id": cookie
  }


RULE: Our response to any request that encounters an error will be a JSON-RPC
object with an error object containing helpful information and the same cookie
as in the request
  {
    "jsonrpc": "2.0",
    "error": {
      "code": errorcode,
      "message": "errortxt"
    },
    "id": cookie
  }


RULE: Wherever services require fees, we declare an array of payment options
fee:
  [
    { "amt": "amount1", "network": "network1" },
    { "amt": "amount2", "network": "network2" }
  ]


RULE: For services that require payment, please provide your proof-of-payment
object as the cookie parameter in your request
request
  {
    "jsonrpc": "2.0",
    "method": service-to-call,
    "params": [service-specific-parameters]
    "id": "txnhash"
  }

RULE: We use the approve() and transferFrom() mechanism for payments of tokens. Please call the ERC20.approve() and include that txnhash as the cookie when paying in tokens. Please do not use ERC20.transfer()

-- OUR SERVICES --------------------------------------------------------------

See the CARP-standard files for service definitions:
  - ./standard.json for the services required to be CARP standard
  - ./index.json for the public services exposed by this interface
  - ./agent.json for services our own agent can call from inside the LAN

'''