Skip to main content

Communication Layer APIs

The communication layer represents the base Tangle layer where so called Messages are gossiped around. A Message contains payloads and it is up to upper layers to interpret and derive functionality out of them.

The API provides the following functions to interact with this primitive layer:

Client lib APIs:

/messages/:messageID#

Return message from the tangle.

Parameters#

ParametermessageID
Required or Optionalrequired
DescriptionID of a message to retrieve
Typestring

Examples#

cURL#

curl --location --request GET 'http://localhost:8080/messages/:messageID'

where :messageID is the base58 encoded message ID, e.g. 4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc.

Client lib - GetMessage#

Messages can be retrieved via GetMessage(base58EncodedID string) (*jsonmodels.Message, error)

message, err := goshimAPI.GetMessage(base58EncodedMessageID)if err != nil {    // return error}
// will print "Hello GoShimmer World"fmt.Println(string(message.Payload))

Note that we're getting actual Message objects from this call which represent a vertex in the communication layer Tangle. It does not matter what type of payload the message contains, meaning that this will also return messages which contain a transactions or DRNG payloads.

Response examples#

{    "id": "4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc",    "strongParents": [        "6LrXyDCorw8bTWKFaEmm3CZG6Nb6Ga8Bmosi1GPypGc1",        "B89koPthm9zDx1p1fbkHwoyC1Buq896Spu3Mx1SmSete"    ],    "weakParents": [],    "strongApprovers": [        "4E4ucAA9UTTd1UC6ri4GYaS4dpzEnHPjs5gMEYhpUK8p",        "669BRH69afQ7VfZGmNTMTeh2wnwXGKdBxtUCcRQ9CPzq"    ],    "weakApprovers": [],    "issuerPublicKey": "9DB3j9cWYSuEEtkvanrzqkzCQMdH1FGv3TawJdVbDxkd",    "issuingTime": 1621873309,    "sequenceNumber": 4354,    "payloadType": "GenericDataPayloadType(0)",    "payload": "BAAAAAAAAAA=",    "signature": "2J5XuVnmaHo54WipirWo7drJeXG3iRsnLYfzaPPuy6TXKiVBqv6ZYg2NjYP75xvgvut1SKNm8oYTchGi5t2SjyWJ"}

Results#

Return fieldTypeDescription
idstringMessage ID.
strongParents[]stringList of strong parents' message IDs.
weakParents[]stringList of weak parents' message IDs.
strongApprovers[]stringList of strong approvers' message IDs.
weakApprovers[]stringList of weak approvers' message IDs.
issuerPublicKey[]stringPublic key of issuing node.
issuingTimeint64Time this message was issued
sequenceNumberuint64Message sequence number.
payloadTypestringPayload type.
payload[]byteThe contents of the message.
signaturestringMessage signature.
errorstringError message. Omitted if success.

/messages/:messageID/metadata#

Return message metadata.

Parameters#

ParametermessageID
Required or Optionalrequired
DescriptionID of a message to retrieve
Typestring

Examples#

cURL#

curl --location --request GET 'http://localhost:8080/messages/:messageID/metadata'

where :messageID is the base58 encoded message ID, e.g. 4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc.

Client lib - GetMessageMetadata#

Message metadata can be retrieved via GetMessageMetadata(base58EncodedID string) (*jsonmodels.MessageMetadata, error)

message, err := goshimAPI.GetMessageMetadata(base58EncodedMessageID)if err != nil {    // return error}
// will print whether message is finalizedfmt.Println(string(message.Finalized))

Response examples#

{    "id": "4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc",    "receivedTime": 1621873309,    "solid": true,    "solidificationTime": 1621873309,    "structureDetails": {        "rank": 23323,        "pastMarkerGap": 0,        "isPastMarker": true,        "pastMarkers": {            "markers": {                "1": 21904            },            "highestIndex": 21904,            "lowestIndex": 21904        },        "futureMarkers": {            "markers": {                "1": 21905            },            "highestIndex": 21905,            "lowestIndex": 21905        }    },    "branchID": "BranchID(MasterBranchID)",    "scheduled": false,    "booked": true,    "eligible": true,    "invalid": false,    "finalized": true,    "finalizedTime": 1621873310}

Results#

Return fieldTypeDescription
idstringMessage ID.
receivedTimeint64Time when message was received by the node.
solidboolFlag indicating whether the message is solid.
solidificationTimeint64Time when message was solidified by the node.
structureDetailsStructureDetailsList of weak approvers' message IDs.
branchIDstringName of branch that the message is part of.
scheduledboolFlag indicating whether the message is scheduled.
bookedboolFlag indicating whether the message is booked.
eligibleboolFlag indicating whether the message is eligible.
invalidboolFlag indicating whether the message is invalid.
finalizedboolFlag indicating whether the message is finalized.
finalizedTimestringTime when message was finalized.
errorstringError message. Omitted if success.

/messages/:messageID/consensus#

Return message consensus info such as opinion and FCoB data.

Parameters#

ParametermessageID
Required or Optionalrequired
DescriptionID of a message to retrieve
Typestring

Examples#

cURL#

curl --location --request GET 'http://localhost:8080/messages/:messageID/consensus'

where :messageID is the base58 encoded message ID, e.g. 4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc.

Client lib#

This method is not available in the client library.

Response examples#

{  "id": "MessageID(4MSkwAPzGwnjCJmTfbpW4z4GRC7HZHZNS33c2JikKXJc)",  "opinionFormedTime": 1621873309,  "payloadOpinionFormed": true,  "timestampOpinionFormed": true,  "messageOpinionFormed": true,  "messageOpinionTriggered": true,  "timestampOpinion": "Like",  "timestampLoK": "LevelOfKnowledge(Two)"}

Results#

Return fieldTypeDescription
idstringMessage ID.
opinionFormedTimeint64Time when the node formed full opinion.
payloadOpinionFormedboolFlag indicating whether the node formed opinion about the payload.
timestampOpinionFormedboolFlag indicating whether the node formed opinion about the timestamp.
messageOpinionFormedboolFlag indicating whether the node formed opinion about the message.
messageOpinionTriggeredboolFlag indicating whether the node triggered an opinion formed event for the message.
timestampOpinionstringOpinion about the message's timestamp.
timestampLoKboolLevel of knowledge about message's timestamp.
errorstringError message. Omitted if success.

/data#

Method: POST

A data message is simply a Message containing some raw data (literally bytes). This type of message has therefore no real functionality other than that it is retrievable via GetMessage.

Parameters#

Parameterdata
Required or Optionalrequired
Descriptiondata bytes
Typebase64 serialized bytes

Body#

{  "data": "dataBytes"}

Examples#

cURL#

curl --location --request POST 'http://localhost:8080/data' \--header 'Content-Type: application/json' \--data-raw '{"data": "dataBytes"}'

Client lib - Data#

Data(data []byte) (string, error)#
messageID, err := goshimAPI.Data([]byte("Hello GoShimmer World"))if err != nil {    // return error}

Note that there is no need to do any additional work, since things like tip-selection, PoW and other tasks are done by the node itself.

Response examples#

{  "id": "messageID" }

Results#

Return fieldTypeDescription
idstringMessage ID of the message. Omitted if error.
errorstringError message. Omitted if success.

/messages/payload#

Method: POST

SendPayload() takes a payload object of any type (data, transaction, drng, etc.) as a byte slice, issues a message with the given payload and returns its messageID. Note that the payload must be valid, otherwise an error is returned.

Parameters#

Parameterpayload
Required or Optionalrequired
Descriptionpayload bytes
Typebase64 serialized bytes

Body#

{  "payload": "payloadBytes"}

Examples#

cURL#

curl --location --request POST 'http://localhost:8080/messages/payload' \--header 'Content-Type: application/json' \--data-raw '{"payload": "payloadBytes"}'

Client lib - SendPayload#

SendPayload(payload []byte) (string, error)#
helloPayload := payload.NewData([]byte{"Hello GoShimmer World!"})messageID, err := goshimAPI.SendPayload(helloPayload.Bytes())

Response examples#

{  "id": "messageID" }

Results#

Return fieldTypeDescription
idstringMessage ID of the message. Omitted if error.
errorstringError message. Omitted if success.

Note that there is no need to do any additional work, since things like tip-selection, PoW and other tasks are done by the node itself.