Tags

What are Tags?

Tags are content trackers that can hold any string based content, as well as providing a way to store a checksum of the content and the algorithm used to produce the checksum. Tags can also easily be updated to change the underlying content with the option of updating the checksum and algorithm fields if necessary.

In short, Tags allow developers to attach specific, verifiable content to Items that will travel with changes in Item ownership. Anyone can verify the contents of a tag by running the defined checksum algorithm over the content and comparing to the checksum stored on the tag.

Tag Name Standards

The following are existing tag name standards in use throughout Marble.

Name	Description
image	An item's image that can be consumed by a frontend UI.
title	A title that identifies the item.
subtitle	A short tweet-length subtitle for the item.

Shared Tags

The Tags layer also includes Shared Tags, which funciton the same as normal Item Tags but are assigned to an entire group instead of an individual item. Use Shared Tags to handle Tags that all items inherit or to save on RAM costs.

Tag Locks

Tags can also be locked, which prevents any further changes to the given Tag and effectively makes it immutable. Once locked, the tag can never become unlocked again.

Table Breakdown

Table Name: tags

Table Scoping: item.serial

Field Name	Field Type	Description
tag_name	name	Tag Name Identifier
content	string	Tag Content (JSON, REST Endpoint, IPFS CID, etc.)
checksum	string	Checksum of content
algorithm	string	Algorithm used to produce checksum
locked	bool	Tag is locked if true

No extra indices.

Create a New Tag

To create a new tag for an Item call the newtag() action.

Required Authority: group.manager

Note that parameters marked as optional still require the 'null' argument in their place and can't simply be omitted in the transaction.

Action Parameters

Name	Type	Example	Description
serial	uint64_t	5	The serial number of the Item to tag.
tag_name	name	tag1	The name of the new tag.
content	string	"content here"	The content of the tag (JSON, Markdown, IPFS CID, etc).
checksum	optional<string>	"f83jfya7"	Checksum of the content field.
algorithm	optional<string>	"sha256"	The algorithm used to produce the checksum.
shared	bool	false	Create shared tag if true.

Examples

Cleos

cleos push action {account} newtag '[ {params} ]' -p {manager}

Marble CLI

marble make tag ...

Update a Tag

To update a tag call the updatetag() action.

Required Authority: group.manager

Action Parameters

Name	Type	Example	Description
serial	uint64_t	5	The serial number of the Item with the tag to update.
tag_name	name	tag1	The name of the tag to update.
new_content	string	"new content here"	The new content for the tag.
new_checksum	optional<string>	"mfau72n4"	The checksum of the new content.
new_algorithm	optional<string>	"md5"	The algorithm used to produce the checksum.
shared	bool	true	Update a shared tag if true.

Examples

Cleos

cleos push action {account} updatetag '[ {params} ]' -p {manager}

Marble CLI

marble modify tag ...

Lock a Tag

Lock a tag and prevent future updates with the locktag() action.

Required Authority: group.manager

Action Parameters

Name	Type	Example	Description
group_name	name	testgroup	The name of the group with the behavior to lock.
behavior_name	name	transfer	The name of the behavior to lock.
shared	bool	true	Lock a shared tag if true.

Examples

Cleos

cleos push action {account} lockbhvr '[ ... ]' -p {account}

Marble CLI

marble lock ...

Remove a Tag

To remove a tag from an Item call the rmvtag() action.

Required Authority: group.manager

Action Parameters

Name	Type	Example	Description
serial	uint64_t	5	The serial of the Item with the Tag.
tag_name	name	tag1	The name of the tag to remove.
memo	string	"Removing Tag"	An optional memo field.
shared	bool	false	Remove a shared tag if true.

Examples

Cleos

cleos push action {account} rmvtag '[ ... ]' -p {manager}

Marble CLI

marble remove tag ...