sls-documentation.yml

documentation:
  api:
    info:
      version: ${file(package.json):version}
      title: SecureVote convenience API
      description: >
        An API provided for convenient functions via SecureVote.
        This includes fee-less voting and other such functions.

        While these operations aren't as trustless as interacting with a chain directly,
        they do provide very fast verifiability (by checking the txid, etc) and allow for
        a few features that cannot be done without 3rd parites.

        APIs exist at

        * https://api.secure.vote

        * https://staging.api.secure.vote

        * https://dev.api.secure.vote

      termsOfService: https://secure.vote
      contact:
        name: Max Kaye
        url: https://secure.vote
        email: max@secure.vote
      license:
        name: None
        url: http://secure.vote

  resources:
    - path: "sv/light/submitProxyVote"
      description: "Submit a proxy vote here"

  models:
    - name: ErrTy
      contentType: application/json
      schema:
        type: object
        properties:
          error:
            type: string
      example:
        error: "Invalid request data."

    - name: HexString
      contentType: 'application/json'
      schema:
        type: string
      example: "0xdeadbeef1337"
      pattern: pattern = "/^0x([0-9a-fA-F]{2})*$/"
      format: "0x3b2c..."
      description: A hex string in Ethereum format ('0x010203aabbcc...')

    - name: EthAddress
      contentType: 'application/json'
      schema:
        type: string
      example: "0xD386456eb1Af15A5918E7ECC57142bB2634bF9B9"
      pattern: pattern = "/^0x([0-9a-fA-F]{2})*$/"
      format: "ethHexAddress"
      description: An Ethereum address

    - name: ProxyVoteReq
      description: >
        A tuple5 corresponding to the `proxyReq` object expected for proxy votes.
      contentType: "application/json"
      schema:
        type: array
        items:
          - $ref: '{{model: HexString}}'
            description: bytes32; The `r` param for an eth signature
          - $ref: '{{model: HexString}}'
            description: bytes32; The `s` param for an eth signature
          - $ref: '{{model: HexString}}'
            description: 'bytes32; Packed data. First byte is the `v` param for an eth sig, then 27 unallocated bytes, and the last 4 bytes are the sequence number'
          - $ref: '{{model: HexString}}'
            description: 'bytes32; ballotId as hex'
          - $ref: '{{model: HexString}}'
            description: 'bytes32; voteData as hex'
        minItems: 5
        maxItems: 5
      example:
        - "'0x0102..1f20' (`r` param)"
        - "'0x0102..1f20' (`s` param)"
        - "'0x0102..1f20' (`v` param in byte1, 27 unused bytes, `sequenceNumber` last 4 bytes)"
        - "'0x0102..1f20' (ballotId as hex)"
        - "'0x0102..1f20' (voteData as hex)"

    - name: ProxyVoteInput
      description: An object composed of the signed vote and metadata about which democracy and ballot it is for.
      contentType: application/json
      schema:
        type: object
        properties:
          proxyReq:
            $ref: '{{model: ProxyVoteReq}}'
          extra:
            $ref: '{{model: HexString}}'
          democHash:
            $ref: '{{model: HexString}}'
          ballotId:
            $ref: '{{model: HexString}}'
        required:
          - proxyReq
          - democHash
          - ballotId
          - extra
      example:
        proxyReq:
          - "0x32a28ff5895d200d3a518cc55a6cfdabe18623a29e8fb100a0b29b42a2111687"
          - "0x3d8c990c44939c2a619db686542614a5410ee48a217e7e5b0ecec4c1fb50865f"
          - "0x1c00000000000000000000000000000000000000000000000000000000000001"
          - "0x0000000000000000053970000000000000000000000000000000000000000000"
          - "0x4000000000000000000000000000000000000000000000000000000000000000"
        extra: 0x
        democHash: '0x40e135c54ddfdc99585d5d8e723906ea75e8447ba731ed0679135c084ac8278f'
        ballotId: '0x0000000000000000053970000000000000000000000000000000000000000000'

    - name: SubmitProxyVoteResp
      contentType: application/json
      schema:
        type: object
        properties:
          txid:
            $ref: '{{model: HexString}}'
          address:
            $ref: '{{model: EthAddress}}'

    - name: Ed25519DelegationReq
      description: An object composed of the ed25519 delegation and metadata about which democracy and subgroup it is for.
      contentType: application/json
      schema:
        type: object
        properties:
          signature:
            $ref: '{{model: HexString}}'
          publickey:
            $ref: '{{model: HexString}}'
          packed:
            $ref: '{{model: HexString}}'
        required:
          - signature
          - publickey
          - packed
      example:
        signature: ''
        publickey: ''
        packed: ''

    - name: Ed25519DelegationResp
      contentType: application/json
      schema:
        type: object
        properties:
          txid:
            $ref: '{{model: HexString}}'
          from:
            type: string
          to:
            $ref: '{{model: EthAddress}}'

    - name: TextResponse
      contentType: application/json
      schema:
        type: string

    - name: TxidResponse
      contentType: application/json
      schema:
        oneOf:
          - type: object
            properties:
              txid:
                $ref: '{{model: HexString}}'
          - $ref: '{{model: ErrTy}}'
      example:
        txid: "0xbf42...54d2 (32 bytes)"

    - name: HexResponse
      contentType: application/json
      schema:
        $ref: '{{model: HexString}}'

    - name: ObjectResponse
      contentType: application/json
      schema:
        type: object
        properties:
          val:
            type: object
          ty:
            type: string
        required:
          - val
          - ty

docFrags:
  GoodTextResp:
    statusCode: 200
    responseModels:
      "application/json": TextResponse
  GoodObjResp:
    statusCode: 200
    responseModels:
      "application/json": ObjectResponse
  ErrResp:
    statusCode: 400
    responseModels:
      "application/json": ErrTy