openapi.yaml

openapi: 3.0.0
info:
  description: Smart Vault API
  version: 0.1.0
  title: Smart Vault API
  termsOfService: 'http://www.lightstreams.network/terms'
  license:
    name: GPLv3
    url: 'https://www.gnu.org/licenses/gpl.html'
paths:
  /user/signup:
    post:
      tags:
        - User
      summary: signup
      description: Create a new user on the gateway
      operationId: userSignup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    type: string
                    example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                    description: the account address that was created on the gateway
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                password:
                  type: string
                  example: yourpassword
        description: request body
        required: true
  /user/signin:
    post:
      tags:
        - User
      summary: signin
      description: Sign in a user into the system
      operationId: userSignin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: eyJibG9ja2NoYWluIjoiRVRIIiwiZXRoX2FkZHJlc3MiOiIweDRGNWFERWRDYTZkODY5RTlGNUY3ZENmNEI3QTlkRmE4MjMxYTA5NWYiLCJpYXQiOjI1LCJlYXQiOjEwMjV9.78mSE4Z9SiHO9fcY5vtCZpK-rdDGuJXpW4qEOzyH9-Zy5HySKGVH9aB-j_ixUb0q91S-I9_Cktj_OVl0LcRvmgE
                    description: the account address that was created on the gateway
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - account
                - password
              properties:
                account:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the account
        description: Password to sign in the user
        required: true
  /wallet/balance:
    get:
      tags:
        - Wallet
      summary: balance
      description: Get wallet balance from an account
      operationId: walletBalance
      parameters:
        - in: query
          name: account
          description: account
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: string
                    example: '100'
                    description: current balance in wei
  /wallet/transfer:
    post:
      tags:
        - Wallet
      summary: transfer
      description: Transfer funds to an account
      operationId: walletTransfer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: string
                    example: '100'
                    description: current balance in wei
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - password
                - to
                - amount_wei
              properties:
                from:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address to transfer funds from
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the account
                to:
                  type: string
                  example: '0x50c9406f0942711b6e2e28301CE86bFbF42eBE3F'
                  description: account address to transfer funds to
                amount_wei:
                  type: string
                  example: '1200000000000000000'
                  description: amount in wei
        description: Password to sign in the user
        required: true
  /storage/add:
    post:
      tags:
        - Storage
      summary: add
      description: Add a new file
      operationId: storageAdd
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: file to add
                  type: string
                  format: binary
                owner:
                  description: file owner address
                  type: string
                password:
                  description: the password that unlocks the owner
                  type: string
              required:
                - file
                - owner
                - password
  /storage/add-with-acl:
    post:
      tags:
        - Storage
      summary: add-with-acl
      description: Add a new file using an already deployed acl
      operationId: storageAddWithAcl
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: file to add
                  type: string
                  format: binary
                owner:
                  description: address of the owner of the file
                  type: string
                acl:
                  description: address of acl smart contract
                  type: string
              required:
                - file
                - owner
                - acl
  /storage/add-raw:
    post:
      tags:
        - Storage
      summary: add-raw
      description: Add a new raw file (text, json, etc.)
      operationId: storageAddRaw
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  description: raw string to add
                  type: string
                  format: binary
                ext:
                  description: extension describing the raw content (txt, json, etc.)
                  type: string
                  format: binary
                owner:
                  description: address of the owner of the raw content
                  type: string
                password:
                  description: the password that unlocks the owner
                  type: string
              required:
                - data
                - ext
                - owner
                - password
  /storage/add-raw-with-acl:
    post:
      tags:
        - Storage
      summary: add-raw-with-acl
      description: Add a new raw file (text, json, etc.) linked to an existing ACL
      operationId: storageAddRawWithAcl
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  description: raw string to add
                  type: string
                  format: binary
                ext:
                  description: extension describing the raw content (txt, json, etc.)
                  type: string
                  format: binary
                owner:
                  description: address of the owner of the raw content
                  type: string
                acl:
                  description: address of acl smart contract
                  type: string
              required:
                - data
                - ext
                - owner
                - acl
  /storage/update:
    post:
      tags:
        - Storage
      summary: update
      description: Create a new version of the file, linking to previous file meta and reusing its ACL
      operationId: storageUpdate
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: file to add
                  type: string
                  format: binary
                owner:
                  description: address of the owner of the new file
                  type: string
                meta:
                  description: address of the file meta data
                  type: string
              required:
                - file
                - owner
                - meta
  /storage/update-raw:
    post:
      tags:
        - Storage
      summary: update-raw
      description: Create a new version of the file, linking to previous file meta and reusing its ACL
      operationId: storageUpdateRaw
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: 'QmbVtvd1rD9pDHpx7AUqrsh3CoCMW3Na3g4fAwXJxyaawz'
                    description: address of the file metadata
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: address of the ACL for the file
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  description: raw string to add
                  type: string
                  format: binary
                ext:
                  description: extension describing the raw content (.txt, .json, etc.)
                  type: string
                  format: binary
                owner:
                  description: address of the current file owner
                  type: string
                meta:
                  description: address of the file meta data
                  type: string
              required:
                - data
                - ext
                - owner
                - meta
  /storage/meta:
    get:
      tags:
        - Storage
      summary: meta
      description: Fetch meta data information about file
      operationId: storageMeta
      parameters:
        - in: query
          name: meta
          description: address of the file meta data
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  filename:
                    type: string
                    example: smart_vault_rocks.txt
                    description: Original file name
                  ext:
                    type: string
                    example: txt
                    description: File extension
                  owner:
                    type: string
                    example:
                    description: File owner address
                  hash:
                    type: string
                    example: 'QmXT5yfwk9zpVHZZ9WYzAFiSV3N2YAx8nFqd5w3t2jrsvo'
                    description: Hash of the protected file
                  acl:
                    type: string
                    example: '0x7000f85C4065643435E8A350655F3153c7dd030E'
                    description: Address of the ACL for the file
                  prev_meta_hash:
                    type: string
                    example: ''
                    description: Address of previous metadata content (in case of update)
  /storage/stream:
    get:
      tags:
        - Storage
      summary: stream
      description: Stream a file
      operationId: storageStream
      parameters:
        - in: query
          name: meta
          description: address of the file meta data
          required: true
          schema:
            type: string
        - in: query
          name: token
          description: token received after succesfull authentication (/user/signin)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              examples:
                response:
                  value: Smart Vault Rocks!
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: {"message":"token 'eyJibG9xxx.yyyGBw' is not valid. token has expired by 56888 blocks. Expiry block 796257, Current block: 853145","code":"ERROR_UNKNOWN"}
                    description: The reason of the failure
  /acl/grant:
    post:
      tags:
        - ACL
      summary: grant
      description: Grant certain file permissions to an account
      operationId: aclGrant
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_granted:
                    type: string
                    example: 'true'
                    description: a boolean that is true when the grant was executed succesfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - acl
                - owner
                - password
                - to
                - permission
              properties:
                acl:
                  type: string
                  example: '0x7251e7005dba3abb0aee4e772a5ff378a8eea885'
                  description: ACL address obtained after storing a file
                owner:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address of file's owner
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the account
                to:
                  type: string
                  example: '0x50c9406f0942711b6e2e28301CE86bFbF42eBE3F'
                  description: account address that will receive the permissions
                permission:
                  type: string
                  enum:
                    - read
                    - write
                    - admin
                    - noaccess
                  example: read
                  description: permission type to grant
        description: request body
        required: true
  /acl/grant-public:
    post:
      tags:
        - ACL
      summary: grantPublic
      description: Grant public access to a file
      operationId: aclGrantPublic
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_granted:
                    type: string
                    example: 'true'
                    description: a boolean that is true when the grant was executed succesfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - acl
                - owner
                - password
              properties:
                acl:
                  type: string
                  example: '0x7251e7005dba3abb0aee4e772a5ff378a8eea885'
                  description: ACL address obtained after storing a file
                owner:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address of file's owner
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the account
        description: request body
        required: true
  /acl/revoke-public:
    post:
      tags:
        - ACL
      summary: revokePublic
      description: Revoke public access to a file
      operationId: aclRevoke
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_revoked:
                    type: string
                    example: 'true'
                    description: a boolean that is true when the revoke was executed succesfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - acl
                - owner
                - password
              properties:
                acl:
                  type: string
                  example: '0x7251e7005dba3abb0aee4e772a5ff378a8eea885'
                  description: ACL address obtained after storing a file
                owner:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address of file's owner
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the account
        description: request body
        required: true
  /shop/create:
    post:
      tags:
        - Shop
      summary: create
      description: 'Creates an online shop, smart contract, for selling/buying digital content'
      operationId: shopCreate
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  shop:
                    type: string
                    example: 0xshopIDF16F003897fb927e22438cb1b820f79879
                    description: the shop smart contract address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - password
              properties:
                from:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: shop owner account address
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the from account
        description: request body
        required: true
  /shop/sell:
    post:
      tags:
        - Shop
      summary: sell
      description: Puts an ACL permission to digital content for sale in owner's online shop
      operationId: shopSell
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    example: 'true'
                    description: whenever the ACL is successfully on sale now
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - shop
                - from
                - password
                - acl
                - price_wei
              properties:
                shop:
                  type: string
                  example: 0xshopIDF16F003897fb927e22438cb1b820f79879
                  description: shop contract address
                from:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: shop owner account address
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the from account
                acl:
                  type: string
                  example: '0x32b480cCf1f6ccc6ABd3C1bfEecCd8D12b2Db3f8'
                  description: the ACL to sell
                price_wei:
                  type: string
                  example: '1000000000000000000'
                  description: the ACL price possible buyers must pay to get ACL Read Permission
        description: request body
        required: true
  /shop/buy:
    post:
      tags:
        - Shop
      summary: buy
      description: Buys the ACL Read Permission to digital content from owner's online shop
      operationId: shopBuy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    example: 'true'
                    description: whenever the ACL Read Permission is successfully bought now
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - shop
                - from
                - password
                - acl
              properties:
                shop:
                  type: string
                  example: 0xshopIDF16F003897fb927e22438cb1b820f79879
                  description: shop contract address
                from:
                  type: string
                  example: '0xE41b5C21671C22f1f054F1896d18b4773Dd9deC0'
                  description: account address buying ACL
                password:
                  type: string
                  example: yourpassword
                  description: the password that unlocks the from account
                acl:
                  type: string
                  example: '0x32b480cCf1f6ccc6ABd3C1bfEecCd8D12b2Db3f8'
                  description: the ACL to buy
        description: request body
        required: true
externalDocs:
  description: Read more about Lightstreams
  url: 'https://docs.lightstreams.network'
servers:
  - url: 'http://localhost:9091'
components:
  schemas:
    Meta:
      type: object
      required:
        - meta
      properties:
        meta:
          type: string
          example: '0x50c9406f0942711b6e2e28301CE86bFbF42eBE3F'
          description: address of the file meta data