swagger.yaml

openapi: 3.0.0

info:
  title: Namada Undexer REST API
  version: 4.0.0
  description: "API for accessing Namada blockchain data via Undexer."
  contact: 
    email: hello@hack.bg
    url: "https://github.com/hackbg/undexer"

servers:
  - url: "https://undexer.hack.bg/v4/"

paths:

  /:
    get:
      summary: Get blockchain status information
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/Overview'}}}}

  /status:
    get:
      summary: Get current status of the blockchain
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/Status'}}}}

  /search:
    get:
      summary: Search by string
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/SearchResults'}}}}

  /blocks:
    get:
      summary: Get blocks with optional pagination
      parameters:
        - {name: limit,  in: query, required: false, schema: {type: integer, minimum: 1, maximum: 100}, description: "Number of blocks to return per page (default 25)" }
        - {name: before, in: query, required: false, schema: {type: string}, description: "Retrieve blocks before the specified block ID (default 0)" }
        - {name: after,  in: query, required: false, schema: {type: string}, description: "Retrieve blocks after the specified block ID (default 0)" }
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/BlocksList'}}}}

  /block:
    get:
      summary: Get block information by height and/or hash
      parameters:
        - {name: height, in: query, required: false, schema: {type: integer}, description: "The height of the block" }
        - {name: hash,   in: query, required: false, schema: {type: string},  description: "The hash of the block"}
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/BlockDetails'}}}}
        '404': {description: "Block not found"}

  /txs:
    get:
      summary: Get paginated list of transactions
      parameters:
        - {name: limit,  in: query, required: false, schema: {type: integer}, description: "Number of transactions to return" }
        - {name: offset, in: query, required: false, schema: {type: integer}, description: "Offset for pagination" }
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/TransactionsList'}}}}

  /tx/{hash}:
    get:
      summary: Retrieve transaction details by transaction hash
      parameters:
        - name: hash
          in: path
          required: true
          schema: {type: string}
          description: Transaction hash identifier
      responses:
        '404': {description: "Not found"}
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/TransactionDetail'}}}}

  /validators/states:
    get:
      summary: Retrieve validator states
      description: Returns the current consensus and jailed states of validators.
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ValidatorsStates'}}}}

  /validators:
    get:
      summary: Get paginated list of validators, optionally filtered by state
      parameters:
        - {name: state,  in: query, required: true,  schema: {type: string, enum: [BelowThreshold, BelowCapacity, Jailed, Consensus, Inactive]}, description: "State of the validators"}
        - {name: limit,  in: query, required: false, schema: {type: integer}, description: "Number of validators to return"}
        - {name: offset, in: query, required: false, schema: {type: integer}, description: "Offset for pagination"}
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ValidatorsList'}}}}

  /validator:
    get:
      summary: Get validator by public key
      parameters:
        - {name: publicKey, in: query, required: true,  schema: {type: string}, description: "The hash of the validator" }
        - {name: uptime,    in: query, required: false, schema: {type: number}, description: "Count uptime over past X blocks" }
      responses:
        '404': {description: "Not found"}
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ValidatorDetails'}}}}

  /proposals:
    get:
      summary: Get paginated list of proposals
      parameters:
        - {name: limit,          in: query, required: false, schema: {type: integer}, description: "Number of proposals to return"}
        - {name: offset,         in: query, required: false, schema: {type: integer}, description: "Offset for pagination"}
        - {name: orderBy,        in: query, required: false, schema: {type: string, enum: [id, status, result, proposalType]}, description: "Field to order by"}
        - {name: orderDirection, in: query, required: false, schema: {type: string, enum: [ASC, DESC]}, description: "Direction to order by"}
        - {name: proposalType,   in: query, required: false, schema: {type: string, enum: [pgf_steward, pgf_payment, default]}, description: "Type of proposals to return"}
        - {name: status,         in: query, required: false, schema: {type: string, enum: [upcoming, ongoing, finished]}, description: "Status of proposals to return"}
        - {name: result,         in: query, required: false, schema: {type: string, enum: [passed, rejected]}, description: "Result of proposals to return"}
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ProposalsList'}}}}

  /proposals/stats:
    get:
      summary: Get count of proposals by status, result and total count
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ProposalsStats'}}}}

  /proposal/{id}:
    get:
      summary: Get governance proposal information by id
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}, description: "The id of the proposal"}
      responses:
        '404': {description: "Not found"}
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/ProposalDetail'}}}}

  /proposal/votes/{proposalId}:
    get:
      summary: Get all votes by proposal id
      parameters:
        - {name: proposalId, in: path, required: true, schema: {type: string}, description: "The id of the proposal" }
      responses:
        '404': {description: "Not found"}
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/VotesPage'}}}}

  /transfers:
    get:
      summary: Get transfers from address
      parameters:
        - {name: from, in: query, schema: {type: string}, description: "Sender"}
        - {name: to,   in: query, schema: {type: string}, description: "Receiver"}
        - {name: by,   in: query, schema: {type: string}, description: "Sender or receiver"}
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/TransferList'}}}}

  /epoch:
    get:
      summary: Get current epoch information
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/EpochInfo'}}}}

  /total-staked:
    get:
      summary: Get total staked amount
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/TotalStaked'}}}}

  /parameters/staking:
    get:
      summary: Get staking parameters
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/PoSParams'}}}}

  /parameters/governance:
    get:
      summary: Get governance parameters
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/GovParams'}}}}

  /parameters/pgf:
    get:
      summary: Get PGF parameters
      responses:
        '200': {content:{application/json:{schema:{$ref:'#/components/schemas/PGFParams'}}}}

components:
  schemas:

    Status:
      type:                object
      properties:
        timestamp:         {type: string, format: date-time}
        totalBlocks:       {type: integer}
        oldestBlock:       {type: integer}
        latestBlock:       {type: integer}
        totalTransactions: {type: integer}
        totalValidators:   {type: integer}
        totalProposals:    {type: integer}
        totalVotes:        {type: integer}

    Overview:
      type:                                    object
      properties:
        timestamp:                             {type: string, format: date-time}
        totalBlocks:                           {type: integer}
        oldestBlock:                           {type: integer}
        latestBlock:                           {type: integer}
        latestBlocks:
          type:                                array
          items:
            type:                              object
            properties:
              blockHeight:                     {type: integer}
              blockHash:                       {type: string}
              blockTime:                       {type: string, format: date-time}
        totalTransactions:                     {type: integer}
        latestTransactions:
          type:                                array
          items:
            type:                              object
            properties:
              blockHeight:                     {type: integer}
              blockHash:                       {type: string}
              blockTime:                       {type: string, format: date-time}
              txHash:                          {type: string}
              txTime:                          {type: string, format: date-time}
              txContentType:                   {type: string}
        totalValidators:                       {type: integer}
        topValidators:
          type:                                array
          items:
            type:                              object
            properties:
              address:                         {type: string}
              publicKey:                       {type: string}
              votingPower:                     {type: integer, nullable: true}
              proposerPriority:                {type: integer, nullable: true}
              namadaAddress:                   {type: string}
              metadata:
                type:                          object
                properties:
                  email:                       {type: string}
                  avatar:                      {type: string, nullable: true}
                  website:                     {type: string, nullable: true}
                  description:                 {type: string, nullable: true}
                  discordHandle:               {type: string, nullable: true}
              commission:
                type:                          object
                properties:
                  epoch:                       {type: string}
                  commissionRate:              {type: string}
                  maxCommissionChangePerEpoch: {type: string}
              stake:                           {type: string}
              state:
                type:                          object
                properties:
                  epoch:                       {type: string}
                  state:                       {type: string}
              createdAt:                       {type: string, format: date-time}
              updatedAt:                       {type: string, format: date-time}
        totalProposals:                        {type: integer}
        totalVotes:                            {type: integer}

    SearchResults:
      type:           object
      properties:
        blocks:       {type: array}
        transactions: {type: array}
        proposals:    {type: array}

    BlocksList:
      type: object
      properties:
        totalBlocks:
          type: integer
          description: Total number of blocks matching the query parameters
        latestBlock:
          type: integer
          description: Height of the latest block in the returned list
        oldestBlock:
          type: integer
          description: Height of the oldest block in the returned list
        count:
          type: integer
          description: Number of blocks returned in this response
        blocks:
          type: array
          items:
            type: object
            properties:
              blockHeight:
                type: integer
                description: Height of the block
              blockHash:
                type: string
                description: Hash of the block
              blockTime:
                type: string
                format: date-time
                description: Time when the block was created
              transactionCount:
                type: integer
                description: Number of transactions in the block

    BlockDetails:
      type:                                         object
      properties:
        blockHeight:                                {type: integer}
        blockHash:                                  {type: string}
        blockTime:                                  {type: string, format: date-time}
        transactionCount:                           {type: integer}
        proposer:
          type:                                     object
          properties:
            namadaAddress:                          {type: string}
            publicKey:                              {type: string}
            consensusAddress:                       {type: string}
            metadata:
              type:                                 object
              properties:
                name:                               {type: string}
                email:                              {type: string}
                avatar:                             {type: string}
                website:                            {type: string}
                description:                        {type: string}
                discordHandle:                      {type: string}
        signers:
          type:                                     array
          items:
            type:                                   object
            properties:
              namadaAddress:                        {type: string}
              publicKey:                            {type: string}
              consensusAddress:                     {type: string}
              metadata:
                type:                               object
                properties:
                  name:                             {type: string}
                  email:                            {type: string}
                  avatar:                           {type: string}
                  website:                          {type: string}
                  description:                      {type: string}
                  discordHandle:                    {type: string}
        transactions:
          type:                                     array
          items:
            type:                                   object
            properties:
              chainId:                              {type: string}
              blockHash:                            {type: string}
              blockHeight:                          {type: integer}
              blockTime:                            {type: string, format: date-time}
              txHash:                               {type: string}
              txTime:                               {type: string, format: date-time}
              txData:
                type:                               object
                properties:
                  id:                               {type: string}
                  data:
                    type:                           object
                    properties:
                      type:
                        type:                       object
                        properties:
                          Wrapper:
                            type:                   object
                            properties:
                              pk:
                                type:               object
                                properties:
                                  pk:               {type: string}
                                  type:             {type: string}
                              fee:
                                type:               object
                                properties:
                                  token:            {type: string}
                                  amountPerGasUnit: {type: string}
                              payer:                {type: string}
                              feeToken:             {type: string}
                              gasLimit:             {type: string}
                              multiplier:           {type: string}
                              gasLimitMultiplier:   {type: string}
                              feeAmountPerGasUnit:  {type: string}

    TransactionsList:
      type: object
      properties:
        count:
          type: integer
          description: Total count of transactions
        transactions:
          type: array
          items:
            type: object
            properties:
              txHash: {type: string}
              date: {type: string, format: date-time}

    TransactionDetail:
      type: object
      properties:
        chainId:
          type: string
          description: Identifier of the blockchain network
        blockHash:
          type: string
          description: Hash of the block containing this transaction
        blockHeight:
          type: integer
          description: Height of the block containing this transaction
        blockTime:
          type: string
          format: date-time
          description: Time when the block containing this transaction was created
        txHash:
          type: string
          description: Hash identifier of the transaction
        txTime:
          type: string
          format: date-time
          description: Time when the transaction was executed
        txData:
          type: object
          properties:
            id:
              type: string
              description: Identifier of the transaction data
            data:
              type: object
              properties:
                type:
                  type: object
                  properties:
                    Wrapper:
                      type: object
                      properties:
                        pk:
                          type: object
                          properties:
                            pk:
                              type: string
                              description: Public key associated with the transaction
                            type:
                              type: string
                              description: Public key type
                        fee:
                          type: object
                          properties:
                            token:
                              type: string
                              description: Token used for transaction fee
                            amountPerGasUnit:
                              type: string
                              description: Amount per gas unit for the transaction fee
                        payer:
                          type: string
                          description: Payer of the transaction fee
                        feeToken:
                          type: string
                          description: Token used for transaction fee
                        gasLimit:
                          type: string
                          description: Gas limit for the transaction
                        multiplier:
                          type: string
                          description: Multiplier associated with the transaction
                        gasLimitMultiplier:
                          type: string
                          description: Gas limit multiplier associated with the transaction
                        feeAmountPerGasUnit:
                          type: string
                          description: Fee amount per gas unit associated with the transaction
                batch:
                  type: array
                  items:
                    type: object
                    properties:
                      hash:
                        type: string
                        description: Hash associated with the batch
                      codeHash:
                        type: string
                        description: Code hash associated with the batch
                      dataHash:
                        type: string
                        description: Data hash associated with the batch
                      memoHash:
                        type: string
                        description: Memo hash associated with the batch
                atomic:
                  type: boolean
                  description: Boolean indicating if the transaction is atomic
                chainId:
                  type: string
                  description: Identifier of the blockchain network
                content:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        address:
                          type: string
                          description: Address associated with the content
                        threshold:
                          type: integer
                          description: Threshold associated with the content
                        publicKeys:
                          type: array
                          items:
                            type: string
                          description: Public keys associated with the content
                      description: Content data associated with the transaction
                    type:
                      type: string
                      description: Type associated with the content
                sections:
                  type: array
                  items:
                    type: object
                    properties:
                      tag:
                        type: string
                        description: Tag associated with the section
                      code:
                        type: string
                        description: Code associated with the section
                      salt:
                        type: string
                        description: Salt associated with the section
                      type:
                        type: string
                        description: Type associated with the section
                    description: Sections associated with the transaction
                timestamp:
                  type: string
                  description: Timestamp associated with the transaction
                expiration:
                  type: string
                  description: Expiration associated with the transaction
              description: Data associated with the transaction
          description: Transaction data associated with the transaction

    ProposalsList:
      type:             object
      properties:
        count:          {type:integer}
        proposals:
          type:         array
          items:
            type:       object
            properties:
              id:       {type: integer}
              content:  {type: object}
              metadata: {type: object}
              result:   {type: object}

    ProposalsStats:
      type:       object
      properties:
        all:      {type:integer}
        ongoing:  {type:integer}
        upcoming: {type:integer}
        finished: {type:integer}
        passed:   {type:integer}
        rejected: {type:integer}

    ProposalDetail:
      type:                  object
      properties:
        id:                  {type: integer}
        content:             {type: object}
        metadata:            {type: object}
        result:              {type: object}

    VotesPage:
      type:                  object
      properties:
        count:               {type: integer}
        votes:
          type:              array
          items:
            type:            object
            properties:
              data:
                type:        object
                properties:
                  data:      {type: string}
                  delegator: {type: string}
                  validator: {type: string}

    TransferList:
      type:           object
      properties:
        transfers:
          type:       array
          items:
            type:     object
            properties:
              from:   {type: string}
              to:     {type: string}
              amount: {type: integer}
              date:   {type: string, format: date-time}

    EpochInfo:
      type:             object
      properties:
        timestamp:      {type: string}
        epoch:          {type: string}
        firstBlock:     {type: string}
        minNumOfBlocks: {type: string}
        minDuration:    {type: string}

    TotalStaked:
      type:          object
      properties:
        timestamp:   {type: string}
        totalStaked: {type: string}

    PoSParams:
      type:                            object
      properties:
        maxValidatorSlots:             {type: string}
        pipelineLen:                   {type: string}
        unbondingLen:                  {type: string}
        tmVotesPerToken:               {type: string}
        blockProposerReward:           {type: string}
        blockVoteReward:               {type: string}
        maxInflationRate:              {type: string}
        targetStakedRatio:             {type: string}
        duplicateVoteMinSlashRate:     {type: string}
        lightClientAttackMinSlashRate: {type: string}
        cubicSlashingWindowLength:     {type: string}
        validatorStakeThreshold:       {type: string}
        livenessWindowCheck:           {type: string}
        livenessThreshold:             {type: string}
        rewardsGainP:                  {type: string}
        rewardsGainD:                  {type: string}
        maxProposalPeriod:             {type: string}

    GovParams:
      type:                      object
      properties:
        minProposalFund:         {type: string}
        maxProposalCodeSize:     {type: string}
        minProposalVotingPeriod: {type: string}
        maxProposalPeriod:       {type: string}
        maxProposalContentSize:  {type: string}
        minProposalGraceEpochs:  {type: string}

    PGFParams:
      type:                    object
      properties:
        stewards:              {type: object}
        pgfInflationRate:      {type: string}
        stewardsInflationRate: {type: string}

    ValidatorsStates:
      type: object
      properties:
        Consensus:
          type: integer
          description: Number of validators in consensus
        Jailed:
          type: integer
          description: Number of validators currently jailed
        BelowThreshold:
          type: integer
          description: Number of validators currently below threshold
        BelowCapacity:
          type: integer
          description: Number of validators currently below capacity
        Inactive:
          type: integer
          description: Number of validators currently inactive

    ValidatorsList:
      type:                      object
      properties:
        count:                   {type: integer, description: "Total count of validators"}
        validators:
          type:                  array
          items:
            type:                object
            properties:
              publicKey:         {type: string}
              address:           {type: string}
              namadaAddress:     {type: string}
              votingPower:       {type: string}
              proposerPriority:  {type: string}
              metadata:          {type: object}
              commission:        {type: object}
              stake:             {type: string}
              state:             {type: object}

    ValidatorDetails:
      type:                object
      properties:
        publicKey:         {type: string}
        address:           {type: string}
        namadaAddress:     {type: string}
        votingPower:       {type: string}
        proposerPriority:  {type: string}
        metadata:          {type: object}
        commission:        {type: object}
        stake:             {type: string}
        state:             {type: object}
        uptime:            {type: integer}
        currentHeight:     {type: integer}
        countedBlocks:     {type: integer}