Skip to main content

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 IDfmt.Println("full ID: ", manas.NodeID, "short ID: ", manas.ShortNodeID)
// get access mana of the nodefmt.Println("access mana: ", manas.Access, "access mana updated time: ", manas.AccessTimestamp)
// get consensus mana of the nodefmt.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 timefmt.Println("access mana updated time: ", manas.AccessTimestamp)fmt.Println("consensus mana updated time: ", manas.ConsensusTimestamp)
// get access mana of each nodefor _, 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 nodefor _, 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 timefmt.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 manaaccessMana, 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 manaaccessMana, 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 nodesaccessMana, 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 nodesconsensusMana, 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 manafmt.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 nodefor _, 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 tofor _, id := range res.Access.Allowed {    fmt.Println("node ID:", id)}
// print the list of nodes that consensus mana is allowed to be pledged tofor _, 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