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 finalized
fmt.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.