## 🔍 About Cardano Governance Explorer
Cardano Governance Explorer is a comprehensive platform for exploring Cardano's on-chain governance ecosystem. It provides AI-powered analytics and natural language interfaces to make blockchain governance accessible and understandable for everyone.
## 📚 Documentation Overview
This repository contains the official API documentation for the Cardano Governance Explorer, built with [Mintlify](https://mintlify.com/). Our comprehensive documentation covers:
- **DRep Explorer**: Search and filter Delegated Representatives (DReps) based on various criteria
- **Proposal Explorer**: Analyze governance proposals with AI-powered insights
- **Rationale Explorer**: Understand the reasoning behind governance votes
## 🚀 Getting Started
### Prerequisites
- Node.js (version 19 or higher)
- npm or yarn
### Installation
1. Clone this repository:
```bash
git clone https://github.com/Nucastio/sync-ai-api.git
cd docs
```
2. Install the Mintlify CLI:
```bash
npm install -g mintlify
```
3. Run the documentation locally:
```bash
mintlify dev
```
The documentation will be available at `http://localhost:3000`.
## 🧩 Project Structure
```
docs/
├── README.md # This file
├── docs.json # Main configuration file
├── index.mdx # Homepage
├── api-reference/ # API reference documentation
│ ├── introduction.mdx # API introduction
│ ├── drep-api.mdx # DRep API documentation
│ ├── proposal-api.mdx # Proposal API documentation
│ └── rationale-api.mdx # Rationale API documentation
├── user-guide/ # User guides
│ ├── drep-explorer.mdx # DRep Explorer guide
│ ├── proposal-explorer.mdx # Proposal Explorer guide
│ └── rationale-explorer.mdx # Rationale Explorer guide
├── images/ # Images for the documentation
├── logo/ # Logo files
└── snippets/ # Reusable content snippets
```
## 🔧 Customizing the Documentation
### Adding New Pages
1. Create a new `.mdx` file in the appropriate directory.
2. Add the page to the navigation in `docs.json`.
### Updating the OpenAPI Specification
1. Update the API reference files with your changes.
2. Run `mintlify dev` to see the changes.
## 🤝 Contributing
1. Create a new branch for your changes.
2. Make your changes and test them locally using `mintlify dev`.
3. Commit your changes and push them to your branch.
4. Create a pull request to merge your changes into the main branch.
## 📞 Need Help?
If you need assistance with the documentation, please contact:
- Email: [adnan@syncai.pro](mailto:adnan@syncai.pro)
- GitHub: Open an issue in this repository
================================================
FILE: docs/docs.json
================================================
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Cardano Governance Explorer API Documentation",
"colors": {
"primary": "#2091ff",
"light": "#4ba9ff",
"dark": "#0d6ecc"
},
"background": {
"color": {
"light": "#fff",
"dark": "#000"
}
},
"banner": {
"dismissible": true,
"content": "🚀 Cardano Governance Explorer is now live! Visit our [Dashboard](https://syncgovhub.com/app) to explore Cardano's governance ecosystem."
},
"contextual": {
"options": [
"copy",
"view"
]
},
"appearance": {
"default": "dark"
},
"favicon": "/logo/favicon.png",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "Get Started",
"pages": [
"index"
]
},
{
"group": "User Guide",
"pages": [
"user-guide/drep-explorer",
"user-guide/proposal-explorer",
"user-guide/rationale-explorer"
]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "Overview",
"pages": [
"api-reference/introduction"
]
},
{
"group": "DRep API",
"pages": [
"api-reference/drep-api"
]
},
{
"group": "Proposal API",
"pages": [
"api-reference/proposal-api"
]
},
{
"group": "Rationale API",
"pages": [
"api-reference/rationale-api"
]
}
]
}
],
"global": {
"anchors": [
{
"anchor": "Dashboard",
"href": "https://syncgovhub.com/app",
"icon": "gauge"
}
]
}
},
"logo": {
"light": "/logo/logo-light.svg",
"dark": "/logo/logo-dark.svg"
},
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:adnan@syncai.pro"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://syncgovhub.com/app"
}
},
"footer": {
"socials": {
"x": "https://x.com/SyncAI_Network",
"discord": "https://discord.gg/syncainetwork"
}
},
"api": {
"playground": {
"display": "interactive"
},
"mdx": {
"server": "https://api.syncgovhub.com"
}
}
}
================================================
FILE: docs/index.mdx
================================================
---
title: 'Introduction'
description: 'Overview of the Cardano Governance Explorer API'
icon: "code"
---
# API Reference
**AI-Powered Analytics**: The Cardano Governance Explorer API provides AI-enhanced endpoints to query and analyze Cardano's on-chain governance data using natural language.
The API enables developers to access and integrate the power of our AI-driven blockchain governance analytics into their own applications, providing seamless access to DRep data, proposal analysis, and vote rationale insights.
## API Structure
The Cardano Governance Explorer API is divided into three main categories, each serving a specific purpose:
Explore and filter Delegated Representatives (DReps) using natural language queries
Analyze governance proposals with AI-powered insights
Extract insights from voting rationales across stakeholder groups
## Authentication
**API Key Required**: All API endpoints require an API key for authentication.
Include your API key in the header of all requests:
```bash
x-api-key: YOUR_API_KEY
```
To obtain an API key, register at the [Cardano Governance Explorer Dashboard](https://syncgovhub.com/app).
## Base URL
All API requests should be made to:
```plaintext
https://api.syncgovhub.com
```
## Request Format
All API endpoints accept POST requests with a JSON body. Make sure to set the appropriate headers:
```bash
x-api-key: YOUR_API_KEY
```
## Response Format
All API responses follow a consistent structure:
```json
{
"data": {
// The main response data
},
"meta": {
// Metadata about the request and response
"timings": {
// Performance metrics
}
}
}
```
## Error Handling
When an error occurs, the API returns an appropriate HTTP status code and a JSON object explaining the error:
```json
{
"error": "Descriptive error message",
"details": "Additional information when available"
}
```
Common HTTP status codes:
| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters or request format |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Resource does not exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |
## Rate Limiting
To ensure service stability, API requests are rate-limited to:
- 60 requests per minute per API key
- 1,000 requests per day per API key
If you exceed these limits, you'll receive a `429 Too Many Requests` status code.
## Support
If you encounter any issues or have questions about the API, reach out to our support team at [adnan@syncai.pro](mailto:adnan@syncai.pro).
================================================
FILE: docs/.gitignore
================================================
/api-reference/openapi.json
================================================
FILE: docs/api-reference/drep-api.mdx
================================================
---
title: 'DRep AI'
api: 'POST /api/drep/ai'
description: 'Search and filter Delegated Representatives (DReps) using natural language queries'
---
**Natural Language Queries**: The DRep API allows you to search and filter Cardano's Delegated Representatives using plain English, making complex blockchain data more accessible.
The DRep API enables you to find DReps based on a wide range of criteria, including their attributes (voting power, delegators, participation rate) and their voting behavior on specific proposals.
## Request Headers
Your API key for authentication
## Request Body
Natural language query describing the DReps you want to find
Page number for pagination
Number of results per page (maximum 100)
## Response
Array of DReps matching the query
Unique identifier for the DRep
Internal database ID
Name of the DRep
Current status (active, inactive)
Amount of ADA delegated to this DRep
Number of delegators
Percentage of proposals voted on
Alignment score with community consensus
Number of proposals this DRep has voted on
Number of proposals this DRep was allowed to vote on
Total number of proposals in the system
URLs and social media links associated with the DRep
DRep's stated motivations for participation
DRep's stated objectives
DRep's qualifications
URL to profile picture (if available)
ISO timestamp of registration
Username (usually same as drepId)
Whether the vote aligned with majority ("aligned", "opposed", "not_voted")
Date of the vote (YYYY-MM-DD)
Global alignment percentage for this vote
ID of the proposal
Title of the proposal
The majority vote on this proposal
URL to the proposal details
Proposal rationale
Type of proposal (InfoAction, ParameterChange, etc.)
Subtype of proposal (if applicable)
DRep's vote (Yes, No, Abstain)
Whether DRep voting was allowed on this proposal
Date when the DRep became active
Detailed metadata about the DRep
Geographic location (if provided)
Primary URL associated with the DRep
Additional links associated with the DRep
Timestamp when the record was created
Timestamp when the record was last updated
AI-generated explanation of the results
Original query string
How the AI interpreted your query
Type of query (e.g., "proposal_first", "drep_first", "balanced")
Filters applied to proposals
Filters applied to votes
Filters applied to DRep attributes
Explanation of how the query was interpreted
Detected intent of the query
Proposals that matched your query criteria
Proposal ID
Proposal title
Proposal type
Proposal subtype (if applicable)
Whether DRep voting is allowed for this proposal
Number of results returned in this response
Proposal titles that could not be found (if any)
Alternative proposals suggested when exact matches aren't found
Current page number
Results per page
Total number of matching results
Total number of pages
Performance metrics for the request
Time taken to determine query intent (ms)
Time taken to parse the query (ms)
Time taken to execute database queries (ms)
Time taken to transform data (ms)
Time taken to generate the explanation (ms)
Time taken to validate proposals (ms)
Total request processing time (ms)
```json 200 (Success)
{
"data": [
{
"drepId": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
"id": "dc3cfd1e-3308-4223-adf6-da1662a1b4b0",
"links": [
"x.com/Crown_Tech1021",
"crown-tech.co.jp/ctecstakepool",
"https://www.crown-tech.co.jp/DRep/CTEC-Stake-Pool.jsonld"
],
"metrics": {
"participationRate": 100,
"votingPower": 19829102.491109,
"communityAlignment": 0,
"proposalsVoted": 12,
"globalAlignment": 54.19,
"totalDelegators": 33,
"totalAllowedProposals": 12,
"totalProposals": 18
},
"motivations": "●目標：Target\n\n・安全で安心できるカルダノネットワークを運営する\n\n Operate a safe and secure Cardano network.\n\n・カルダノネットワークをより高度な次元へ発展させるために貢献する\n\n Contribute to the development of the Cardano network to a higher dimension.\n",
"name": "CTEC-Stake-Pool",
"objectives": "●ミッション：mission\n\nカルダノネットワークの発展のためにDRepとして活動していきます\n\nI will work as a DRep for the development of the Cardano network.",
"profilePic": null,
"qualifications": "●資格：Qualifications\n\n CTEC Stake Pool Operator（SPO）",
"registration_date": "2024-11-14T09:54:59+00:00",
"status": "active",
"username": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
"voting_history": [
{
"communityAlignment": "Coming Soon",
"alignmentStatus": "aligned",
"date": "2025-03-25",
"globalAlignment": 54.19,
"id": "1b75c28f-e77b-4304-b050-9ee894d863f5",
"isAligned": true,
"proposalId": "gov_action1nd3t833j7v5sz65k3tp9yyvztw60sjcjgcgjr37682s3m7frwrusqmd2k80",
"isIncluded": true,
"proposalTitle": "2025 Net Change Limit",
"majorityVote": "Yes",
"proposalUrl": "ipfs://bafkreiaqno22swabd3kcqt2awtgwaucdzaagacoemxwadm3exrchhnfite",
"rationale": "As agreed with the Cardano Budget Committee, the 2025 Net Change Limit shall begin at the start of Epoch 532 and progress for 72 epochs, concluding in December 2025 at the end of Epoch 604.\n\nThe 2025 Net Change Limit shall be set at 350,000,000,000,000 lovelace (350M ada).\n\nThis figure is derived from our modeling, which projected in October 2024 that the treasury would increase by approximately 351M ada across 2024 (epoch 459-531), including all approved withdrawals (e.g., Catalyst). Based on this analysis, the 2025 Net Change Limit was proposed at 350m ada. From January 5th, 2024, Epoch 459, through December 30th, Epoch 531, the actual total income into the Cardano Treasury was 335,957,093 ada. Since this is within 5% of our proposed number, the 2025 Net Change Limit should stay at 350 million ada.",
"type": "InfoAction",
"subtype": null,
"vote": "Yes",
"drepVotingAllowed": true
}
],
"active_since": "2024-11-14T09:54:59",
"metadata": {
"drep_id": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
"hex": "22aa61eb75dd91ff67c73ea168bb39f5fd1de0792408cb8dc2b4094ec8",
"url": "https://www.crown-tech.co.jp/DRep/CTEC-Stake-Pool.jsonld",
"hash": "d679b05cc0de219e47c11333bc1faf0caa6b75d480dbf406b69a60016ef8b551",
"json_metadata": { /* ... detailed metadata ... */ },
"bytes": "\\x7b0a20202240636f...",
"location": null,
"other_links": [
"x.com/Crown_Tech1021",
"crown-tech.co.jp/ctecstakepool"
],
"created_at": "2025-04-09T10:27:41.477642+00:00",
"updated_at": "2025-05-21T03:14:13.159637+00:00"
}
}
],
"meta": {
"explanation": "A total of 194 DReps voted 'yes' on the \"2025 Net Change Limit\" proposal. These DReps have an average voting power of 10,794,519 ADA and an average participation rate of 80.77%, indicating active engagement in governance. The wide range of DReps underscores diverse participation within the community.",
"query": "Find DReps who voted yes on the net change limit (Referring to these proposals: 2025 Net Change Limit)",
"parsedQuery": {
"queryType": "proposal_first",
"proposalFilters": {
"title": {
"any": [
"2025 Net Change Limit"
]
}
},
"voteFilters": {
"vote": "yes",
"voterRole": "DRep"
},
"drepFilters": {},
"explanation": "The query is focused on finding DReps who voted 'yes' on the proposal titled '2025 Net Change Limit'. No specific DRep status or additional filters were specified."
},
"queryIntent": "proposal_first",
"matchedProposals": [
{
"id": "gov_action1nd3t833j7v5sz65k3tp9yyvztw60sjcjgcgjr37682s3m7frwrusqmd2k80",
"title": "2025 Net Change Limit",
"type": "InfoAction",
"subtype": null,
"drepVotingAllowed": true
}
],
"resultCount": 1
},
"pagination": {
"page": 1,
"limit": 10,
"total": 194,
"pages": 20
},
"timings": {
"intent_determination": 1631,
"query_parsing": 5060,
"database_queries": 609,
"data_transformation": 0,
"explanation_generation": 2917,
"proposal_validation": 6649,
"total": 13901
}
}
```
```json 400 (Bad Request)
{
"error": "Missing or invalid query",
"details": "Please provide a valid query string"
}
```
```json 401 (Unauthorized)
{
"error": "Unauthorized",
"message": "API key is required"
}
```
```json 404 (Not Found)
{
"error": "No DReps found matching your criteria",
"details": "Try different search terms or check if there are proposals with the specified criteria"
}
```
```json 500 (Internal Server Error)
{
"error": "Failed to process query",
"details": "Internal server error occurred while processing the request"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Success - DReps found matching the criteria |
| 400 | Bad Request - Invalid query parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 404 | Not Found - No DReps found matching the criteria |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
## Notes
**AI-Powered Query Processing**: The API uses AI to interpret natural language queries. It analyzes the intent (finding DReps, exploring proposals, or both) and extracts relevant filters to apply to the database. This allows for a more intuitive and flexible way to search for DReps.
**Performance Considerations**: Queries with complex filters or multiple proposal criteria may take longer to process. Consider using more specific queries for faster results, especially when searching across a large number of proposals or DReps.
================================================
FILE: docs/api-reference/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Overview of the Cardano Governance Explorer API'
---
# API Reference
**AI-Powered Analytics**: The Cardano Governance Explorer API provides AI-enhanced endpoints to query and analyze Cardano's on-chain governance data using natural language.
The API enables developers to access and integrate the power of our AI-driven blockchain governance analytics into their own applications, providing seamless access to DRep data, proposal analysis, and vote rationale insights.
## API Structure
The Cardano Governance Explorer API is divided into three main categories, each serving a specific purpose:
Explore and filter Delegated Representatives (DReps) using natural language queries
Analyze governance proposals with AI-powered insights
Extract insights from voting rationales across stakeholder groups
## Authentication
**API Key Required**: All API endpoints require an API key for authentication.
Include your API key in the header of all requests:
```bash
x-api-key: YOUR_API_KEY
```
To obtain an API key, register at the [Cardano Governance Explorer Dashboard](https://syncgovhub.com/app).
## Base URL
All API requests should be made to:
```plaintext
https://api.syncgovhub.com
```
## Request Format
All API endpoints accept POST requests with a JSON body. Make sure to set the appropriate headers:
```bash
x-api-key: YOUR_API_KEY
```
## Response Format
All API responses follow a consistent structure:
```json
{
"data": {
// The main response data
},
"meta": {
// Metadata about the request and response
"timings": {
// Performance metrics
}
}
}
```
## Error Handling
When an error occurs, the API returns an appropriate HTTP status code and a JSON object explaining the error:
```json
{
"error": "Descriptive error message",
"details": "Additional information when available"
}
```
Common HTTP status codes:
| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters or request format |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Resource does not exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |
## Rate Limiting
To ensure service stability, API requests are rate-limited to:
- 60 requests per minute per API key
- 1,000 requests per day per API key
If you exceed these limits, you'll receive a `429 Too Many Requests` status code.
## Support
If you encounter any issues or have questions about the API, reach out to our support team at [adnan@syncai.pro](mailto:adnan@syncai.pro).
================================================
FILE: docs/api-reference/proposal-api.mdx
================================================
---
title: 'Proposal AI'
api: 'POST /api/proposal/ai'
description: 'Ask questions about governance proposals and receive AI-powered analysis'
---
**Intelligent Analysis**: This endpoint provides detailed, context-aware answers to questions about specific governance proposals or general proposal patterns using advanced AI.
The Proposal API enables you to ask natural language questions about Cardano governance proposals and receive detailed analysis based on the proposal content, metadata, and related documents. It can analyze specific proposals or provide insights on patterns across multiple proposals.
## Request Headers
Your API key for authentication
## Request Body
Natural language question about a proposal
ID of the specific proposal to analyze. If omitted, the API will analyze across all proposals.
## Response
AI-generated analysis responding to the query
ID of the analyzed proposal (if govaction_id was provided)
Title of the analyzed proposal (if govaction_id was provided)
Type of the analyzed proposal (if govaction_id was provided)
Subtype of the analyzed proposal, if applicable (if govaction_id was provided)
Original query string
Sources of content used in the analysis
URL of the content source
Whether this is the primary metadata URL
Type of content (e.g., "proposal", "discussion", "technical-reference", "markdown")
Performance metrics for the request
Time taken to fetch proposal data (ms)
Time taken to search relevant content (ms)
Time taken for AI analysis (ms)
Total request processing time (ms)
```json 200 (Specific Proposal)
{
"data": {
"analysis": "## Parameter Change Analysis\n\nThis proposal suggests modifying the protocol parameter `minPoolCost` from 340 ADA to 170 ADA. This parameter sets the minimum fixed cost that stake pool operators (SPOs) can charge for operating a pool.\n\n### Main Objectives\n\nThe primary goal of this proposal is to lower the entry barrier for new stake pool operators by reducing the minimum fixed cost requirement by 50%. This change aims to enhance decentralization by making it more economically viable to operate smaller stake pools.\n\n### Technical Implications\n\nThe `minPoolCost` parameter directly affects stake pool economics in the following ways:\n\n1. **Pool Profitability**: Reducing this parameter allows pool operators to set lower fixed costs, potentially making smaller pools more competitive\n2. **Delegator Rewards**: Lower fixed costs could translate to higher returns for delegators of smaller pools\n3. **Network Topology**: The change may encourage the creation of more pools, potentially increasing network decentralization\n\n### Community Sentiment\n\nThe proposal received strong support from the DRep community, with 87.2% voting in favor. SPOs were more divided with 62.4% in favor, suggesting some existing operators have concerns about increased competition or potential impacts on the sustainability of smaller pools.\n\nThe total voting participation was high at 78.3%, indicating significant community interest in this parameter change.",
"proposal_id": "gov1x8jkz74",
"proposal_title": "Reduce minPoolCost Parameter from 340 to 170 ADA",
"proposal_type": "ParameterChange",
"proposal_subtype": "Economic"
},
"meta": {
"query": "What are the main objectives and implications of this parameter change?",
"content_sources": [
{
"url": "https://governance.cardano.org/en/proposals/gov1x8jkz74",
"is_meta_url": true,
"content_type": "proposal"
},
{
"url": "https://github.com/cardano-foundation/cips/blob/master/CIP-0094/README.md",
"is_meta_url": false,
"content_type": "technical-reference"
},
{
"url": "https://forum.cardano.org/t/discussion-reduce-minpoolcost-parameter-from-340-to-170-ada/128975",
"is_meta_url": false,
"content_type": "discussion"
}
],
"timings": {
"fetch_proposal_data": 125,
"search_content": 452,
"openai_analysis": 2351,
"total": 2928
}
}
}
```
```json 200 (Cross-Proposal Analysis)
{
"data": {
"analysis": "## Parameter Change Proposals - Common Patterns\n\nBased on the analysis of parameter change proposals in the Cardano governance system, several key patterns emerge:\n\n### 1. Economic Parameter Changes\n\nThe most common parameter modifications focus on economic aspects of the protocol:\n\n- **Pool Economics**: Adjustments to `minPoolCost` and `poolPledgeInfluence` parameters are frequent, aiming to balance pool operator sustainability with delegator returns\n- **Transaction Costs**: Changes to `minFeeA`, `minFeeB`, and related parameters to optimize transaction pricing\n- **Monetary Policy**: Fine-tuning of staking rewards and incentive mechanisms\n\n### 2. Technical Parameter Changes\n\nTechnical parameters are typically adjusted in response to network performance or security considerations:\n\n- **Block Size**: Gradual increases to `maxBlockSize` to improve throughput as network capacity grows\n- **Script Limits**: Adjustments to script execution limits to balance computational constraints with dApp functionality\n- **Protocol Security**: Conservative modifications to security parameters with extensive testing evidence\n\n### 3. Governance Parameters\n\nChanges to governance rules themselves represent a smaller but significant category:\n\n- **Voting Thresholds**: Adjustments to participation thresholds and majority requirements\n- **DRep Mechanics**: Refinements to delegation and voting power calculations\n\n### Common Success Factors\n\nSuccessful parameter change proposals typically share these characteristics:\n\n1. Clear technical justification with empirical evidence\n2. Gradual rather than radical parameter adjustments\n3. Thorough impact analysis discussing potential trade-offs\n4. Active engagement with community feedback during drafting\n5. Transparent benchmarking data when performance claims are made\n\nProposals lacking these elements tend to receive less support or face significant opposition during voting."
},
"meta": {
"query": "What are the common patterns in parameter change proposals?",
"content_sources": [
{
"url": "https://governance.cardano.org/en/proposals/",
"is_meta_url": false,
"content_type": "proposal-list"
},
{
"url": "https://github.com/cardano-foundation/cips/tree/master/",
"is_meta_url": false,
"content_type": "technical-reference"
},
{
"url": "https://forum.cardano.org/c/governance/29",
"is_meta_url": false,
"content_type": "discussion"
}
],
"timings": {
"fetch_proposal_data": 320,
"search_content": 865,
"openai_analysis": 2758,
"total": 3943
}
}
}
```
```json 200 (Constitution Analysis)
{
"data": {
"analysis": "# Analysis of ARTICLE IV. THE CARDANO BLOCKCHAIN ECOSYSTEM BUDGET\n\n## Overview\nARTICLE IV of the Cardano Blockchain Constitution pertains to the ecosystem budget, which is a crucial component in the governance and economic framework of Cardano. This section outlines the principles and processes related to the allocation and management of funds within the Cardano ecosystem.\n\n## Key Sections and Content\n\n### Section 1: Budget Proposals\n- **Proposal Submission**: Any participant in the Cardano Community is allowed to propose a budget for the ecosystem. This inclusivity ensures that all stakeholders have the opportunity to influence financial decisions.\n- **Community Involvement**: The section emphasizes the role of the community in shaping the budget, reflecting Cardano's commitment to decentralized governance.\n\n### Section 2: Budget Approval\n- **Approval Process**: Details the process by which budget proposals are reviewed and approved. This typically involves a voting mechanism where community members can express their support or opposition.\n- **Transparency and Accountability**: The section likely includes measures to ensure that the budget approval process is transparent and that those responsible for managing funds are held accountable.\n\n### Section 3: Fund Allocation\n- **Allocation Criteria**: Specifies the criteria used to allocate funds to various projects or initiatives within the ecosystem. This ensures that resources are directed towards efforts that align with Cardano's strategic goals.\n- **Prioritization**: May include guidelines on how to prioritize different funding requests based on factors such as impact, feasibility, and alignment with community values.\n\n### Section 4: Monitoring and Reporting\n- **Oversight Mechanisms**: Describes the mechanisms in place to monitor the use of funds and ensure they are used effectively. This could involve regular reporting and audits.\n- **Feedback Loops**: Encourages continuous feedback from the community to improve budget management practices.\n\n### Section 5: Amendments and Revisions\n- **Flexibility**: Allows for amendments to the budget process to adapt to changing needs and circumstances within the Cardano ecosystem.\n- **Community Engagement**: Ensures that any changes to the budget process involve community consultation and consensus.\n\n## Conclusion\nARTICLE IV of the Cardano Blockchain Constitution establishes a comprehensive framework for managing the ecosystem budget, emphasizing transparency, community involvement, and accountability. This framework is designed to ensure that financial resources are allocated efficiently and in a manner that supports the long-term sustainability and growth of the Cardano ecosystem.\n\nFor more detailed information, refer to the specific sections of the draft constitution available at the provided GitHub links.",
"proposal_id": "gov_action1js2s9v92zpxg2rge0y3jt9zy626he2m67x9kx9phw4r942kvsn6sqfym0d7",
"proposal_title": "Decrease Treasury Tax from 20% to 10%",
"proposal_type": "ParameterChange",
"proposal_subtype": "Economic"
},
"meta": {
"query": "ARTICLE IV. THE CARDANO BLOCKCHAIN ECOSYSTEM",
"content_sources": [
{
"url": "https://github.com/IntersectMBO/draft-constitution/blob/main/2024-12-05/draft-constitution-converted.md",
"is_meta_url": false,
"content_type": "markdown"
},
{
"url": "https://github.com/IntersectMBO/draft-constitution/blob/main/2024-12-04/draft-constitution-converted.md",
"is_meta_url": false,
"content_type": "markdown"
}
],
"timings": {
"fetch_proposal_data": 344,
"search_content": 231,
"openai_analysis": 12807,
"total": 13383
}
}
}
```
```json 400 (Bad Request)
{
"error": "Missing or invalid query",
"details": "Please provide a valid query string"
}
```
```json 401 (Unauthorized)
{
"error": "Unauthorized",
"message": "API key is required"
}
```
```json 404 (Not Found)
{
"error": "Proposal not found",
"details": "No proposal found with ID: gov1x8jkz74"
}
```
```json 500 (Internal Server Error)
{
"error": "Failed to process enhanced AI analysis request",
"details": "Internal server error occurred while processing the request"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Success - Analysis generated successfully |
| 400 | Bad Request - Invalid query parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 404 | Not Found - Specified proposal not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
## Notes
**Content Sources**: The API searches through various sources of content related to the proposal, including the proposal itself, technical references, and community discussions. These sources are used to generate a comprehensive analysis.
**Response Time**: Generating AI analysis for complex queries may take several seconds, especially for cross-proposal analysis that requires synthesizing information from multiple sources.
## Proposal Types
The API supports analysis of all governance proposal types in the Cardano ecosystem:
| Type | Description |
|------|-------------|
| InfoAction | Informational or action proposals |
| ParameterChange | Protocol parameter modifications |
| NewConstitution | Constitutional updates |
| TreasuryWithdrawal | Treasury fund allocations |
| HardForkInitiation | Hardfork trigger proposals |
| NoConfidence | No-confidence votes |
| UpdateCommittee | Constitutional committee changes |
================================================
FILE: docs/api-reference/rationale-api.mdx
================================================
---
title: 'Rationale AI'
api: 'POST /api/rationale/ai'
description: 'Get AI analysis of voting rationales for a specific proposal and vote type'
---
**Collective Intelligence**: This endpoint analyzes voting rationales to extract patterns, common themes, and underlying values that influenced governance decisions across different stakeholder groups for specific vote choices.
The Rationale API provides AI-powered analysis of voting rationales across different stakeholder groups in Cardano's governance system, filtered by vote type (Yes/No votes).
## Request Headers
Your API key for authentication
## Request Body
ID of the proposal to analyze rationales for
Type of vote to analyze: "yes" or "no" - only these values are allowed
Stakeholder group to focus on: "all", "drep", "spo", or "cc" (Constitutional Committee)
Custom system prompt to override the default analysis instructions. Use this to customize the analysis style, focus areas, or output format while preserving essential governance context.
## Custom System Prompts
**Flexible Analysis**: Customize the AI analysis style while preserving essential governance context and vote breakdown data.
### Default System Prompt
The API uses this default system prompt when no custom prompt is provided:
```
You are an expert analyst tasked with producing a comprehensive, structured, and easy-to-understand analysis of a community vote or live proposal. Your job is to break down vote data clearly and interpret voter rationales with depth and nuance. You must return all data in Markdown format for readability.
Your response must be well-structured using bullet points, numbered lists, and clear headings. Combine structured formatting with insightful analysis while maintaining conversational, accessible language.
```
### Using Custom System Prompts
Replace the default instructions with your own analysis approach:
```json
{
"govaction_id": "gov_action123...",
"vote_type": "no",
"for": "drep",
"custom_system_prompt": "You are a political scientist specializing in decentralized governance. Focus on institutional dynamics, power structures, and democratic theory. Analyze voting patterns through the lens of public choice theory and collective action problems. Provide academic-level insights with citations to relevant literature where applicable."
}
```
### Best Practices for Custom Prompts
**Specify Expertise**: "You are a [role] specializing in [area]"
**Examples:**
- Political scientist studying blockchain governance
- Financial analyst focusing on treasury management
- Sociologist examining community dynamics
- Legal expert in constitutional compliance
**Specify Perspective**: What lens should the analysis use?
**Examples:**
- Economic impact and financial sustainability
- Technical feasibility and implementation
- Legal compliance and constitutional issues
- Community sentiment and social dynamics
**Format Requirements**: How should results be presented?
**Examples:**
- Academic paper format with citations
- Executive summary for decision makers
- Technical report with recommendations
- Comparative analysis with scoring
**Detail Level**: How comprehensive should the analysis be?
**Examples:**
- High-level strategic overview
- Detailed technical assessment
- Nuanced social dynamics analysis
- Quantitative pattern recognition
### Custom Prompt Examples
```
You are a political scientist specializing in digital democracy and decentralized governance systems. Analyze the voting rationales through the lens of democratic theory, focusing on:
1. Representation quality and delegate responsiveness
2. Information asymmetries and voter competence
3. Coalition formation and factional dynamics
4. Institutional design effects on outcomes
Structure your analysis as an academic paper section with clear theoretical frameworks. Reference relevant concepts from political science literature such as principal-agent theory, median voter theorem, or collective action problems where applicable.
```
```
You are a blockchain treasury analyst with expertise in decentralized finance and risk management. Evaluate the voting rationales from a financial perspective, focusing on:
1. Fiscal responsibility and sustainability concerns
2. Risk assessment and mitigation strategies
3. Economic incentives and market dynamics
4. Treasury management best practices
Provide quantitative insights where possible and structure your analysis as a risk assessment report with clear recommendations for financial governance.
```
```
You are a legal expert specializing in blockchain governance and constitutional law. Analyze the voting rationales for legal and constitutional compliance issues, focusing on:
1. Constitutional adherence and procedural compliance
2. Legal precedent and governance framework integrity
3. Rights protection and due process concerns
4. Regulatory implications and compliance risks
Structure your analysis as a legal memorandum with clear constitutional interpretation and compliance recommendations.
```
```
You are a blockchain developer and systems architect with expertise in governance implementation. Evaluate the voting rationales from a technical feasibility perspective, focusing on:
1. Implementation complexity and technical risks
2. System architecture and scalability concerns
3. Integration challenges and compatibility issues
4. Performance impact and resource requirements
Provide technical depth appropriate for development teams and structure your analysis with clear implementation recommendations.
```
### Tips for Better Analysis
**Context Preservation**: Essential governance data (vote breakdowns, proposal details, rationale lists) are automatically included regardless of your custom prompt.
**Effective Prompting**: Use specific, actionable instructions for better results:
- **Be Specific**: "Focus on economic implications" vs "analyze from financial perspective with emphasis on treasury sustainability, risk management, and long-term fiscal health"
- **Define Structure**: Specify how you want results organized (bullet points, numbered sections, tables, etc.)
- **Set Expectations**: Clarify the depth and style of analysis needed
- **Include Context**: Mention any specific frameworks, theories, or methodologies to apply
### Custom Prompt Guidelines
**Do:**
- Specify your expertise area and perspective
- Define the analysis framework or methodology
- Set clear expectations for output format
- Include specific focus areas or evaluation criteria
- Use domain-specific terminology appropriately
**Don't:**
- Override essential vote data (automatically preserved)
- Request formats incompatible with the governance context
- Use prompts that ignore the provided rationales
- Create prompts that don't match your stakeholder group filter
- Make the prompt overly complex or contradictory
## Response Structure
**Filtered Response**: The API returns only analysis and rationales for requested stakeholder groups. Empty groups are omitted entirely for cleaner responses.
AI-generated structured markdown analysis of rationales by requested stakeholder group(s) only
Structured markdown analysis of DRep rationales (only if "drep" requested or "all" with DRep data)
Structured markdown analysis of SPO rationales (only if "spo" requested or "all" with SPO data)
Structured markdown analysis of Constitutional Committee rationales (only if "cc" requested or "all" with CC data)
ID of the analyzed proposal
Title of the analyzed proposal
Vote type that was analyzed (yes/no)
Complete voting breakdown by stakeholder group (always includes all groups for context)
DRep voting breakdown including detailed No vote breakdown
Majority vote outcome (yes, no, abstain)
Percentage breakdown of votes
Percentage of "yes" votes
Percentage of "no" votes (includes all no categories)
Percentage of "abstain" votes
Count of votes
Number of "yes" votes
Number of "no" votes
Number of "abstain" votes
SPO voting breakdown including detailed No vote breakdown
Majority vote outcome (yes, no, abstain)
Percentage breakdown of votes
Percentage of "yes" votes
Percentage of "no" votes (includes all no categories)
Percentage of "abstain" votes
Count of votes
Number of "yes" votes
Number of "no" votes
Number of "abstain" votes
Constitutional Committee voting breakdown including detailed No vote breakdown
Majority vote outcome (yes, no, abstain)
Percentage breakdown of votes
Percentage of "yes" votes
Percentage of "no" votes (includes all no categories)
Percentage of "abstain" votes
Count of votes
Number of "yes" votes
Number of "no" votes
Number of "abstain" votes
Filter used for stakeholder groups
Vote type that was analyzed
Count of rationales analyzed by group (only includes requested groups with data)
Number of DRep rationales analyzed (only if requested and available)
Number of SPO rationales analyzed (only if requested and available)
Number of CC rationales analyzed (only if requested and available)
Total number of rationales processed across requested groups
Exact token count using GPT tokenizer for processed rationales
Token limits and configuration used
GPT-4o maximum context window (18,000)
Safe input limit used (7,600 tokens)
Tokens reserved for response output (5,000)
Method used: "direct_analysis" or "precise_token_based_summarization"
Whether a custom system prompt was provided for this analysis
Total number of votes processed from database for requested groups
Performance metrics for the request
Time taken to fetch proposal data (ms)
Time taken to fetch votes (ms)
Time taken to extract rationales (ms)
Time taken for AI analysis (ms)
Total request processing time (ms)
Raw rationales from voters (only includes requested groups with data)
Array of DRep rationales (only if "drep" requested or "all" with DRep data)
Voter ID who provided the rationale
The rationale text provided by the voter
Array of SPO rationales (only if "spo" requested or "all" with SPO data)
Voter ID who provided the rationale
The rationale text provided by the voter
Array of CC rationales (only if "cc" requested or "all" with CC data)
Voter ID who provided the rationale
The rationale text provided by the voter
```json 200 (All Stakeholder Groups - "for": "all")
{
"data": {
"analysis": {
"DRep": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 1.62B ADA (active voters who chose \"No\")\n- **Not Voted**: 1.55B ADA (eligible voters who didn't participate)\n...",
"SPO": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 612.37M ADA (active voters who chose \"No\")\n- **Not Voted**: 13.89B ADA (eligible voters who didn't participate)...",
"ConstitutionalCommittee": "## 📊 What the Numbers Tell Us\n- **Explicit No Votes**: N/A ADA (active voters who chose \"No\")\n- **Not Voted**: N/A ADA (eligible voters who didn't p..."
},
"proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
"proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
"vote_type": "no",
"vote_percentages": {
"SPO": {
"counts": { "No": 22, "Yes": 29, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 96.44, "Yes": 3.56 }
},
"DRep": {
"counts": { "No": 111, "Yes": 141, "Abstain": 15 },
"majority": "No",
"percentages": { "No": 65.25, "Yes": 34.75 }
},
"ConstitutionalCommittee": {
"counts": { "No": 4, "Yes": 1, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 83.33, "Yes": 16.67 }
}
}
},
"meta": {
"group_filter": "all",
"vote_type": "no",
"rationale_counts": {
"DRep": 26,
"SPO": 1,
"ConstitutionalCommittee": 4
},
"total_rationales_processed": 31,
"precise_token_count": 6276,
"token_limits": {
"gpt4o_max_context": 18000,
"safe_input_limit": 7600,
"output_token_reserve": 5000
},
"processed_votes_count": 137,
"processing_method": "precise_token_based_summarization",
"custom_prompt_used": false,
"timings": {
"fetch_proposal_data": 247,
"fetch_votes": 132,
"extract_rationales": 12,
"generate_ai_analysis": 38004,
"total": 38396
}
},
"rationales": {
"DRep": [
{
"id": "drep1y23kabcdefg...",
"comment": "I'm voting \"No\" on t..."
}
],
"SPO": [
{
"id": "pool1vc8jhijklmn...",
"comment": "Please provide some ..."
}
],
"ConstitutionalCommittee": [
{
"id": "cc_hot1qvr7p6mlmnopqus...",
"comment": "The published rationale for t..."
}
]
}
}
```
```json 200 (DRep Only - "for": "drep")
{
"data": {
"analysis": {
"DRep": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 1.62B ADA (active voters who chose \"No\")\n- **Not Voted**: 1.55B ADA (eligible voters who didn't participate)\n..."
},
"proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
"proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
"vote_type": "no",
"vote_percentages": {
"SPO": {
"counts": { "No": 22, "Yes": 29, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 96.44, "Yes": 3.56 }
},
"DRep": {
"counts": { "No": 111, "Yes": 141, "Abstain": 15 },
"majority": "No",
"percentages": { "No": 65.25, "Yes": 34.75 }
},
"ConstitutionalCommittee": {
"counts": { "No": 4, "Yes": 1, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 83.33, "Yes": 16.67 }
}
}
},
"meta": {
"group_filter": "drep",
"vote_type": "no",
"rationale_counts": {
"DRep": 26
},
"total_rationales_processed": 26,
"precise_token_count": 5188,
"token_limits": {
"gpt4o_max_context": 18000,
"safe_input_limit": 7600,
"output_token_reserve": 5000
},
"processed_votes_count": 111,
"processing_method": "precise_token_based_summarization",
"timings": {
"fetch_proposal_data": 221,
"fetch_votes": 134,
"extract_rationales": 7,
"generate_ai_analysis": 12674,
"total": 13037
}
},
"rationales": {
"DRep": [
{
"id": "drep1y23kumvpqgal3t6v4tamwrprjya453p3djam0eqg63usm9su77hjl",
"comment": "I'm voting \"No\" on this governance action since there is a newer similar GA (\"2025 Net Change Limit\") which does a better job of explaining what it's meant to achieve, why it's needed, and how the authors arrived at the proposed spending cap."
},
{
"id": "drep1y2rvnp40ea4zsl4hqm0ev4qju205jx7mz57u2vwjzzrf50c24jca9",
"comment": "Not a fan of giant bulk withdrawals from treasury, prefer larger number of smaller withdrawals that would get approved based on their merit by the community governance..."
}
]
}
}
```
```json 200 (SPO Only - "for": "spo")
{
"data": {
"analysis": {
"SPO": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 612.37M ADA (active voters who chose \"No\")\n- **Not Voted**: 13.89B ADA (eligible voters who didn't participate)\n- **Auto No Confide..."
},
"proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
"proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
"vote_type": "no",
"vote_percentages": {
"SPO": {
"counts": { "No": 22, "Yes": 29, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 96.44, "Yes": 3.56 }
},
"DRep": {
"counts": { "No": 111, "Yes": 141, "Abstain": 15 },
"majority": "No",
"percentages": { "No": 65.25, "Yes": 34.75 }
},
"ConstitutionalCommittee": {
"counts": { "No": 4, "Yes": 1, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 83.33, "Yes": 16.67 }
}
}
},
"meta": {
"group_filter": "spo",
"vote_type": "no",
"rationale_counts": {
"SPO": 1
},
"total_rationales_processed": 1,
"precise_token_count": 22,
"token_limits": {
"gpt4o_max_context": 18000,
"safe_input_limit": 7600,
"output_token_reserve": 5000
},
"processed_votes_count": 22,
"processing_method": "direct_analysis",
"timings": {
"fetch_proposal_data": 265,
"fetch_votes": 74,
"extract_rationales": 1,
"generate_ai_analysis": 10104,
"total": 10444
}
},
"rationales": {
"SPO": [
{
"id": "pool1vc8jhqtwjrjwsfk6a0enx47hd2ufg98c34ta6lvl0zv0uhpech9",
"comment": "Please provide some research and math proving that it is necessary, effective, and healthy for the network and users."
}
]
}
}
```
```json 200 (Custom System Prompt Example)
{
"data": {
"analysis": {
"DRep": "## Constitutional Compliance Assessment\n\n**Primary Legal Concerns Identified:**\n\n**Procedural Violations:** Multiple rationales cite concerns about constitutional ..."
},
"proposal_id": "gov_actionabcdefgh...",
"proposal_title": "Set 2025 Net Chan...",
"vote_type": "no",
"vote_percentages": {
"DRep": {
"counts": { "No": 111, "Yes": 141, "Abstain": 15 },
"majority": "No",
"percentages": { "No": 65.25, "Yes": 34.75 }
}
}
},
"meta": {
"group_filter": "drep",
"vote_type": "no",
"rationale_counts": { "DRep": 26 },
"total_rationales_processed": 26,
"processing_method": "direct_analysis",
"custom_prompt_used": true,
"timings": {
"generate_ai_analysis": 14521,
"total": 15892
}
},
"rationales": {
"DRep": [
{
"id": "drep1y23kumabcdeff....",
"comment": "I'm voting \"No\" on this governance act..."
}
]
}
}
```
```json 200 (No Rationales Available - Empty Response)
{
"data": {
"analysis": {},
"proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
"proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
"vote_type": "yes",
"vote_percentages": {
"SPO": {
"counts": { "No": 22, "Yes": 29, "Abstain": 1 },
"majority": "No",
"percentages": { "No": 96.44, "Yes": 3.56 }
}
}
},
"meta": {
"group_filter": "spo",
"vote_type": "yes",
"rationale_counts": {},
"total_rationales_processed": 0,
"precise_token_count": 0,
"processed_votes_count": 29,
"processing_method": "direct_analysis"
},
"rationales": {}
}
```
```json 400 (Missing Vote Type)
{
"error": "Invalid or missing 'vote_type' parameter",
"details": "Only 'yes' or 'no' allowed"
}
```
```json 400 (Invalid Parameters)
{
"error": "Invalid 'for' parameter",
"details": "Must be one of: 'all', 'drep', 'spo', 'cc'"
}
```
```json 404 (Not Found)
{
"error": "Proposal not found",
"details": "No proposal found with ID: gov_action1example123456789"
}
```
## Response Filtering Logic
**Clean Responses**: The API implements intelligent filtering to return only relevant data:
- **Specific Group Requests** (`"drep"`, `"spo"`, `"cc"`): Returns only that group's analysis and rationales
- **All Groups Request** (`"all"`): Returns all groups that have rationales (skips empty groups)
- **Empty Groups**: Omitted entirely from response (no empty arrays or empty analysis)
- **Context Data**: `vote_percentages` always included for full proposal context
## Analysis Output Format
The API returns structured markdown analysis with consistent sections:
- **📊 What the Numbers Tell Us**: Vote breakdown and community sentiment
- **🎯 Main Concerns and Themes**: Top 3-4 identified themes with explanations
- **💡 What Matters Most to These Voters**: Core values and principles
- **🤔 Mixed Feelings or Conditions**: Conditional statements and uncertainties
- **👥 How Their Role Influenced Their Thinking**: Role-specific perspectives
- **🎯 Bottom Line**: Summary of main reasoning
## Processing Methods
**Automatic Optimization**: The API automatically selects the optimal processing method based on rationale volume.
- **Direct Analysis** (≤7,600 tokens): Single comprehensive analysis
- **Token-Based Summarization** (>7,600 tokens): Intelligent chunking with summary synthesis
## Technical Specifications
- **Context Window**: GPT-4o 18,000 tokens
- **Safe Input Limit**: 7,600 tokens (70% of capacity)
- **Token Measurement**: Precise GPT tokenizer counting
- **Processing**: ALL available rationales (complete coverage)
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Success - Analysis generated successfully |
| 400 | Bad Request - Invalid or missing required parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 404 | Not Found - Proposal not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
## Notes
**Required Parameter**: The `vote_type` parameter is mandatory. The API analyzes rationales from voters who chose the specified vote type only.
**Complete Coverage**: The API processes ALL available rationales for the specified parameters, not samples, ensuring comprehensive analysis regardless of dataset size.
**Optimized Responses**: Empty groups are automatically filtered out to provide clean, focused responses without unnecessary empty data structures.
## Advanced Usage Tips
**Maximize Analysis Value**: Combine different analysis approaches and stakeholder perspectives for comprehensive governance insights.
### Multi-Perspective Analysis Strategy
**Comparative Analysis:**
- Run the same query with different custom prompts
- Compare results across stakeholder groups
- Analyze both Yes and No votes for complete picture
- Use different analytical frameworks for deeper insights
**Sequential Analysis:**
1. Start with default analysis for comprehensive overview
2. Apply domain-specific prompts for targeted insights
3. Use legal/compliance perspective for risk assessment
4. Apply technical lens for implementation considerations
### Prompt Optimization Tips
**Iterative Refinement:**
- Start with broad expertise-based prompts
- Refine based on initial results
- Add specific focus areas as needed
- Test different analytical frameworks
**Context Integration:**
- Reference your organizational context
- Include relevant regulatory requirements
- Consider stakeholder communication needs
- Align with existing analytical processes
**Quality Assurance:**
- Compare custom prompt results with default analysis
- Validate insights against known stakeholder positions
- Cross-reference with other governance data sources
- Consider multiple analytical perspectives for important decisions
================================================
FILE: docs/essentials/code.mdx
================================================
---
title: 'Code Blocks'
description: 'Display inline code and code blocks'
icon: 'code'
---
## Basic
### Inline Code
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
### Code Block
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````md
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
================================================
FILE: docs/essentials/images.mdx
================================================
---
title: 'Images and Embeds'
description: 'Add image, video, and other HTML elements'
icon: 'image'
---
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using Embeds
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
```html
```
## Embeds and HTML elements
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
### iFrames
Loads another HTML page within the document. Most commonly used for embedding videos.
```html
```
================================================
FILE: docs/essentials/markdown.mdx
================================================
---
title: 'Markdown Syntax'
description: 'Text, title, and styling in standard markdown'
icon: 'text-size'
---
## Titles
Best used for section headers.
```md
## Titles
```
### Subtitles
Best use to subsection headers.
```md
### Subtitles
```
Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
## Text Formatting
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
| Style | How to write it | Result |
| ------------- | ----------------- | --------------- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | _italic_ |
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
| Text Size | How to write it | Result |
| ----------- | ------------------------ | ---------------------- |
| Superscript | `superscript` | superscript |
| Subscript | `subscript` | subscript |
## Linking to Pages
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
## Blockquotes
### Singleline
To create a blockquote, add a `>` in front of a paragraph.
> Dorothy followed her through many of the beautiful rooms in her castle.
```md
> Dorothy followed her through many of the beautiful rooms in her castle.
```
### Multiline
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```md
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```
### LaTeX
Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
8 x (vk x H1 - H2) = (0,1)
```md
8 x (vk x H1 - H2) = (0,1)
```
================================================
FILE: docs/essentials/navigation.mdx
================================================
---
title: 'Navigation'
description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
icon: 'map'
---
The navigation menu is the list of links on every website.
You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
## Navigation syntax
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
```json Regular Navigation
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
}
]
}
```
```json Nested Navigation
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Nested Reference Pages",
"pages": ["nested-reference-page"]
}
]
}
]
}
]
}
```
## Folders
Simply put your MDX files in folders and update the paths in `docs.json`.
For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
```json Navigation With Folder
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
}
]
}
```
## Hidden Pages
MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
================================================
FILE: docs/essentials/reusable-snippets.mdx
================================================
---
title: Reusable Snippets
description: Reusable, custom snippets to keep content in sync
icon: 'recycle'
---
import SnippetIntro from '/snippets/snippet-intro.mdx';
## Creating a custom snippet
**Pre-condition**: You must create your snippet file in the `snippets` directory.
Any page in the `snippets` directory will be treated as a snippet and will not
be rendered into a standalone page. If you want to create a standalone page
from the snippet, import the snippet into another file and call it as a
component.
### Default export
1. Add content to your snippet file that you want to re-use across multiple
locations. Optionally, you can add variables that can be filled in via props
when you import the snippet.
```mdx snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.
```
The content that you want to reuse must be inside the `snippets` directory in
order for the import to work.
2. Import the snippet into your destination file.
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
### Reusable variables
1. Export a variable from your snippet file:
```mdx snippets/path/to/custom-variables.mdx
export const myName = 'my name';
export const myObject = { fruit: 'strawberries' };
```
2. Import the snippet from your destination file and use the variable:
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.
```
### Reusable components
1. Inside your snippet file, create a component that takes in props by exporting
your component in the form of an arrow function.
```mdx snippets/custom-component.mdx
export const MyComponent = ({ title }) => (
{title}
... snippet content ...
);
```
MDX does not compile inside the body of an arrow function. Stick to HTML
syntax when you can or use a default export if you need to use MDX.
2. Import the snippet into your destination file and pass in the props
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
```
================================================
FILE: docs/essentials/settings.mdx
================================================
---
title: 'Global Settings'
description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file'
icon: 'gear'
---
Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
## Properties
Name of your project. Used for the global title.
Example: `mintlify`
An array of groups with all the pages within that group
The name of the group.
Example: `Settings`
The relative paths to the markdown files that will serve as pages.
Example: `["customization", "page"]`
Path to logo image or object with path to "light" and "dark" mode logo images
Path to the logo in light mode
Path to the logo in dark mode
Where clicking on the logo links you to
Path to the favicon image
Hex color codes for your global theme
The primary color. Used for most often for highlighted content, section
headers, accents, in light mode
The primary color for dark mode. Used for most often for highlighted
content, section headers, accents, in dark mode
The primary color for important buttons
The color of the background in both light and dark mode
The hex color code of the background in light mode
The hex color code of the background in dark mode
Array of `name`s and `url`s of links you want to include in the topbar
The name of the button.
Example: `Contact us`
The url once you click on the button. Example: `https://mintlify.com/docs`
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
If `link`: What the button links to.
If `github`: Link to the repository to load GitHub information from.
Text inside the button. Only required if `type` is a `link`.
Array of version names. Only use this if you want to show different versions
of docs with a dropdown in the navigation bar.
An array of the anchors, includes the `icon`, `color`, and `url`.
The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
Example: `comments`
The name of the anchor label.
Example: `Community`
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
Used if you want to hide an anchor until the correct docs version is selected.
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
Override the default configurations for the top-most anchor.
The name of the top-most anchor
Font Awesome icon.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
An array of navigational tabs.
The name of the tab label.
The start of the URL that marks what pages go in the tab. Generally, this
is the name of the folder you put your pages in.
Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
options that the user can toggle.
The authentication strategy used for all API endpoints.
The name of the authentication parameter used in the API playground.
If method is `basic`, the format should be `[usernameName]:[passwordName]`
The default value that's designed to be a prefix for the authentication input field.
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
Configurations for the API playground
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
Learn more at the [playground guides](/api-playground/demo)
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
This behavior will soon be enabled by default, at which point this field will be deprecated.
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
Examples:
```json Absolute
"openapi": "https://example.com/openapi.json"
```
```json Relative
"openapi": "/openapi.json"
```
```json Multiple
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
An object of social media accounts where the key:property pair represents the social media platform and the account url.
Example:
```json
{
"x": "https://x.com/mintlify",
"website": "https://mintlify.com"
}
```
One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
Example: `x`
The URL to the social platform.
Example: `https://x.com/mintlify`
Configurations to enable feedback buttons
Enables a button to allow users to suggest edits via pull requests
Enables a button to allow users to raise an issue about the documentation
Customize the dark mode toggle.
Set if you always want to show light or dark mode for new users. When not
set, we default to the same mode as the user's operating system.
Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
```json Only Dark Mode
"modeToggle": {
"default": "dark",
"isHidden": true
}
```
```json Only Light Mode
"modeToggle": {
"default": "light",
"isHidden": true
}
```
A background image to be displayed behind every page. See example with
[Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
================================================
FILE: docs/snippets/api-key-notice.mdx
================================================
================================================
FILE: docs/snippets/error-handling.mdx
================================================
================================================
FILE: docs/snippets/response-formats.mdx
================================================
================================================
FILE: docs/snippets/snippet-intro.mdx
================================================
One of the core principles of software development is DRY (Don't Repeat
Yourself). This is a principle that apply to documentation as
well. If you find yourself repeating the same content in multiple places, you
should consider creating a custom snippet to keep your content in sync.
================================================
FILE: docs/user-guide/drep-explorer.mdx
================================================
---
title: "DRep Explorer"
description: "A guide to using the DRep Explorer"
icon: "user-gear"
---
**Natural Language Search**: The DRep Explorer allows you to search for and filter Delegated Representatives using simple English queries.
## What is the DRep Explorer?
The DRep Explorer is an AI-powered tool for finding and analyzing Delegated Representatives (DReps) in the Cardano ecosystem. It allows you to search for DReps based on a wide range of criteria, including their attributes (voting power, delegators, participation rate) and their voting behavior on specific proposals.
## Key Features
Search for DReps using simple English queries
Filter by voting patterns, delegators, and power
View comprehensive DRep information
Analyze past voting behavior
## How to Use the DRep Explorer
Type your search criteria in plain English in the search bar.
**Example Queries:**
- "Find DReps with more than 10 delegators"
- "Show DReps who voted yes on the Cardano NCL proposal"
- "Find active DReps with high voting power"
Use the sorting and filtering options to organize and narrow down your results.
You can sort results by:
- Voting Power
- Number of Delegators
- Participation Rate
- Alignment Score
Click on any DRep in the results to view their detailed profile.
Each profile includes:
- Basic information (name, location, registration date)
- Performance metrics (voting power, delegators, participation)
- Voting history on recent proposals
- Alignment scores with different stakeholder groups
Use the voting history section to analyze a DRep's voting patterns over time.
The voting history shows:
- Votes on recent proposals (yes, no, abstain)
- Alignment with majority decisions
- Proposal types and categories
## Advanced Search Techniques
### Combining Multiple Criteria
You can combine multiple criteria in a single query to find DReps that match specific combinations of attributes and voting behavior.
**Examples:**
- "Find active DReps with more than 50 delegators who voted yes on parameter change proposals"
- "Show DReps from Europe with at least 90% participation rate"
### Using AND/OR Logic
The search system understands both "AND" and "OR" logic in your queries.
- **AND Logic**: "Find DReps who voted on both the NCL proposal and the parameter change proposal"
- **OR Logic**: "Show DReps who voted yes on either the treasury withdrawal or the parameter change proposal"
### Searching by Date Ranges
You can search for DReps based on when they registered or when they voted on specific proposals.
**Examples:**
- "Find DReps who registered in 2023"
- "Show DReps who voted on proposals in the last month"
## Understanding the Results
**AI-Generated Explanations**: Each search result includes an AI-generated explanation that helps you understand what the data means.
The DRep Explorer provides an explanation of your search results, highlighting key insights such as:
- Total number of matching DReps
- Average metrics (voting power, delegators, participation)
- Common patterns in voting behavior
- Distribution of DReps across different categories
## API Integration
For developers who want to integrate the DRep Explorer capabilities into their own applications, the API provides programmatic access to the same functionality.
```bash API Example
curl -X POST https://api.syncgovhub.com/api/drep/ai \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"query": "Find DReps who voted yes on the cardano ncl proposal",
"page": 1,
"limit": 10
}'
```
```javascript JavaScript Example
fetch('https://api.syncgovhub.com/api/drep/ai', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'Find DReps who voted yes on the cardano ncl proposal',
page: 1,
limit: 10
})
})
.then(response => response.json())
.then(data => console.log(data));
```
## Best Practices
- **Be Specific**: The more specific your query, the more relevant your results will be
- **Use Natural Language**: Write queries in plain English rather than trying to use special syntax
- **Explore Progressively**: Start with broader queries and gradually refine them based on results
- **Check Explanations**: Read the AI-generated explanations to understand the context of your results
- **Verify Alignment**: When analyzing voting behavior, consider both the voting power and alignment scores
================================================
FILE: docs/user-guide/proposal-explorer.mdx
================================================
---
title: "Proposal Explorer"
description: "A guide to using the Proposal Explorer"
icon: "file-contract"
---
**AI-Powered Analysis**: The Proposal Explorer features a chat interface that allows you to ask questions about governance proposals and receive detailed AI-generated analysis.
## What is the Proposal Explorer?
The Proposal Explorer is an interactive tool for browsing and analyzing Cardano governance proposals. It features an AI assistant that can answer questions about proposal content, technical details, voting outcomes, and implications.
## Key Features
Browse proposals by type, status, and date
Ask questions about proposals in natural language
Find proposals based on content and context
View detailed voting breakdowns
## How to Use the Proposal Explorer
Use the proposal list to browse and select a specific governance proposal.
You can filter proposals by:
- Proposal type (Parameter Change, Treasury Withdrawal, etc.)
- Status (Active, Ratified, Enacted, etc.)
- Date range
Once you select a proposal, you can view its details including the proposal text, metadata, and voting results.
The details page includes:
- Proposal title and description
- Proposer information
- Status and lifecycle dates
- Technical details (for parameter changes)
- Voting results by stakeholder group
Use the chat interface to ask questions about the proposal and receive AI-generated analysis.
**Example Questions:**
- "What are the main objectives of this proposal?"
- "How does this parameter change affect staking rewards?"
- "What were the arguments for and against this proposal?"
- "What impact will this have on the Cardano ecosystem?"
Analyze the voting patterns and outcomes for the proposal across different stakeholder groups.
The voting analytics show:
- Vote distribution (yes, no, abstain) for each stakeholder group
- Participation rates
- Voting power distribution
- Threshold achievements
## AI Assistant Capabilities
**Comprehensive Understanding**: The AI assistant analyzes the full proposal content, related documents, and voting data to provide detailed insights.
The AI assistant can answer questions about:
### Content Analysis
- Explain proposal objectives and rationale
- Analyze technical details of parameter changes
- Summarize key points and implications
- Compare different sections of a proposal
### Contextual Information
- Explain a proposal's relationship to the Cardano ecosystem
- Provide background on proposal types and purposes
- Analyze historical context for proposals
### Vote Analysis
- Explain vote outcomes and distribution
- Analyze stakeholder participation and consensus
- Explore implications of voting results
## Cross-Proposal Analysis
You can also use the AI assistant to analyze patterns across multiple proposals. Simply start a new chat without selecting a specific proposal.
**Example Cross-Proposal Questions:**
- "What are common patterns in parameter change proposals?"
- "How have treasury withdrawal proposals evolved over time?"
- "What factors contribute to proposal success or failure?"
- "What are the voting trends for governance proposals in the last six months?"
## API Integration
For developers who want to integrate the Proposal Explorer capabilities into their own applications, the API provides programmatic access to the same functionality.
```bash API Example
curl -X POST https://api.syncgovhub.com/api/proposal/ai \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"query": "What are the main objectives and implications of this parameter change?",
"govaction_id": "gov1x8jkz74"
}'
```
```javascript JavaScript Example
fetch('https://api.syncgovhub.com/api/proposal/ai', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'What are the main objectives and implications of this parameter change?',
govaction_id: 'gov1x8jkz74'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
## Best Practices
- **Ask Focused Questions**: Specific questions yield more detailed and accurate responses
- **Explore Key Aspects**: Ask about objectives, technical details, implications, and voting outcomes
- **Use Follow-up Questions**: Build on previous answers to explore topics in greater depth
- **Verify Information**: Use the source references to verify information in the original documents
- **Compare Proposals**: Use cross-proposal analysis to identify patterns and trends
================================================
FILE: docs/user-guide/rationale-explorer.mdx
================================================
---
title: "Rationale Explorer"
description: "A comprehensive guide to using the Rationale Explorer for governance analysis"
icon: "magnifying-glass-chart"
---
**Deep Governance Insights**: The Rationale Explorer provides comprehensive analysis of voter reasoning by examining ALL available rationales for specific vote choices, delivering clean, focused results that only include relevant stakeholder groups with data.
## What is the Rationale Explorer?
The Rationale Explorer is an advanced AI-powered tool that analyzes the reasoning provided by different stakeholder groups when casting votes on governance proposals. It processes ALL available rationales for specific vote types (Yes or No) to extract comprehensive themes, reasoning patterns, and underlying values, providing unprecedented depth in understanding governance decisions with optimized, clean response structures.
## Key Features
Analyze reasoning for Yes or No votes separately for focused insights
Process ALL available rationales, not just samples
Only returns data for requested groups with available rationales
Automatic optimization for datasets from 10 to 10,000+ rationales
## Enhanced Response Structure
**Optimized Output**: The system now provides clean, filtered responses that only include analysis and rationales for stakeholder groups that have data, eliminating empty arrays and unnecessary fields.
### Response Filtering Logic
**For Specific Group Requests** (`"drep"`, `"spo"`, `"cc"`):
- Returns analysis only for the requested group
- Includes rationales only for the requested group
- Omits other groups entirely from analysis and rationales sections
- Always includes full `vote_percentages` for context
**For All Groups Request** (`"all"`):
- Returns analysis for all groups that have rationales
- Skips groups with no available rationales
- Provides comprehensive cross-group comparison
- Includes rationales from all groups with data
**Empty Data Handling**:
- Groups without rationales are completely omitted
- No empty arrays or placeholder analysis
- Clean, focused responses without clutter
## Comprehensive Analysis Structure
**Consistent Framework**: Every analysis follows a structured 6-section format ensuring thorough coverage of all important aspects.
### 📊 What the Numbers Tell Us
- **Vote Breakdown**: Precise ADA amounts and percentages
- **Vote Categories**: Clear distinction between explicit votes, non-participation, and automatic votes
- **Community Sentiment**: What the voting pattern reveals about overall sentiment
### 🎯 Main Concerns and Themes
- **Top Themes**: 3-4 most significant concerns or motivations
- **Detailed Context**: Why each theme matters to voters
- **Evidence Base**: How themes manifest across rationales
### 💡 What Matters Most to These Voters
- **Core Values**: Primary principles driving decisions
- **Value Hierarchy**: How values are prioritized
- **Decision Impact**: How values translate to vote choices
### 🤔 Mixed Feelings or Conditions
- **Conditional Support**: "If this, then that" statements
- **Uncertainties**: Areas of doubt or ambivalence
- **Flexibility**: Potential for changing positions
### 👥 How Their Role Influenced Their Thinking
- **Role Responsibilities**: What their position requires
- **Unique Perspectives**: How their role shapes viewpoints
- **Decision Priorities**: Role-specific evaluation criteria
### 🎯 Bottom Line
- **Core Summary**: Main reason for their vote choice
- **Collective Reasoning**: Essence of the group's decision-making
## How to Use the Enhanced Rationale Explorer
Choose a governance proposal from the list to analyze voting rationales.
The interface shows:
- Proposal title and ID
- Proposal type and voting status
- Available rationale counts by vote type and group
- Estimated analysis scope and processing method
Select which vote type to analyze for focused insights.
**Vote Type Options:**
- **Yes Votes**: Analyze reasoning behind support
- **No Votes**: Understand objections and concerns
**Why Vote Type Matters**: Analyzing specific vote types provides clearer insights than mixing opposing viewpoints together.
Choose which stakeholder group(s) to analyze for targeted insights.
**Stakeholder Groups:**
- **DReps**: Delegated Representatives elected by ADA holders
- **SPOs**: Stake Pool Operators running network infrastructure
- **CC**: Constitutional Committee members overseeing constitutional adherence
- **All**: Compare reasoning across groups with available data
**Smart Filtering**: The system automatically shows only groups that have rationales for your selected vote type, preventing empty results.
Examine the AI-generated structured analysis for your selected parameters.
**Analysis Features:**
- Clean responses with only relevant groups
- Complete coverage of available rationales
- Structured 6-section format for consistency
- Vote breakdown with precise numbers
- Thematic analysis with detailed context
Use the "All Groups" option to understand how different stakeholder groups approach the same proposal.
**Comparison Benefits:**
- Identify different reasoning patterns
- Understand varying priorities and concerns
- Discover role-specific perspectives
- Find areas of consensus and disagreement
## Processing Intelligence
**Adaptive Processing**: The system automatically optimizes analysis based on the volume of rationales, ensuring comprehensive coverage regardless of dataset size with clean, filtered outputs.
### Direct Analysis (Small to Medium Datasets)
- **When**: ≤7,600 tokens (~800-1,200 rationales)
- **Method**: Single comprehensive analysis using GPT-4o
- **Benefit**: Complete processing in one pass
- **Speed**: Fast processing for immediate results
- **Output**: Clean, focused analysis for requested groups only
### Token-Based Summarization (Large Datasets)
- **When**: >7,600 tokens (~1,200+ rationales)
- **Method**: Intelligent chunking → Summarization → Comprehensive analysis
- **Benefit**: Handles unlimited dataset sizes
- **Quality**: Same analysis depth as direct method
- **Output**: Filtered results with same quality as direct analysis
## Understanding Filtered Response Examples
**Response Optimization**: Examples show how responses adapt based on the `for` parameter and available data.
### DRep-Only Request (`"for": "drep"`)
```json
{
"data": {
"analysis": {
"DRep": "Complete analysis for DRep rationales only"
},
// Full vote_percentages for context
"vote_percentages": { /* All groups for context */ }
},
"meta": {
"group_filter": "drep",
"rationale_counts": {
"DRep": 26 // Only DRep count
}
},
"rationales": {
"DRep": [/* DRep rationales only */]
}
}
```
### All Groups Request with Mixed Data (`"for": "all"`)
```json
{
"data": {
"analysis": {
"DRep": "DRep analysis (has rationales)",
"ConstitutionalCommittee": "CC analysis (has rationales)"
// SPO omitted - no rationales available
},
"vote_percentages": { /* All groups for context */ }
},
"meta": {
"rationale_counts": {
"DRep": 26,
"ConstitutionalCommittee": 4
// SPO omitted - no rationales
}
},
"rationales": {
"DRep": [/* DRep rationales */],
"ConstitutionalCommittee": [/* CC rationales */]
// SPO omitted - no rationales available
}
}
```
### Empty Results (No Rationales Available)
```json
{
"data": {
"analysis": {}, // Empty object, no analysis
"vote_percentages": { /* Context still provided */ }
},
"meta": {
"rationale_counts": {}, // Empty object
"total_rationales_processed": 0
},
"rationales": {} // Empty object
}
```
## Advanced Customization with System Prompts
**Expert-Level Customization**: Transform the analysis perspective to match your domain expertise while preserving essential governance data and vote breakdowns.
### When to Use Custom Prompts
**Academic Research:**
- Applying specific theoretical frameworks
- Following disciplinary conventions and terminology
- Focusing on particular research questions
- Meeting publication or citation requirements
**Professional Analysis:**
- Executive summaries for decision makers
- Risk assessments for financial stakeholders
- Legal compliance reviews for governance teams
- Technical feasibility studies for development teams
**Specialized Perspectives:**
- Industry-specific analysis requirements
- Regional or cultural context considerations
- Comparative analysis with other governance systems
- Integration with existing organizational frameworks
### Effective Custom Prompt Strategies
**Define Expertise:**
- Specify your professional background
- Include relevant experience areas
- Set appropriate analytical depth
- Use domain-specific language
**Example:** "You are a political economist with 15 years experience in public choice theory and institutional analysis..."
**Apply Methodologies:**
- Reference specific analytical frameworks
- Include evaluation criteria
- Set measurement standards
- Define success metrics
**Example:** "Apply stakeholder theory and power-interest grid analysis to evaluate..."
**Format Specifications:**
- Define section requirements
- Set presentation style
- Include specific deliverables
- Specify audience considerations
**Example:** "Structure as executive brief with risk matrix, recommendations table, and action items..."
**Domain Integration:**
- Include organizational context
- Reference existing systems
- Consider stakeholder needs
- Align with strategic objectives
**Example:** "Consider impact on institutional investor requirements and regulatory compliance..."
### Custom Prompt Examples by Use Case
```javascript
{
"govaction_id": "gov_action123...",
"vote_type": "no",
"for": "drep",
"custom_system_prompt": "You are a political scientist conducting research on decentralized governance systems. Apply democratic theory and institutional analysis to examine the voting rationales. Focus on: (1) Principal-agent relationships between voters and representatives, (2) Information asymmetries and their impact on decision quality, (3) Coalition formation patterns and factional dynamics, (4) Institutional design effects on governance outcomes. Structure your analysis using academic conventions with clear theoretical framework, empirical observations, and implications for democratic theory."
}
```
```javascript
{
"govaction_id": "gov_action123...",
"vote_type": "no",
"for": "all",
"custom_system_prompt": "You are a chief risk officer preparing an executive briefing on governance decision risks. Focus on financial sustainability, treasury management, and fiduciary responsibility concerns. Structure as: Executive Summary (2-3 key points), Risk Assessment (high/medium/low categories), Financial Impact Analysis (quantitative where possible), Mitigation Recommendations (actionable items), and Strategic Implications (long-term considerations). Use clear, concise language appropriate for C-level stakeholders."
}
```
```javascript
{
"govaction_id": "gov_action123...",
"vote_type": "no",
"for": "cc",
"custom_system_prompt": "You are a governance attorney specializing in decentralized autonomous organizations and constitutional law. Examine the rationales for legal compliance issues, constitutional adherence, and procedural concerns. Structure as legal memorandum: Issue Statement, Legal Analysis (constitutional interpretation, precedent review, compliance assessment), Risk Evaluation (legal exposure, regulatory concerns), and Recommendations (corrective actions, compliance measures). Use appropriate legal terminology and cite relevant governance framework sections."
}
```
```javascript
{
"govaction_id": "gov_action123...",
"vote_type": "yes",
"for": "spo",
"custom_system_prompt": "You are a blockchain systems architect evaluating governance proposals for technical feasibility and implementation complexity. Analyze rationales for technical concerns, infrastructure requirements, and operational impacts. Focus on: System Architecture implications, Scalability considerations, Integration challenges, Performance impacts, Resource requirements, Implementation timeline risks. Structure as technical assessment with clear recommendations for development teams, including priority levels and resource allocation suggestions."
}
```
### Best Practices for Custom Prompts
**Effective Prompt Design:**
✅ **Be Specific**: Rather than "analyze from business perspective," use "evaluate as CFO focusing on treasury sustainability, cash flow impacts, and fiduciary responsibilities"
✅ **Define Scope**: Clearly state what aspects to emphasize and what to minimize
✅ **Set Context**: Include relevant background about your organization, industry, or research focus
✅ **Specify Format**: Detail how you want results structured and presented
✅ **Include Constraints**: Mention any limitations, requirements, or compliance needs
**Common Pitfalls to Avoid:**
❌ **Too Generic**: Vague instructions produce generic results
❌ **Conflicting Instructions**: Contradictory requirements confuse the analysis
❌ **Overly Complex**: Extremely long prompts can dilute focus
❌ **Inappropriate Scope**: Requesting analysis beyond the available data
❌ **Format Mismatch**: Requesting formats incompatible with governance context
### Integration Tips
**Research Projects:**
- Align custom prompts with your research methodology
- Include specific theoretical frameworks or models
- Reference relevant literature or precedents
- Consider peer review and publication requirements
**Business Applications:**
- Match organizational reporting standards
- Include stakeholder communication preferences
- Consider regulatory or compliance requirements
- Align with strategic planning processes
**Policy Development:**
- Focus on implementation feasibility
- Include stakeholder impact considerations
- Consider public communication needs
- Align with existing policy frameworks
## Understanding Vote Breakdown Analysis
**Detailed Breakdown**: For "No" votes, the analysis includes detailed breakdown of different no-vote categories to provide complete context.
### Yes Vote Analysis
Shows straightforward breakdown:
- Total Yes votes in ADA and percentage
- Number of active Yes voters
- Community support indicators
### No Vote Analysis
Provides comprehensive breakdown:
- **Explicit No Votes**: Active voters who chose "No"
- **Not Voted**: Eligible voters who didn't participate
- **Auto No Confidence**: Automatic system votes
- **Combined Effect**: Total "No" impact on proposal
**Analysis Focus**: Rationales come only from explicit "No" voters (active participants), not from non-voters or automatic votes.
## Advanced Research Applications
The enhanced Rationale Explorer enables sophisticated governance research with clean, focused data:
### Academic Research
- **Decision Science**: Study decentralized decision-making processes with precise stakeholder segmentation
- **Political Science**: Analyze direct democracy in digital contexts using filtered group comparisons
- **Economics**: Research public choice theory in blockchain governance with role-specific insights
- **Sociology**: Examine community formation and consensus-building across different stakeholder types
### Governance Analysis
- **Pattern Recognition**: Identify successful governance strategies by stakeholder group
- **Stakeholder Analysis**: Understand group dynamics and priorities with clean data separation
- **Policy Impact**: Assess how proposals affect different constituencies using targeted analysis
- **Value Alignment**: Study alignment between governance and community values by role
### Proposal Development
- **Opposition Research**: Understand specific objections by stakeholder group to improve proposals
- **Support Analysis**: Identify factors that drive approval across different voter types
- **Stakeholder Mapping**: Understand how different groups evaluate proposals using focused analysis
- **Strategic Planning**: Develop proposals that address group-specific concerns
## API Integration for Developers
```bash Enhanced API Example
curl -X POST https://api.syncgovhub.com/api/rationale/ai \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"govaction_id": "gov_action1u9x73kwufaxa70lfy59g4ynwyrcsaxdcd0gxzzmh67s9fxq4j8hqqk2phgh",
"vote_type": "no",
"for": "drep"
}'
```
```javascript JavaScript Example - Focused Analysis
const analyzeRationales = async (proposalId, voteType, stakeholderGroup) => {
try {
const response = await fetch('https://api.syncgovhub.com/api/rationale/ai', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
govaction_id: proposalId,
vote_type: voteType, // "yes" or "no"
for: stakeholderGroup // "all", "drep", "spo", "cc"
})
});
const data = await response.json();
// Access filtered analysis (only requested groups)
console.log('Analysis:', data.data.analysis);
console.log('Available Groups:', Object.keys(data.data.analysis));
console.log('Processing Method:', data.meta.processing_method);
console.log('Total Rationales:', data.meta.total_rationales_processed);
// Check if any rationales were found
if (Object.keys(data.rationales).length === 0) {
console.log('No rationales available for the requested parameters');
}
return data;
} catch (error) {
console.error('Analysis failed:', error);
}
};
// Analyze DRep opposition to a proposal
const drepAnalysis = await analyzeRationales(
'gov_action1u9x73kwufaxa70lfy59g4ynwyrcsaxdcd0gxzzmh67s9fxq4j8hqqk2phgh',
'no',
'drep'
);
// Compare all groups with rationales
const allGroupsAnalysis = await analyzeRationales(
'gov_action1u9x73kwufaxa70lfy59g4ynwyrcsaxdcd0gxzzmh67s9fxq4j8hqqk2phgh',
'no',
'all'
);
```
```python Python Example - Batch Analysis
import requests
import json
class RationaleAnalyzer:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = "https://api.syncgovhub.com/api/rationale/ai"
def analyze_rationales(self, proposal_id, vote_type, stakeholder_group):
"""Get filtered rationale analysis for specific parameters"""
payload = {
"govaction_id": proposal_id,
"vote_type": vote_type,
"for": stakeholder_group
}
headers = {
"Content-Type": "application/json",
"x-api-key": self.api_key
}
response = requests.post(self.base_url, json=payload, headers=headers)
return response.json()
def compare_stakeholder_groups(self, proposal_id, vote_type):
"""Compare analysis across all stakeholder groups with data"""
all_groups = self.analyze_rationales(proposal_id, vote_type, "all")
if not all_groups.get("data", {}).get("analysis"):
return {"message": "No rationales available for analysis"}
# Get available groups (automatically filtered)
available_groups = list(all_groups["data"]["analysis"].keys())
comparison = {
"proposal_id": proposal_id,
"vote_type": vote_type,
"available_groups": available_groups,
"rationale_counts": all_groups["meta"]["rationale_counts"],
"analysis_by_group": all_groups["data"]["analysis"]
}
return comparison
# Usage example
analyzer = RationaleAnalyzer("YOUR_API_KEY")
# Get focused DRep analysis
drep_analysis = analyzer.analyze_rationales(
"gov_action1u9x73kwufaxa70lfy59g4ynwyrcsaxdcd0gxzzmh67s9fxq4j8hqqk2phgh",
"no",
"drep"
)
# Compare all groups (only returns groups with data)
comparison = analyzer.compare_stakeholder_groups(
"gov_action1u9x73kwufaxa70lfy59g4ynwyrcsaxdcd0gxzzmh67s9fxq4j8hqqk2phgh",
"no"
)
```
## Stakeholder Group Comparison
**Focus Areas:**
- Community representation
- Long-term ecosystem health
- Strategic governance
- Fiscal responsibility
**Typical Concerns:**
- Treasury sustainability
- Proposal bundling
- Transparency requirements
- Constitutional alignment
**Analysis Benefits:**
- Comprehensive community perspectives
- Strategic long-term thinking
- Representative viewpoints
**Focus Areas:**
- Network infrastructure
- Operational impacts
- Technical feasibility
- Economic sustainability
**Typical Concerns:**
- Network performance
- Resource allocation
- Implementation complexity
- Operator compensation
**Analysis Benefits:**
- Technical implementation insights
- Operational feasibility assessment
- Infrastructure impact evaluation
**Focus Areas:**
- Constitutional compliance
- Legal framework
- Procedural adherence
- Governance integrity
**Typical Concerns:**
- Constitutional violations
- Precedent setting
- Legal implications
- Process compliance
**Analysis Benefits:**
- Legal compliance insights
- Constitutional interpretation
- Governance process evaluation
## Best Practices for Focused Analysis
### For Researchers
- **Targeted Analysis**: Use specific group filters to focus on relevant stakeholder perspectives
- **Clean Comparisons**: Leverage filtered responses to avoid empty data in comparative studies
- **Temporal Tracking**: Monitor how reasoning patterns evolve by group over time
- **Quantitative Integration**: Combine with vote distribution data for comprehensive insights
### For Proposal Authors
- **Group-Specific Research**: Analyze opposition by stakeholder group to understand specific concerns
- **Targeted Improvements**: Address group-specific objections in proposal revisions
- **Support Mapping**: Understand what drives support across different voter types
- **Strategic Positioning**: Position proposals to address identified group priorities
### For Governance Participants
- **Informed Decisions**: Understand stakeholder reasoning before voting
- **Strategic Alignment**: Align with demonstrated community values by group
- **Consensus Building**: Identify common ground across stakeholder groups
- **Quality Assessment**: Evaluate proposals against group-specific priorities
## Data Quality and Coverage
**Optimized Coverage**: The system processes every available rationale for specified parameters and returns clean, filtered results without empty data structures.
### Coverage Metrics
- **Filtered Results**: Only groups with rationales are included in responses
- **Complete Processing**: All available rationales processed (not sampled)
- **Token Accuracy**: Precise measurement using GPT-4o tokenizer
- **Processing Transparency**: Clear indication of direct vs. summarized analysis methods
- **Quality Assurance**: Consistent structured output regardless of dataset size
### Response Optimization
- **Smart Filtering**: Automatic removal of empty groups and unused fields
- **Focused Analysis**: Only requested stakeholder groups with data included
- **Context Preservation**: Full vote percentages always included for broader context
- **Clean Structure**: No empty arrays or placeholder content
### Limitations and Considerations
- **Data Dependency**: Analysis quality depends on voter participation in providing rationales
- **Vote Specificity**: Analysis focuses only on the specified vote type and stakeholder groups
- **Language Processing**: Optimized for English-language rationales
- **Context Awareness**: Analysis considers governance context and terminology (e.g., NCL = Network Change Limit)
## Integration with Other Tools
The enhanced Rationale Explorer works seamlessly with other governance analysis tools:
- **Proposal Explorer**: Combine with proposal details for complete context
- **Vote Distribution Analysis**: Integrate with voting pattern analysis using consistent filtering
- **Timeline Analysis**: Track reasoning evolution across proposal lifecycle by group
- **Stakeholder Profiles**: Build comprehensive stakeholder understanding with focused data
## Performance and Efficiency
**Optimized Performance**: Filtered responses reduce bandwidth usage and improve processing speed by eliminating unnecessary data transfer.
### Response Efficiency
- **Reduced Payload**: Only relevant data included in responses
- **Faster Processing**: Less data manipulation required on client side
- **Cleaner Integration**: Simplified data structures for easier application integration
- **Bandwidth Optimization**: Smaller response sizes for better performance
### Processing Intelligence
- **Automatic Optimization**: System selects optimal processing method based on data volume
- **Scalable Architecture**: Handles datasets from single rationales to thousands
- **Quality Consistency**: Same analysis depth regardless of processing method
- **Resource Efficiency**: Intelligent token management for cost-effective operation
This enhanced Rationale Explorer provides unprecedented insight into the collective intelligence behind Cardano's governance decisions with clean, focused data structures that enable better understanding, participation, and outcomes in decentralized governance.
## Advanced Usage Strategies
**Maximize Governance Insights**: Combine multiple analysis approaches, stakeholder perspectives, and custom prompts for comprehensive understanding of governance dynamics.
### Multi-Dimensional Analysis Approach
**Cross-Stakeholder Comparison:**
- Analyze same proposal across all stakeholder groups
- Compare reasoning patterns between DReps, SPOs, and Constitutional Committee
- Identify consensus areas and points of divergence
- Understand role-specific priorities and concerns
**Vote Type Analysis:**
- Examine both Yes and No rationales for complete picture
- Understand what drives support vs. opposition
- Identify conditional support and compromise opportunities
- Map voter sentiment evolution over time
**Custom Perspective Integration:**
- Apply multiple expert lenses to same dataset
- Compare default analysis with domain-specific perspectives
- Use specialized prompts for stakeholder-specific insights
- Validate findings across different analytical frameworks
### Strategic Research Workflows
**For Academic Research:**
1. Start with default analysis for comprehensive overview
2. Apply theoretical framework-specific prompts
3. Compare results across stakeholder groups
4. Validate findings with quantitative vote data
5. Integrate with broader governance literature
**For Business Decision Making:**
1. Use financial risk perspective for treasury implications
2. Apply legal compliance lens for regulatory concerns
3. Examine technical feasibility for implementation planning
4. Synthesize insights for executive recommendations
**For Policy Development:**
1. Analyze opposition rationales to understand concerns
2. Identify common themes across stakeholder groups
3. Use legal perspective for constitutional compliance
4. Apply custom prompts for specific policy domains
### Quality Assurance Best Practices
**Validation Techniques:**
- Cross-reference insights with quantitative voting data
- Compare custom prompt results with default analysis
- Validate findings against known stakeholder positions
- Use multiple analytical perspectives for important decisions
**Bias Mitigation:**
- Apply diverse analytical frameworks to same data
- Compare results across different stakeholder groups
- Use both broad and focused analytical approaches
- Consider temporal factors and proposal context
**Insight Integration:**
- Combine rationale analysis with vote distribution data
- Reference proposal details and governance context
- Consider broader ecosystem and market factors
- Integrate with other governance analysis tools
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using Embeds
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
```html
```
## Embeds and HTML elements