From 70772f6a781e60b5e8f5d701d1142ef7040bb6e4 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Sun, 31 Mar 2024 17:21:26 -0400
Subject: [PATCH 01/19] =?UTF-8?q?=F0=9F=92=BB=F0=9F=93=90=20openapi=20swag?=
 =?UTF-8?q?ger=20wip=20specification=20for=20/delegates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/app/api/feature.swagger.yaml | 89 ++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 src/app/api/feature.swagger.yaml

diff --git a/src/app/api/feature.swagger.yaml b/src/app/api/feature.swagger.yaml
new file mode 100644
index 000000000..65c82343a
--- /dev/null
+++ b/src/app/api/feature.swagger.yaml
@@ -0,0 +1,89 @@
+openapi: 3.0.0
+info:
+  title: Agora API
+  description: Public API for interacting with the Agora platform
+  version: 0.1.0
+servers:
+  - url: vote.optimisim.io/api/v1
+  description: Base URL for optimism production
+components:
+  schemas:
+    Delegate:
+      type: object
+      properties:
+        address:
+          type: string
+          example: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+        votingPower:
+          type: object
+          properties:
+            advanced:
+              type: string
+              example: "10000"
+            direct:
+              type: string
+              example: "20000"
+            total:
+              type: string
+              example: "30000"
+        isCitizen:
+          type: boolean
+        email:
+          type: string
+        twitter:
+          type: string
+          example:
+        discord:
+          type: string
+          exmaple:
+        statement:
+          type: string
+          example: "hello! I am a great delegate for reasons xyz"
+        leastValuableProposals:
+          type: array
+          item: ???
+        mostValuableProposals:
+          type: array
+          item: ???
+        openToSponsoringProposals:
+          type: boolean
+        topIssues:
+          type: array
+          item: ???
+parameters:
+   limitParam:
+      name: limit
+      in: query
+      description: Limits the number of returned results
+      required: false
+      type: integer
+      format: int32
+   offsetParam:
+      name: offset
+      in: query
+      description: Offset from which start returned results
+      required: false
+      type: integer
+      format: int32
+paths:
+  /delegates:
+    get:
+      summary: Gets delegates
+      description: Retrieves a list of voting delegates
+      operationId: getDelegates
+      parameters:
+        - $ref: "#/parameters/limitParam"
+        - $ref: "#/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >-
+            The desired method by which returned delegates will be sorted
+          required: false
+          schema: 
+            type: string
+      responses: 
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema: '#/components/schema/Delegate'
\ No newline at end of file

From 7c18ea281c57904208d970881de86a0638707ce3 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Sun, 31 Mar 2024 17:21:26 -0400
Subject: [PATCH 02/19] =?UTF-8?q?=F0=9F=92=BB=F0=9F=93=90=20openapi=20swag?=
 =?UTF-8?q?ger=20wip=20specification=20for=20/delegates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/app/api/feature.swagger.yaml | 157 +++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 src/app/api/feature.swagger.yaml

diff --git a/src/app/api/feature.swagger.yaml b/src/app/api/feature.swagger.yaml
new file mode 100644
index 000000000..16abecda8
--- /dev/null
+++ b/src/app/api/feature.swagger.yaml
@@ -0,0 +1,157 @@
+openapi: 3.0.0
+info:
+  title: Agora API
+  description: Public API for interacting with the Agora platform
+  version: 0.1.0
+servers:
+  - url: vote.optimisim.io/api/v1
+    description: Base URL for optimism production
+security:
+  - ApiKeyAuth: []
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+  schemas:
+    Delegate:
+      type: object
+      properties:
+        address:
+          type: string
+          example: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+        votingPower:
+          type: object
+          properties:
+            advanced:
+              type: string
+              example: "10000"
+            direct:
+              type: string
+              example: "20000"
+            total:
+              type: string
+              example: "30000"
+        isCitizen:
+          type: boolean
+        email:
+          type: string
+        twitter:
+          type: string
+          example:
+        discord:
+          type: string
+          example: "delegate#1234"
+        statement:
+          type: string
+          example: "hello! I am a great delegate for reasons xyz"
+        leastValuableProposals:
+          type: array
+          items: 
+            type: string
+        mostValuableProposals:
+          type: array
+          items: 
+            type: string
+        openToSponsoringProposals:
+          type: boolean
+        topIssues:
+          type: array
+          items: 
+            type: string
+  parameters:
+   limitParam:
+      name: limit
+      in: query
+      description: Limits the number of returned results
+      required: false
+      schema:
+        type: integer
+        format: int32
+        minimum: 1
+        maximum: 100
+        default: 10
+   offsetParam:
+      name: offset
+      in: query
+      description: Offset from which start returned results
+      required: false
+      schema:
+        type: integer
+        format: int32
+        minimum: 0
+        default: 0
+paths:
+  /delegates:
+    get:
+      summary: Gets a list of delegates.
+      description: >
+        Retrieves a list of voting delegates on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getDelegates
+      tags:
+        - delegates
+      parameters:
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned delegates will be sorted.
+            Supported values are: 'most_delegators', 'weighted_random'
+          required: false
+          schema: 
+            type: string
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: array
+                items:
+                  $ref: '#/components/schemas/Delegate'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /delegates/{addressOrEnsName}:
+    get:
+      summary: Gets a specific delegate.
+      description: >
+        Retrieves a specific delegate on Agora by address or ENS name.
+      operationId: getDelegate
+      tags: 
+        - delegates
+      parameters:
+        - name: addressOrEnsName
+          in: path
+          description: The address or ENS name of the delegate to retrieve
+          required: true
+          schema:
+            type: string
+          examples: 
+            address: 
+              value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+              summary: Address of the delegate. 
+            ensName:
+              value: "flipliquid.eth"
+              summary: ENS name of the delegate.
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Delegate'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
\ No newline at end of file

From 0b98064f5fc8c1720f457ab8b6ae7c08290aebd3 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 1 Apr 2024 15:18:14 -0400
Subject: [PATCH 03/19] =?UTF-8?q?=F0=9F=A4=8F=20=F0=9F=93=83=20?=
 =?UTF-8?q?=F0=9F=86=9A=20bump=20version=203.1.0;=20add=20license;=20quali?=
 =?UTF-8?q?fy=20beta?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/app/api/feature.swagger.yaml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/app/api/feature.swagger.yaml b/src/app/api/feature.swagger.yaml
index 16abecda8..2b8b6fc32 100644
--- a/src/app/api/feature.swagger.yaml
+++ b/src/app/api/feature.swagger.yaml
@@ -1,8 +1,11 @@
-openapi: 3.0.0
+openapi: 3.1.0
 info:
   title: Agora API
   description: Public API for interacting with the Agora platform
-  version: 0.1.0
+  version: 0.1.0-beta
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
 servers:
   - url: vote.optimisim.io/api/v1
     description: Base URL for optimism production

From 10777861973acf137975ef7df2ff7e60ea9df65e Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 1 Apr 2024 16:36:02 -0400
Subject: [PATCH 04/19] =?UTF-8?q?=F0=9F=8F=B7=EF=B8=8F=20rename=20to=20oas?=
 =?UTF-8?q?=5Fv1.yaml?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/app/api/feature.swagger.yaml => spec/oas_v1.yaml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename src/app/api/feature.swagger.yaml => spec/oas_v1.yaml (100%)

diff --git a/src/app/api/feature.swagger.yaml b/spec/oas_v1.yaml
similarity index 100%
rename from src/app/api/feature.swagger.yaml
rename to spec/oas_v1.yaml

From 3fcb58530202ada1e252df2d9190bb4b31bec5e8 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 1 Apr 2024 16:53:22 -0400
Subject: [PATCH 05/19] =?UTF-8?q?=F0=9F=94=82=20add=20CI/GHA=20file;=20int?=
 =?UTF-8?q?egrate=20basic=20swagger=20linting?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/ci.yml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..f2659e5c6
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,22 @@
+name: CI
+run-name: ${{ github.actor }} - ${{ github.event_name }} - ${{ github.repository }}
+on:
+  pull_request:
+    branches:
+      - 'main'
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  swagger_lint:
+    runs-on: ubuntu-latest
+    name: Swagger Editor Validator Remote
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Validate OpenAPI definition
+        uses: char0n/swagger-editor-validate@v1
+        with:
+          swagger-editor-url: https://editor-next.swagger.io/
+          definition-file: spec/oas_v1.yaml
\ No newline at end of file

From 89bd2a51782c1a00348012d153fe3b76299ceda4 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 1 Apr 2024 17:01:24 -0400
Subject: [PATCH 06/19] =?UTF-8?q?=F0=9F=A4=8F=F0=9F=AA=B3=20remove=20depre?=
 =?UTF-8?q?cated=20exmaples=20syntax?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 2b8b6fc32..e9af500f7 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -23,35 +23,49 @@ components:
       properties:
         address:
           type: string
-          example: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+          examples: 
+            - summary: Address of the delegate.
+              value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
         votingPower:
           type: object
           properties:
             advanced:
               type: string
-              example: "10000"
+              examples:
+                - summary: Advanced voting power
+                  value: "10000"
             direct:
               type: string
-              example: "20000"
+              examples:
+                - summary: Direct voting power
+                  value: "20000"
             total:
               type: string
-              example: "30000"
+              examples:
+                - summary: Total voting power
+                  value: "30000"
         isCitizen:
           type: boolean
         email:
           type: string
         twitter:
           type: string
-          example:
+          examples:
+            - summary: Twitter handle
+              value: ""
         discord:
           type: string
-          example: "delegate#1234"
+          examples:
+            - summary: Discord handle
+              value: "delegate#1234"
         statement:
           type: string
-          example: "hello! I am a great delegate for reasons xyz"
+          examples:
+            - summary: Delegate statement
+              value: "hello! I am a great delegate for reasons xyz"
         leastValuableProposals:
           type: array
-          items: 
+          items:
             type: string
         mostValuableProposals:
           type: array

From c2af1ab1a9db0b338e0e9228ffa7db25860aa2e3 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 1 Apr 2024 17:10:37 -0400
Subject: [PATCH 07/19] =?UTF-8?q?=F0=9F=A4=8F=F0=9F=94=82=20fixup=20to=20C?=
 =?UTF-8?q?I;=20use=20ApiDOM=20validator=20for=20OAS=20v=203.1.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f2659e5c6..3e00f53f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,7 +16,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - name: Validate OpenAPI definition
-        uses: char0n/swagger-editor-validate@v1
+        uses: char0n/apidom-validate@v1
         with:
-          swagger-editor-url: https://editor-next.swagger.io/
+          fails-on: 2
           definition-file: spec/oas_v1.yaml
\ No newline at end of file

From d89a168d70642b7e01afd95369262eeaed856223 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Wed, 3 Apr 2024 10:22:18 -0700
Subject: [PATCH 08/19] =?UTF-8?q?=F0=9F=A4=8F=F0=9F=93=9D=20=F0=9F=93=90?=
 =?UTF-8?q?=20fixup=20examples;=20add=20issue=20type=20for=20delegates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index e9af500f7..65d608440 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -52,7 +52,7 @@ components:
           type: string
           examples:
             - summary: Twitter handle
-              value: ""
+              value: "@flip_liquide"
         discord:
           type: string
           examples:
@@ -64,10 +64,12 @@ components:
             - summary: Delegate statement
               value: "hello! I am a great delegate for reasons xyz"
         leastValuableProposals:
+          description: An array of proposal IDs
           type: array
           items:
             type: string
         mostValuableProposals:
+          description: An array of proposal IDs
           type: array
           items: 
             type: string
@@ -76,7 +78,18 @@ components:
         topIssues:
           type: array
           items: 
-            type: string
+              $ref: '#/components/schemas/Issue'
+    Issue:
+      type: object
+      properties:
+        type: 
+          type: string
+          examples: 
+            - "Funding"
+        value:
+          type: string
+          examples: 
+            - "Grant funding should be directed to projects with a great track record"
   parameters:
    limitParam:
       name: limit

From e114f734bda5da0a9899a03bbd67307baf1a1168 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Wed, 3 Apr 2024 10:26:58 -0700
Subject: [PATCH 09/19] =?UTF-8?q?=E2=9D=8C=20delete=20old=20spec?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/app/api/feature.swagger.yaml | 89 --------------------------------
 1 file changed, 89 deletions(-)
 delete mode 100644 src/app/api/feature.swagger.yaml

diff --git a/src/app/api/feature.swagger.yaml b/src/app/api/feature.swagger.yaml
deleted file mode 100644
index 65c82343a..000000000
--- a/src/app/api/feature.swagger.yaml
+++ /dev/null
@@ -1,89 +0,0 @@
-openapi: 3.0.0
-info:
-  title: Agora API
-  description: Public API for interacting with the Agora platform
-  version: 0.1.0
-servers:
-  - url: vote.optimisim.io/api/v1
-  description: Base URL for optimism production
-components:
-  schemas:
-    Delegate:
-      type: object
-      properties:
-        address:
-          type: string
-          example: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
-        votingPower:
-          type: object
-          properties:
-            advanced:
-              type: string
-              example: "10000"
-            direct:
-              type: string
-              example: "20000"
-            total:
-              type: string
-              example: "30000"
-        isCitizen:
-          type: boolean
-        email:
-          type: string
-        twitter:
-          type: string
-          example:
-        discord:
-          type: string
-          exmaple:
-        statement:
-          type: string
-          example: "hello! I am a great delegate for reasons xyz"
-        leastValuableProposals:
-          type: array
-          item: ???
-        mostValuableProposals:
-          type: array
-          item: ???
-        openToSponsoringProposals:
-          type: boolean
-        topIssues:
-          type: array
-          item: ???
-parameters:
-   limitParam:
-      name: limit
-      in: query
-      description: Limits the number of returned results
-      required: false
-      type: integer
-      format: int32
-   offsetParam:
-      name: offset
-      in: query
-      description: Offset from which start returned results
-      required: false
-      type: integer
-      format: int32
-paths:
-  /delegates:
-    get:
-      summary: Gets delegates
-      description: Retrieves a list of voting delegates
-      operationId: getDelegates
-      parameters:
-        - $ref: "#/parameters/limitParam"
-        - $ref: "#/parameters/offsetParam"
-        - name: sort
-          in: query
-          description: >-
-            The desired method by which returned delegates will be sorted
-          required: false
-          schema: 
-            type: string
-      responses: 
-        '200':
-          description: successful operation
-          content:
-            application/json:
-              schema: '#/components/schema/Delegate'
\ No newline at end of file

From f54d5c319aba6dc2c077f0f4e9eefabbee303293 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Wed, 3 Apr 2024 16:18:33 -0700
Subject: [PATCH 10/19] =?UTF-8?q?=F0=9F=92=BB=F0=9F=93=90=20add=20page=20m?=
 =?UTF-8?q?etadata=20to=20OAS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 65d608440..8d9ec3dfc 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -18,6 +18,17 @@ components:
       in: header
       name: Authorization
   schemas:
+    PageMetadata:
+      type: object
+      properties:
+        hasNext:
+          type: boolean
+        totalReturned:
+          type: integer
+          format: int32
+        nextOffset: 
+          type: integer
+          format: int32
     Delegate:
       type: object
       properties:
@@ -139,9 +150,14 @@ paths:
           content:
             application/json:
               schema: 
-                type: array
-                items:
-                  $ref: '#/components/schemas/Delegate'
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Delegate'
         '400':
           description: Bad Request
         '401': 

From ed6e0b4e9df69d2e53aa4f37a98185b0934e6965 Mon Sep 17 00:00:00 2001
From: Flip <13227294+Flip-Liquid@users.noreply.github.com>
Date: Mon, 8 Apr 2024 14:24:58 -0700
Subject: [PATCH 11/19] =?UTF-8?q?=F0=9F=93=90=F0=9F=92=BB=20update=20per?=
 =?UTF-8?q?=20notion=20draft=20spec?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 84 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 63 insertions(+), 21 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 8d9ec3dfc..58b70d639 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -19,78 +19,120 @@ components:
       name: Authorization
   schemas:
     PageMetadata:
+      summary: Pagination metadata
+      description: Metadata associated with paginated requests.
       type: object
       properties:
         hasNext:
+          summary: Flag indicating if there's more data for retieval
+          description: A boolean flag indicating if there is additional data past the returned page to retrieve.
           type: boolean
         totalReturned:
+          summary: Total records returned
+          description: A number indicating the total amount of records returned for the request.
           type: integer
           format: int32
         nextOffset: 
+          summary: Offset to supply to the next request
+          description: A number indicating the offset at which a subsequent request may retrieve the next set of records.
           type: integer
           format: int32
-    Delegate:
+    Delegation:
+      summary: A delegation of voting power
+      description: A delegation of voting power from one address to another.
+      type: object
+      properties:
+        address: 
+          summary: Delegate address
+          description: Address of the delegator or delegatee.
+          type: string 
+          examples:
+          - summary: Address of the delegator or delegatee.
+            value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+        totalAllowance:
+          summary: Voting allowance for delegate
+          description: Total amount of voting power delegated to or from address. 
+          type: string
+          examples:
+          - summary: Amount of voting power delegated to or from address.
+            value: "100000"
+        delegatedOn:
+          summary: When delegation occured
+          description: The datetime on which the delegation of voting power occurred. 
+          type: string
+          format: date-time
+          examples:
+          - summary: The datetime on which the delegation of voting power occurred.
+        type:
+          $ref: "#/components/schemas/DelegationType"
+    DelegationType:
+      summary: Type of delegation
+      description: The type of delegation; can be advanced or standard.
+      type: string
+      enum:
+        - advanced
+        - standard
+    BaseDelegate:
+      summary: A voting delegate
+      description: Data associated with a voting delegate. Sub-resources under this delegate are not expanded. 
       type: object
       properties:
         address:
+          summary: Delegate address
+          description: Address of the delegate.
           type: string
           examples: 
             - summary: Address of the delegate.
               value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
         votingPower:
+          summary: Delegate's available voting power
+          description: An object providing a breakdown of a delegate's overall voting power between direct, advanced, and total.
           type: object
           properties:
             advanced:
+              description: Advanced voting power.
               type: string
               examples:
-                - summary: Advanced voting power
+                - summary: Advanced voting power.
                   value: "10000"
             direct:
+              description: Direct voting power.
               type: string
               examples:
                 - summary: Direct voting power
                   value: "20000"
             total:
+              description: Total voting power.
               type: string
               examples:
                 - summary: Total voting power
                   value: "30000"
         isCitizen:
+          description: A boolean flag indicating whether or not this delegate is an Agora citizen.
           type: boolean
-        email:
-          type: string
         twitter:
+          description: Optional twitter handle for a particular delegate.
           type: string
           examples:
             - summary: Twitter handle
               value: "@flip_liquide"
-        discord:
-          type: string
-          examples:
-            - summary: Discord handle
-              value: "delegate#1234"
         statement:
+          description: A statement from the delegate describing their voting positions.
           type: string
           examples:
             - summary: Delegate statement
               value: "hello! I am a great delegate for reasons xyz"
-        leastValuableProposals:
-          description: An array of proposal IDs
-          type: array
-          items:
-            type: string
-        mostValuableProposals:
-          description: An array of proposal IDs
-          type: array
-          items: 
-            type: string
         openToSponsoringProposals:
+          description: A boolean flag indicating if this delegate is willing to act as a sponsor for new proposals.
           type: boolean
         topIssues:
+          description: The most important issues for a given delegate.
           type: array
           items: 
               $ref: '#/components/schemas/Issue'
     Issue:
+      summary: Description of a governance issue
+      description: An object describing a particular view on a particular governance issue.
       type: object
       properties:
         type: 
@@ -157,7 +199,7 @@ paths:
                   delegates:
                     type: array
                     items:
-                      $ref: '#/components/schemas/Delegate'
+                      $ref: '#/components/schemas/BaseDelegate'
         '400':
           description: Bad Request
         '401': 
@@ -192,7 +234,7 @@ paths:
           content:
             application/json:
               schema: 
-                $ref: '#/components/schemas/Delegate'
+                $ref: '#/components/schemas/BaseDelegate'
         '400':
           description: Bad Request
         '401': 

From 8cebd15144955aa3e0463f20348dbd5c4d602457 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Thu, 11 Apr 2024 18:02:22 -0400
Subject: [PATCH 12/19] =?UTF-8?q?=F0=9F=93=90=20=F0=9F=92=BB=20add=20reusa?=
 =?UTF-8?q?ble=20datatypes=20for=20proposal,=20vote,=20delegation;=20route?=
 =?UTF-8?q?s=20for=20props?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 278 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 265 insertions(+), 13 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 58b70d639..8f9ec07f5 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -64,14 +64,19 @@ components:
           examples:
           - summary: The datetime on which the delegation of voting power occurred.
         type:
-          $ref: "#/components/schemas/DelegationType"
-    DelegationType:
-      summary: Type of delegation
-      description: The type of delegation; can be advanced or standard.
-      type: string
-      enum:
-        - advanced
-        - standard
+          summary: Type of delegation
+          description: The type of delegation; can be advanced or standard.
+          type: string
+          enum:
+            - advanced
+            - standard
+        amount:
+          summary: Amount delegated
+          description: The amount of voting power delegated; can be full or partial.
+          type: string
+          enum:
+            - full
+            - partial
     BaseDelegate:
       summary: A voting delegate
       description: Data associated with a voting delegate. Sub-resources under this delegate are not expanded. 
@@ -130,6 +135,7 @@ components:
           type: array
           items: 
               $ref: '#/components/schemas/Issue'
+    
     Issue:
       summary: Description of a governance issue
       description: An object describing a particular view on a particular governance issue.
@@ -143,11 +149,165 @@ components:
           type: string
           examples: 
             - "Grant funding should be directed to projects with a great track record"
+    ExecutionData:
+      summary: Structured exceution data for proposal
+      description: >
+        Provides the values, targets, calldata, and signatures provided for proposal execution.
+      type: object
+      properties:
+        values:
+          summary: Values for execution
+          type: string
+        targets:
+          summary: Targets for execution
+          type: string
+        calldata:
+          summary: Calldata for execution
+          type: string
+        signatures:
+          summary: Signatures for execution
+          type: string
+    Proposal: 
+      summary: A specific governance proposal for voting
+      description: >
+        An object describing the specifics and metadata associated with a particular governance proposal,
+        including the specific measure, proposer, data, etc.
+      type: object
+      properites:
+        proposalId:
+          type: string
+        contractAddress:
+          summary: Governor contract address
+          description: Governor contract address to which this proposal was submitted.
+          type: string
+        proposerAddress:
+          summary: Proposer's address
+          description: The address which submitted the proposal for voting.
+          type: string
+        description:
+          summary: Description of the voting measure
+          description: Extended information and context around the proposal.
+          type: string
+        ordinal:
+          summary: Number of this proposal's order
+          description: > 
+            Numeric descriptor of this proposal's ordering among others; Calculated as the concatentation
+            of the proposal's block number left-padded by 10 0's, transaction index left-padded by 3 0's, 
+            and log index left-padded by 3 0's.
+          type: string
+        createBlock:
+          summary: Proposal creation block number
+          description: Block number on which this proposal was created.
+          type: string
+        startBlock:
+          summary: Starting block number
+          description: Block number at which this proposal is open for voting.
+          type: string
+        endBlock:
+          summary: Ending block number
+          description: Block number at which the proposal has closed for voting.
+          type: string
+        cancelledBlock: 
+          summary: Cancelled block number 
+          description: Block number at which this proposal has been canceled. Zero if not canceled.
+          type: string
+        executedBlock:
+          summary: Execution block number 
+          description: Block number at which this proposal has been executed. Zero if not executed.
+          type: string
+        proposalData:
+          $ref: "#/components/schemas/ExecutionData"
+        proposalType:
+          $ref: "#/components/schemas/BaseProposalType"
+    BaseProposalType:  
+      # ADD standard, advanced, optimistic, snapshot enum
+      summary: Metadata about the proposal
+      description: An object describing the particular voting parameters of a proposal.
+      type: object 
+      properties:
+        # How are optimistic and approval types modeled? is there separate logic other than the 
+        # config of the following parameters?
+        name: 
+          summary: Name of proposal type
+          description: Name of proposal type
+          type: string
+        proposalTypeId:
+          summary: Numeric id of the proposal type
+          description: Numeric id of the proposal type
+          type: integer
+        # Note: quorum and threshold are strings since I'm not sure about the unit/size here 
+        # (i.e. if they can be contained in an int32/int64 type)
+        quorum:
+          summary: Minimmum participation for passage
+          description: >
+            The minimum number of voting power needed to be involved in a given proposal as a prerequisite for passage
+          type: string 
+        approvalThreshold:
+          summary: Amount needed for measure to pass 
+          description: The amount of voting power needed to pass the given proposal.
+          type: string
+    ExtendedProposalType:
+      allOf:
+        - $ref: "#/components/schemas/BaseProposalType"
+        - summary: Metadata about the proposal
+          description: An object describing the particular voting parameters of a proposal.
+          type: object
+          properties:
+            contractAddress:
+              summary: Governor contract address
+              description: Governor contract address to which this proposal was submitted.
+              type: string
+            createBlock:
+              summary: Proposal creation block number
+              description: Block number on which this proposal type was created.
+              type: string
+    VoteSupport:
+      summary: Disposition of the vote
+      description: Describes which way the vote was cast (i.e. for/against/abstention)
+      type: string
+      enum: 
+        - FOR 
+        - AGAINST
+        - ABSTENTION
+    Vote:
+      summary: Information about a given vote
+      description: Information and metadata about a specific vote on a governance proposal.
+      type: object
+      properties:
+        transactionId:
+          summary: Transaction ID of the vote
+          description: The transaction ID of the transaction in which the vote was cast.
+          type: string
+        proposalId: 
+          summary: Proposal ID for the vote
+          description: The unique ID of the proposal on which the vote was cast.
+          type: string
+        voterAddress:
+          summary: Address casting the vote
+          description: On-chain address of the EOA or contract which cast the vote.
+          type: string
+        support:
+          $ref: "#/components/schemas/VoteSupport"
+        weight:
+          summary: Voting power behind the vote
+          description: Numeric description of the weight and voting power behind the vote.
+          type: string
+        castBlock:
+          summary: Block in which the vote was cast
+          description: The block number in which the transaction for the cast is contained.
+          type: string 
+        description:
+          summary: Rationale for the vote
+          description: A voter-supplied reason for voting the particular way they did.
+          type: string
+        # Clarify intent
+        approvalParams:
+          $ref: "#/components/schemas/ExecutionData"
   parameters:
-   limitParam:
+    limitParam:
       name: limit
       in: query
-      description: Limits the number of returned results
+      description: Limits the number of returned results.
       required: false
       schema:
         type: integer
@@ -155,16 +315,37 @@ components:
         minimum: 1
         maximum: 100
         default: 10
-   offsetParam:
+    offsetParam:
       name: offset
       in: query
-      description: Offset from which start returned results
+      description: Offset from which start returned results.
       required: false
       schema:
         type: integer
         format: int32
         minimum: 0
         default: 0
+    blockParam: 
+      # What is a reasonable default?
+      name: blockNumber
+      in: query
+      description: The block number in which requested resources are to be sought.
+      required: false
+      schema:
+        type: integer
+        format: int32
+        minimum: 0
+        default: 0
+    supportParam:
+      name: support
+      in: query
+      schema: 
+        $ref: "#/components/schemas/VoteSupport"
+    proposalStatusParam:
+      name: status
+      in: query
+      schema:
+
 paths:
   /delegates:
     get:
@@ -186,6 +367,9 @@ paths:
           required: false
           schema: 
             type: string
+            enum: 
+              - most_delegators
+              - weighted_random
       responses: 
         '200':
           description: OK
@@ -211,7 +395,7 @@ paths:
       summary: Gets a specific delegate.
       description: >
         Retrieves a specific delegate on Agora by address or ENS name.
-      operationId: getDelegate
+      operationId: getDelegateByAddress
       tags: 
         - delegates
       parameters:
@@ -241,5 +425,73 @@ paths:
           description: Unauthorized
         '404':
           description: Not Found
+        '500':
+          description: Internal Server Error
+  /proposals:
+    get:
+      summary: Gets a list of proposals.
+      description: >
+        Retrieves a list of voting proposals on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getProposals
+      tags:
+        - proposals
+      parameters:
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned votes will be sorted.
+            Supported values are: 'status', 'term'
+          required: false
+          schema: 
+            type: string
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Proposal'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /proposals/{proposalId}:
+    get:
+      summary: Gets a specific proposal
+      description: >
+        Retrieves a specific voting proposal on Agora.
+      operationId: getProposalById
+      tags:
+        - proposals
+      parameters:
+        - name: proposalId
+          in: path
+          description: The proposal ID of the proposal to retrieve.
+          required: true
+          schema:
+            type: string
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: "#/components/schemas/Proposal"
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
         '500':
           description: Internal Server Error
\ No newline at end of file

From 4ce62e279facce5bc97a3d35b25ecd8aef72043a Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 02:07:06 -0400
Subject: [PATCH 13/19] =?UTF-8?q?=F0=9F=92=AB=20feedback:=20remove=20openT?=
 =?UTF-8?q?oSponser;=20fix=20typo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 8f9ec07f5..87d09e4d8 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -127,9 +127,6 @@ components:
           examples:
             - summary: Delegate statement
               value: "hello! I am a great delegate for reasons xyz"
-        openToSponsoringProposals:
-          description: A boolean flag indicating if this delegate is willing to act as a sponsor for new proposals.
-          type: boolean
         topIssues:
           description: The most important issues for a given delegate.
           type: array
@@ -457,7 +454,7 @@ paths:
                 properties:
                   metadata:
                     $ref: '#/components/schemas/PageMetadata'
-                  delegates:
+                  proposals:
                     type: array
                     items:
                       $ref: '#/components/schemas/Proposal'

From 3b7eecaff9ce0211912f381938b6390827d5451d Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 13:00:17 -0400
Subject: [PATCH 14/19] =?UTF-8?q?=F0=9F=92=AB=20explicitly=20have=20delega?=
 =?UTF-8?q?te=20and=20delegator=20addresses=20in=20delegation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 87d09e4d8..633c46ed5 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -42,12 +42,19 @@ components:
       description: A delegation of voting power from one address to another.
       type: object
       properties:
-        address: 
-          summary: Delegate address
-          description: Address of the delegator or delegatee.
+        delegatorAddress: 
+          summary: Delegator address
+          description: Address of the delegator.
+          type: string 
+          examples:
+          - summary: Address of the delegator.
+            value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+        delegateeAddress: 
+          summary: Delegatee address
+          description: Address of the delegatee.
           type: string 
           examples:
-          - summary: Address of the delegator or delegatee.
+          - summary: Address of the delegatee.
             value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
         totalAllowance:
           summary: Voting allowance for delegate

From 8878e1f827d2c0c27af04a0b7142875a09150955 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 14:47:55 -0400
Subject: [PATCH 15/19] =?UTF-8?q?=F0=9F=92=AB=F0=9F=92=BB=F0=9F=93=90=20ad?=
 =?UTF-8?q?d=20opt,=20approval,=20std,=20snapshot=20prop=20data;=20propTyp?=
 =?UTF-8?q?e->votingStrategy;=20remove=20extended=20proposal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 214 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 177 insertions(+), 37 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 633c46ed5..e044374b0 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -139,7 +139,6 @@ components:
           type: array
           items: 
               $ref: '#/components/schemas/Issue'
-    
     Issue:
       summary: Description of a governance issue
       description: An object describing a particular view on a particular governance issue.
@@ -153,24 +152,157 @@ components:
           type: string
           examples: 
             - "Grant funding should be directed to projects with a great track record"
+    SnapshotProposalData:
+      summary: Data associated with a snapshot proposal
+      description: >
+        Metadata and data associated with a snapshot proposal, including start/end/created times, scores, and votes. 
+      type: object
+      properties:
+        votingStrategy: 
+          $ref: "#/components/schemas/VotingStrategy"
+        title:
+          summary: Title of the proposal
+          type: string
+        startTimestamp:
+          summary: Start time of the proposal
+          type: string
+          format: date-time
+        endTimestamp:
+          summary: End time of the proposal
+          type: string
+          format: date-time
+        createdTimestamp:
+          summary: Creation time of the proposal
+          type: string
+          format: date-time
+        link:
+          summary: Link to the proposal
+          type: string
+        scores: 
+          summary: Scores for the proposal
+          type: array
+          items:
+            type: string 
+        votes:
+          summary: Votes for the proposal
+          type: string
+        state: 
+          summary: State of the proposal
+          type: string
+          enum: 
+            - ACTIVE
+            - CLOSED
+            - PENDING
+    StandardProposalData: 
+      summary: Data associated with standard proposal 
+      description: >
+        Metadata and data associated with a standard proposal, including onchain execution data.
+      type: object
+      properties:
+        votingStrategy: 
+          $ref: "#/components/schemas/VotingStrategy"
+        options:
+          type: array 
+          items:
+            type: object 
+            properties:
+              executionData:
+                $ref: "#/components/schemas/ExecutionData"
+              signatures:
+                summary: Signatures for the proposal
+                type: array
+                items:
+                  type: string
+    ApprovalProposalData:
+      summary: Data associated with an approval proposal
+      description: >
+        Metadata and data associated with an approval proposal, including onchain execution data.
+      type: object
+      properties:
+        votingStrategy: 
+          $ref: "#/components/schemas/VotingStrategy"
+        options: 
+          type: array 
+          items:
+            type: object 
+            properties:
+              executionData:
+                $ref: "#/components/schemas/ExecutionData"
+              budgetTokensSpent:
+                summary: Budget tokens spent
+                type: string
+              description:
+                summary: Description of the proposal
+                type: string
+        proposalSettings:
+          type: object 
+          properties:
+            maxApprovals: 
+              summary: Maximum approvals for the proposal
+              type: string
+            criteria:
+              summary: Criteria for the proposal
+              type: string
+              enum:
+                - THRESHOLD
+                - TOP_CHOICES
+            budgetToken: 
+              summary: Budget token for the proposal
+              type: string
+            criteriaValue:
+              summary: Criteria value for the proposal
+              type: string
+            budgetAmount:
+              summary: Budget amount for the proposal
+              type: string
+    OptimisticProposalData:
+      summary: Data associated with an optimistic proposal
+      description: >
+        Metadata and data associated with an optimistic proposal, including onchain execution data.
+      type: object
+      properties:
+        votingStrategy: 
+          $ref: "#/components/schemas/VotingStrategy"
+        executionData:
+          $ref: "#/components/schemas/ExecutionData"
+        description:
+          summary: Description of the proposal
+          type: string
     ExecutionData:
       summary: Structured exceution data for proposal
       description: >
-        Provides the values, targets, calldata, and signatures provided for proposal execution.
-      type: object
+        Provides the values, targets, calldata, and functions for proposal execution.
+      type: object 
       properties:
         values:
           summary: Values for execution
-          type: string
+          type: array 
+          items:
+            type: string
         targets:
           summary: Targets for execution
-          type: string
+          type: array 
+          items:
+            type: string
         calldata:
           summary: Calldata for execution
-          type: string
-        signatures:
-          summary: Signatures for execution
-          type: string
+          type: array 
+          items:
+            type: string
+        functionData:
+          summary: Functions for execution
+          type: array 
+          items:
+            type: object 
+            properties:
+              functionName:
+                summary: Function name
+                type: string
+              data:
+                summary: Data for function
+                type: array 
+                items:
+                  type: string 
     Proposal: 
       summary: A specific governance proposal for voting
       description: >
@@ -220,25 +352,31 @@ components:
           description: Block number at which this proposal has been executed. Zero if not executed.
           type: string
         proposalData:
-          $ref: "#/components/schemas/ExecutionData"
-        proposalType:
-          $ref: "#/components/schemas/BaseProposalType"
-    BaseProposalType:  
-      # ADD standard, advanced, optimistic, snapshot enum
+          oneOf: 
+            - $ref: "#/components/schemas/SnapshotProposalData"
+            - $ref: "#/components/schemas/StandardProposalData"
+            - $ref: "#/components/schemas/ApprovalProposalData"
+            - $ref: "#/components/schemas/OptimisticProposalData"
+          discriminator:
+            propertyName: votingStrategy
+        proposalTemplate:
+          $ref: "#/components/schemas/ProposalTemplate"
+    ProposalTemplate:  
       summary: Metadata about the proposal
-      description: An object describing the particular voting parameters of a proposal.
+      description: > 
+        An object describing the particular voting parameters of a proposal.
       type: object 
       properties:
-        # How are optimistic and approval types modeled? is there separate logic other than the 
-        # config of the following parameters?
         name: 
-          summary: Name of proposal type
-          description: Name of proposal type
+          summary: Name of proposal template 
+          description: Name of proposal template 
           type: string
-        proposalTypeId:
-          summary: Numeric id of the proposal type
-          description: Numeric id of the proposal type
+        proposalTemplateId:
+          summary: Numeric id of the proposal template
+          description: Numeric id of the proposal template 
           type: integer
+        votingStrategy:
+          $ref: "#/components/schemas/VotingStrategy" 
         # Note: quorum and threshold are strings since I'm not sure about the unit/size here 
         # (i.e. if they can be contained in an int32/int64 type)
         quorum:
@@ -250,21 +388,23 @@ components:
           summary: Amount needed for measure to pass 
           description: The amount of voting power needed to pass the given proposal.
           type: string
-    ExtendedProposalType:
-      allOf:
-        - $ref: "#/components/schemas/BaseProposalType"
-        - summary: Metadata about the proposal
-          description: An object describing the particular voting parameters of a proposal.
-          type: object
-          properties:
-            contractAddress:
-              summary: Governor contract address
-              description: Governor contract address to which this proposal was submitted.
-              type: string
-            createBlock:
-              summary: Proposal creation block number
-              description: Block number on which this proposal type was created.
-              type: string
+        contractAddress:
+          summary: Governor contract address
+          description: Governor contract address to which this proposal was submitted.
+          type: string
+        createBlock:
+          summary: Proposal creation block number
+          description: Block number on which this proposal template was created.
+          type: string
+    VotingStrategy: 
+      summary: The voting strategy for a proposal
+      description: Enum description of the proposal's voting strategy.
+      type: string
+      enum: 
+        - STANDARD
+        - ADVANCED
+        - OPTIMISTIC
+        - SNAPSHOT
     VoteSupport:
       summary: Disposition of the vote
       description: Describes which way the vote was cast (i.e. for/against/abstention)

From cc87c4ef2c5c6458e7edc109afc6de80a4c9a14f Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 14:54:42 -0400
Subject: [PATCH 16/19] =?UTF-8?q?=F0=9F=92=AB=20array=20of=20strings=20for?=
 =?UTF-8?q?=20approval=20params?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index e044374b0..a0a299da7 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -444,9 +444,12 @@ components:
           summary: Rationale for the vote
           description: A voter-supplied reason for voting the particular way they did.
           type: string
-        # Clarify intent
         approvalParams:
-          $ref: "#/components/schemas/ExecutionData"
+          summary: Array of items to submit for approval 
+          description: An array of items to submit for approval for multiple choice votes.
+          type: array
+          items:
+            type: string
   parameters:
     limitParam:
       name: limit

From c33269cae379625439c8e1e88ba89cb2f6331f4e Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 17:13:55 -0400
Subject: [PATCH 17/19] =?UTF-8?q?=F0=9F=92=BB=20/spec=20route=20for=20OAS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index a0a299da7..3a2f26fdf 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -494,6 +494,26 @@ components:
       schema:
 
 paths:
+  /spec:
+    get: 
+      summary: Gets this specification
+      description: Retrieves the full OAS/Swagger spec for the API in YAML.
+      operationId: getSpec
+      tags:
+        - spec
+      responses: 
+        '200':
+          description: OK
+          content:
+            text/plain:
+              schema:
+                type: string
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
   /delegates:
     get:
       summary: Gets a list of delegates.

From 6b368de26ed22ae894eab3524eb77061ed0f2aa5 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 17:14:42 -0400
Subject: [PATCH 18/19] =?UTF-8?q?=F0=9F=92=BB=F0=9F=93=90=20add=20routes?=
 =?UTF-8?q?=20+=20contract=20schema?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 385 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 385 insertions(+)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 3a2f26fdf..933899ced 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -450,6 +450,27 @@ components:
           type: array
           items:
             type: string
+    Contract:
+      summary: Information about a deployed contract
+      description: Metadata about a specific smart contract deployed on chain.
+      type: object
+      properties:
+          address:
+            summary: Contract address
+            description: The address of the contract on chain.
+            type: string
+          deployer:
+            summary: Deployer address
+            description: The address of the entity which deployed the contract.
+            type: string
+          creationBlock:
+            summary: Block in which the contract was deployed
+            description: The block number in which the contract was deployed.
+            type: string
+          transactionId:
+            summary: Transaction ID of the deployment
+            description: The transaction ID of the transaction in which the contract was deployed.
+            type: string
   parameters:
     limitParam:
       name: limit
@@ -594,6 +615,63 @@ paths:
           description: Not Found
         '500':
           description: Internal Server Error
+  /delegates/{addressOrEnsName}/votes:
+    get:
+      summary: Gets a paginated list of votes.
+      description: >
+        Retrieves a paginated list of votes for a specific proposal on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getDelegateVotes
+      tags:
+        - delegates 
+        - votes
+      parameters:
+        - name: addressOrEnsName
+          in: path
+          description: The address or ENS name of the delegate to retrieve
+          required: true
+          schema:
+            type: string
+          examples: 
+            address: 
+              value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+              summary: Address of the delegate. 
+            ensName:
+              value: "flipliquid.eth"
+              summary: ENS name of the delegate.
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned delegates will be sorted.
+            Supported values are: 'weight' for descending voting weight, or 'block' for descending block number
+          required: false
+          schema: 
+            type: string
+            enum: 
+              - weight
+              - block
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Vote'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
   /proposals:
     get:
       summary: Gets a list of proposals.
@@ -660,5 +738,312 @@ paths:
           description: Bad Request
         '401': 
           description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /proposals/{proposalId}/votes:
+    get:
+      summary: Gets a paginated list of votes.
+      description: >
+        Retrieves a paginated list of votes for a specific proposal on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getProposalVotes
+      tags:
+        - proposals 
+        - votes
+      parameters:
+        - name: proposalId
+          in: path
+          description: The proposal ID of the proposal to retrieve.
+          required: true
+          schema:
+            type: string
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned delegates will be sorted.
+            Supported values are: 'weight' for descending voting weight, or 'block' for descending block number
+          required: false
+          schema: 
+            type: string
+            enum: 
+              - weight
+              - block
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Vote'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /delegatees/{addressOrEnsName}:
+    get:
+      summary: Gets delegatee (delegating from) information for an address
+      description: >
+        Retrieves a paginated list of the delegatees for a given address. That is, the delegates to which
+        the supplied address is delegating votes.
+      operationId: getDelegateesByAddress
+      tags: 
+        - delegates
+        - delegations
+      parameters:
+        - name: addressOrEnsName
+          in: path
+          description: The address or ENS name of the delegate to retrieve
+          required: true
+          schema:
+            type: string
+          examples: 
+            address: 
+              value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+              summary: Address of the delegate. 
+            ensName:
+              value: "flipliquid.eth"
+              summary: ENS name of the delegate.
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Delegation'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+  /delegators/{addressOrEnsName}:
+    get:
+      summary: Gets delegator (delegating to) information for an address
+      description: >
+        Retrieves a paginated list of the delegators for a given address. That is, the delegates from which
+        the supplied address is being delegated votes.
+      operationId: getDelegatorsByAddress
+      tags: 
+        - delegates
+        - delegations
+      parameters:
+        - name: addressOrEnsName
+          in: path
+          description: The address or ENS name of the delegate to retrieve
+          required: true
+          schema:
+            type: string
+          examples: 
+            address: 
+              value: "0xDa6d1F091B672C0f9e215eB9fa6B5a84bF2c5e11"
+              summary: Address of the delegate. 
+            ensName:
+              value: "flipliquid.eth"
+              summary: ENS name of the delegate.
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Delegation'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+  /votes:
+    get:
+      summary: Gets a paginated list of votes.
+      description: >
+        Retrieves a paginated list of votes on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getVotes
+      tags:
+        - votes
+      parameters:
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned delegates will be sorted.
+            Supported values are: 'most_delegators', 'weighted_random'
+          required: false
+          schema: 
+            type: string
+            enum: 
+              - most_delegators
+              - weighted_random
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Vote'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /votes/{transactionId}:
+    get:
+      summary: Gets a specific vote.
+      description: >
+        Retrieves a specific vote on Agora.
+      operationId: getVoteByTransactionId
+      tags:
+        - votes
+      parameters:
+        - name: transactionId
+          in: path
+          description: >
+            The transactionId in which the vote was cast
+          required: true
+          schema: 
+            type: string
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Vote'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /proposals/types:
+    get:
+      summary: Gets a paginated list of proposal types.
+      description: >
+        Retrieves a paginated list of proposal types on Agora as a JSON array.
+        Limit, offset, and sort parameters can be used to customize the returned list.
+      operationId: getProposalTypes
+      tags:
+        - proposals
+        - proposalTypes
+      parameters:
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/offsetParam"
+        - name: sort
+          in: query
+          description: >
+            The desired method by which returned delegates will be sorted.
+            Supported values are: 'most_delegators', 'weighted_random'
+          required: false
+          schema: 
+            type: string
+            enum: 
+              - most_delegators
+              - weighted_random
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                type: object
+                properties:
+                  metadata:
+                    $ref: '#/components/schemas/PageMetadata'
+                  delegates:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ProposalTemplate'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /contracts/governor:
+    get:
+      summary: Gets the governor contract address
+      description: >
+        Retrieves the address of the governor contract on chain.
+      operationId: getGovernorContract
+      tags:
+        - contracts
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Contract'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /contracts/alligator:
+    get:
+      summary: Gets the alligator contract address
+      description: >
+        Retrieves the address of the alligator contract on chain.
+      operationId: getAlligatorContract
+      tags:
+        - contracts
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Contract'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
+        '500':
+          description: Internal Server Error
+  /contracts/votingToken:
+    get:
+      summary: Gets the voting token contract address
+      description: >
+        Retrieves the address of the voting token contract on chain.
+      operationId: getVotingTokenContract
+      tags:
+        - contracts
+      responses: 
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: 
+                $ref: '#/components/schemas/Contract'
+        '400':
+          description: Bad Request
+        '401': 
+          description: Unauthorized
         '500':
           description: Internal Server Error
\ No newline at end of file

From 3f943502527e4cdee3d7015b7342e3b610897a66 Mon Sep 17 00:00:00 2001
From: Flip Liquid <13227294+Flip-Liquid@users.noreply.github.com>
Date: Fri, 12 Apr 2024 17:18:52 -0400
Subject: [PATCH 19/19] =?UTF-8?q?=F0=9F=92=AB=F0=9F=A4=8F=20abstention->ab?=
 =?UTF-8?q?stain;=20remove=20dup'd=20signatures?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spec/oas_v1.yaml | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/spec/oas_v1.yaml b/spec/oas_v1.yaml
index 933899ced..11085c0c8 100644
--- a/spec/oas_v1.yaml
+++ b/spec/oas_v1.yaml
@@ -208,11 +208,6 @@ components:
             properties:
               executionData:
                 $ref: "#/components/schemas/ExecutionData"
-              signatures:
-                summary: Signatures for the proposal
-                type: array
-                items:
-                  type: string
     ApprovalProposalData:
       summary: Data associated with an approval proposal
       description: >
@@ -412,7 +407,7 @@ components:
       enum: 
         - FOR 
         - AGAINST
-        - ABSTENTION
+        - ABSTAIN
     Vote:
       summary: Information about a given vote
       description: Information and metadata about a specific vote on a governance proposal.