Mana API Methods

The mana APIs provide methods for people to retrieve the amount of access/consensus mana of nodes and outputs, as well as the event logs.

HTTP APIs:

Client lib APIs:


/mana

Get the access and consensus mana of the node.

Parameters

Parameternode ID
Required or Optionaloptional
Descriptionfull node ID
Typestring

Note

If no node ID is given, it returns the access and consensus mana of the node you're communicating with.

Examples

cURL

curl http://localhost:8080/mana?2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5 \
-X GET \
-H 'Content-Type: application/json'

client lib

There are 3 APIs to get mana of a node, which is based on the same HTTP API /mana.

GetOwnMana

Get the access and consensus mana of the node this API client is communicating with.

manas, err := goshimAPI.GetOwnMana()
if err != nil {
    // return error
}

// print the node ID
fmt.Println("full ID: ", manas.NodeID, "short ID: ", manas.ShortNodeID)

// get access mana of the node
fmt.Println("access mana: ", manas.Access, "access mana updated time: ", manas.AccessTimestamp)

// get consensus mana of the node
fmt.Println("consensus mana: ", manas.Consensus, "consensus mana updated time: ", manas.ConsensusTimestamp)
GetManaFullNodeID

Get Mana of a node with its full node ID.

manas, err := goshimAPI.GetManaFullNodeID("2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5")
if err != nil {
    // return error
}
GetMana with short node ID
manas, err := goshimAPI.GetMana("4AeXyZ26e4G")
if err != nil {
    // return error
}

Response examples

{
  "shortNodeID": "4AeXyZ26e4G",
  "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
  "access": 26.5,
  "accessTimestamp": 1614924295,
  "consensus": 26.5,
  "consensusTimestamp": 1614924295,
}

Results

Return fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
accessfloat64The amount of access mana.
accessTimestampint64The timestamp of access mana updates.
consensusfloat64The amount of consensus mana.
consensusTimestampint64The timestamp of consensus mana updates.

/mana/all

Get the mana perception of the node in the network. You can retrieve the full/short node ID, consensus mana, access mana of each node, and the mana updated time.

Parameters

None.

Examples

cURL

curl http://localhost:8080/mana/all \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetAllMana()

manas, err := goshimAPI.GetAllMana()
if err != nil {
    // return error
}

// mana updated time
fmt.Println("access mana updated time: ", manas.AccessTimestamp)
fmt.Println("consensus mana updated time: ", manas.ConsensusTimestamp)

// get access mana of each node
for _, m := range manas.Access {
    fmt.Println("full node ID: ", m.NodeID, "short node ID:", m.ShortNodeID, "access mana: ", m.Mana)
}

// get consensus mana of each node
for _, m := range manas.Consensus {
    fmt.Println("full node ID: ", m.NodeID, "short node ID:", m.ShortNodeID, "consensus mana: ", m.Mana)
}

Response examples

{
  "access": [
      {
          "shortNodeID": "4AeXyZ26e4G",
          "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
          "mana": 26.5
      }
  ],
  "accessTimestamp": 1614924295,
  "consensus": [
      {
          "shortNodeID": "4AeXyZ26e4G",
          "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
          "mana": 26.5
      }
  ],
  "consensusTimestamp": 1614924295
}

Results

Return fieldTypeDescription
accessmana.NodeStrA list of node that has access mana.
accessTimestampint64The timestamp of access mana updates.
consensusmana.NodeStrA list of node that has access mana.
consensusTimestampint64The timestamp of consensus mana updates.

Type mana.NodeStr

fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of mana.

/mana/percentile

To learn the top percentile the node belongs to relative to the network in terms of mana. The input should be a full node ID.

Parameters

Parameternode ID
Required or OptionalRequired
Descriptionfull node ID
Typestring

Examples

cURL

curl http://localhost:8080/mana/percentile?2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5 \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetManaPercentile()

mana, err := goshimAPI.GetManaPercentile("2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5")
if err != nil {
    // return error
}

// mana updated time
fmt.Println("access mana percentile: ", mana.Access, "access mana updated time: ", manas.AccessTimestamp)
fmt.Println("consensus mana percentile: ", mana.Consensus, "consensus mana updated time: ", manas.ConsensusTimestamp)

Response examples

{
  "shortNodeID": "4AeXyZ26e4G",
  "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
  "access": 75,
  "accessTimestamp": 1614924295,
  "consensus": 75,
  "consensusTimestamp": 1614924295,
}

Results

Return fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
accessfloat64Access mana percentile of a node.
accessTimestampint64The timestamp of access mana updates.
consensusfloat64Access mana percentile of a node.
consensusTimestampint64The timestamp of consensus mana updates.

/mana/access/online

You can get a sorted list of online access mana of nodes, sorted from the highest access mana to the lowest. The highest access mana node has OnlineRank 1, and increases 1 by 1 for the following nodes.

Parameters

None.

Examples

cURL

curl http://localhost:8080/mana/access/online \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetOnlineAccessMana()

// online access mana
accessMana, err := goshimAPI.GetOnlineAccessMana()
if err != nil {
    // return error
}

for _, m := accessMana.Online {
    fmt.Println("full node ID: ", m.ID, "mana rank: ", m.OnlineRank, "access mana: ", m.Mana)
}

Response examples

{
  "online": [
      {
        "rank": 1,
        "shortNodeID": "4AeXyZ26e4G",
        "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
        "mana": 75
      }
  ],  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
onlineOnlineNodeStrThe access mana information of online nodes.
timestampint64The timestamp of mana updates.

Type OnlineNodeStr

FieldTypeDescription
rankintThe rank of a node.
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of access mana.

/mana/consensus/online

You can get a sorted list of online consensus mana of nodes, sorted from the highest consensus mana to the lowest. The highest consensus mana node has OnlineRank 1, and increases 1 by 1 for the following nodes.

Parameters

None.

Examples

cURL

curl http://localhost:8080/mana/consensus/online \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetOnlineConsensusMana()

// online access mana
accessMana, err := goshimAPI.GetOnlineConsensusMana()
if err != nil {
    // return error
}

for _, m := accessMana.Online {
    fmt.Println("full node ID: ", m.ID, "mana rank: ", m.OnlineRank, "consensus mana: ", m.Mana)
}

Response examples

{
  "online": [
      {
        "rank": 1,
        "shortNodeID": "4AeXyZ26e4G",
        "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
        "mana": 75
      }
  ],  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
onlineOnlineNodeStrThe consensus mana information of online nodes.
timestampint64The timestamp of mana updates.

Type OnlineNodeStr

FieldTypeDescription
rankintThe rank of a node.
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of consensus mana.

/mana/access/nhighest

You can get the N highest access mana holders in the network, sorted in descending order. If N=0, all nodes that have access mana are returned sorted.

Parameters

ParameterN
Required or OptionalRequired
DescriptionThe number of highest mana nodes.
Typeint

Examples

cURL

curl http://localhost:8080/mana/access/nhighest?number=5 \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetNHighestAccessMana()

// get the top 5 highest access mana nodes
accessMana, err := goshimAPI.GetNHighestAccessMana(5)
if err != nil {
    // return error
}

for _, m := accessMana.Nodes {
    fmt.Println("full node ID: ", m.NodeID, "access mana: ", m.Mana)
}v

Response examples

{
  "nodes": [
      {
        "shortNodeID": "4AeXyZ26e4G",
        "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
        "mana": 26.5
      }
  ],  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
nodesmana.NodeStrThe N highest access mana nodes.
timestampint64The timestamp of mana updates.

Type mana.NodeStr

fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of mana.

/mana/consensus/nhighest

You can get the N highest consensus mana holders in the network, sorted in descending order.

Parameters

ParameterN
Required or OptionalRequired
DescriptionThe number of highest consensus mana nodes.
Typeint

Examples

cURL

curl http://localhost:8080/mana/consensus/nhighest?number=5 \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetNHighestConsensusMana()

// get the top 5 highest consensus mana nodes
consensusMana, err := goshimAPI.GetNHighestConsensusMana(5)
if err != nil {
    // return error
}

for _, m := consensusMana.Nodes {
    fmt.Println("full node ID: ", m.NodeID, "consensus mana: ", m.Mana)
}v

Response examples

{
  "nodes": [
      {
        "shortNodeID": "4AeXyZ26e4G",
        "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
        "mana": 26.5
      }
  ],  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
nodesmana.NodeStrThe N highest consensus mana nodes.
timestampint64The timestamp of mana updates.

Type mana.NodeStr

fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of mana.

/mana/pending

Get the amount of base access mana that would be pledged if the given output was spent.

Parameters

ParameteroutputID
Required or OptionalRequired
DescriptionThe requesting output ID.
Typestring

Examples

cURL

curl http://localhost:8080/mana/pending?outputid="4a5KkxVfsdFVbf1NBGeGTCjP8Ppsje4YFQg9bu5YGNMSJK1" \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetPending()

res, err := goshimAPI.GetPending("4a5KkxVfsdFVbf1NBGeGTCjP8Ppsje4YFQg9bu5YGNMSJK1")
if err != nil {
    // return error
}

// get the amount of mana
fmt.Println("mana be pledged: ", res.Mana)
fmt.Println("the timestamp of the output (decay duration)", res.Timestamp)

Response examples

{
  "mana": 26.5,
  "outputID": "4a5KkxVfsdFVbf1NBGeGTCjP8Ppsje4YFQg9bu5YGNMSJK1",  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
manafloat64The amount of access base mana to be pledged.
outputIDstringThe output ID of the request.
timestampint64The timestamp of mana updates.

/mana/consensus/past

Get the consensus base mana vector of a time (int64) in the past.

Parameters

Parametertimestamp
Required or OptionalRequired
DescriptionThe timestamp of the request.
Typeint64

Examples

cURL

curl http://localhost:8080/mana/consensus/past?timestamp=1614924295 \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetPastConsensusManaVector()

res, err := goshimAPI.GetPastConsensusManaVector(1614924295)
if err != nil {
    // return error
}

// the mana vector of each node
for _, m := range res.Consensus {
    fmt.Println("node ID:", m.NodeID, "consensus mana: ", m.Mana)
}

Response examples

{
  "consensus": [
      {
        "shortNodeID": "4AeXyZ26e4G",
        "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
        "mana": 26.5 
      }
  ],  
  "timestamp": 1614924295
}

Results

Return fieldTypeDescription
consensusmana.NodeStrThe consensus mana of nodes.
timestampint64The timestamp of mana updates.

Type mana.NodeStr

fieldTypeDescription
shortNodeIDstringThe short ID of a node.
nodeIDstringThe full ID of a node.
manafloat64The amount of mana.

/mana/consensus/logs

Get the consensus event logs of the given node IDs.

Parameters

ParameternodeIDs
Required or OptionalRequired
DescriptionA list of node ID of the request.
Typestring array

Examples

cURL

curl http://localhost:8080/mana/consensus/logs \
-X GET \
-H 'Content-Type: application/json'
-d '{
  "nodeIDs": [
    "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
    "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux6"
  ]
}'

Client lib - GetConsensusEventLogs()

res, err := goshimAPI.GetConsensusEventLogs([]string{"2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5"})
if err != nil {
    // return error
}

for nodeID, e := range res.Logs {
    fmt.Println("node ID:", nodeID)
    
    // pledge logs
    for _, p := e.Pledge {
        fmt.Println("mana type: ", p.ManaType)
        fmt.Println("node ID: ", p.NodeID)
        fmt.Println("time: ", p.Time)
        fmt.Println("transaction ID: ", p.TxID)
        fmt.Println("mana amount: ", p.Amount)
    }

    // revoke logs
    for _, r := e.Revoke {
        fmt.Println("mana type: ", r.ManaType)
        fmt.Println("node ID: ", r.NodeID)
        fmt.Println("time: ", r.Time)
        fmt.Println("transaction ID: ", r.TxID)
        fmt.Println("mana amount: ", r.Amount)
        fmt.Println("input ID: ", r.InputID)
    }
}

Response examples

{
  "logs": [
      "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5": {
          "pledge": [
              {
                  "manaType": "Consensus",
                  "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
                  "time": 1614924295,
                  "txID": "7oAfcEhodkfVyGyGrobBpRrjjdsftQknpj5KVBQjyrda",
                  "amount": 28
               }
          ],
          "revoke": [
              {
                  "manaType": "Consensus",
                  "nodeID": "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5",
                  "time": 1614924295,
                  "txID": "7oAfcEhodkfVyGyGrobBpRrjjdsftQknpj5KVBQjyrda",
                  "amount": 28,
                  "inputID": "35P4cW9QfzHNjXJwZMDMCUxAR7F9mfm6FvPbdpJWudK2nBZ"
              }
          ]
      }
  ],  
  "startTime": 1614924295,
  "endTime": 1614924300
}

Results

Return fieldTypeDescription
logsmap[string]*EventLogsJSONThe consensus mana of nodes. The key of map is node ID.
startTimeint64The starting time of collecting logs.
endTimeint64The ending time of collecting logs.

Type EventLogsJSON

fieldTypeDescription
pledgePledgedEventJSONPledged event logs.
revokeRevokedEventJSONRevoked event logs.

Type PledgedEventJSON

fieldTypeDescription
manaTypestringType of mana.
nodeIDstringThe full ID of a node.
timeint64The time of transaction.
txIDstringThe transaction ID of pledged mana.
amountfloat64The amount of pledged mana.

Type RevokedEventJSON

fieldTypeDescription
manaTypestringType of mana.
nodeIDstringThe full ID of a node.
timeint64The time of transaction.
txIDstringThe transaction ID of revoked mana.
amountfloat64The amount of revoked mana.
inputIDstringThe input ID of revoked mana.

/mana/allowedManaPledge

This returns the list of allowed mana pledge node IDs.

Parameters

None.

Examples

cURL

curl http://localhost:8080/mana/allowedManaPledge \
-X GET \
-H 'Content-Type: application/json'

Client lib - GetAllowedManaPledgeNodeIDs()

res, err := goshimAPI.GetAllowedManaPledgeNodeIDs()
if err != nil {
    // return error
}

// print the list of nodes that access mana is allowed to be pledged to
for _, id := range res.Access.Allowed {
    fmt.Println("node ID:", id)
}

// print the list of nodes that consensus mana is allowed to be pledged to
for _, id := range res.Consensus.Allowed {
    fmt.Println("node ID:", id)
}

Response examples

{
  "accessMana": {
      "isFilterEnabled": false,
      "allowed": [
          "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5"
      ] 
  }
  "consensusMana": {
      "isFilterEnabled": false,
      "allowed": [
          "2GtxMQD94KvDH1SJPJV7icxofkyV1njuUZKtsqKmtux5"
      ] 
  }
}

Results

Return fieldTypeDescription
accessManaAllowedPledgeA list of nodes that allow to pledge access mana.
consensusManaAllowedPledgeA list of nodes that allow to pledge consensus mana.

Type AllowedPledge

fieldTypeDescription
isFilterEnabledboolA flag shows that if mana pledge filter is enabled.
allowed[]stringA list of node ID that allow to be pledged mana. This list has effect only if isFilterEnabled is true