Skip to main content

LSP2Utils

LSP2Utils

Standard Specifications
Solidity implementation

LSP2 Utility library.

LSP2Utils is a library of utility functions that can be used to encode data key of different key type defined on the LSP2 standard. Based on LSP2 ERC725Y JSON Schema standard.

Internal Methods

Any method labeled as internal serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs.

Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities.

generateSingletonKey

function generateSingletonKey(string keyName) internal pure returns (bytes32);

Generates a data key of keyType Singleton by hashing the string keyName. As:

keccak256("keyName")

Parameters

NameTypeDescription
keyNamestringThe string to hash to generate a Singleton data key.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Singleton.

generateArrayKey

function generateArrayKey(string arrayKeyName) internal pure returns (bytes32);

Generates a data key of keyType Array by hashing arrayKeyName. As:

keccak256("arrayKeyName[]")

Parameters

NameTypeDescription
arrayKeyNamestringThe string that will be used to generate a data key of key type Array.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Array.

generateArrayElementKeyAtIndex

function generateArrayElementKeyAtIndex(
bytes32 arrayKey,
uint128 index
) internal pure returns (bytes32);

Generates an Array data key at a specific index by concatenating together the first 16 bytes of arrayKey with the 16 bytes of index. As:

arrayKey[index]

Parameters

NameTypeDescription
arrayKeybytes32The Array data key from which to generate the Array data key at a specific index.
indexuint128The index number in the arrayKey.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Array at a specific index.

generateMappingKey

function generateMappingKey(
string firstWord,
string lastWord
) internal pure returns (bytes32);

Generates a data key of key type Mapping that map firstWord to lastWord. This is done by hashing two strings words firstWord and lastWord. As:

bytes10(firstWordHash):0000:bytes20(lastWordHash)

Parameters

NameTypeDescription
firstWordstringThe word to retrieve the first 10 bytes of its hash.
lastWordstringThe word to retrieve the first 10 bytes of its hash.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Mapping that map firstWord to a specific lastWord.

generateMappingKey

function generateMappingKey(
string firstWord,
address addr
) internal pure returns (bytes32);

Generates a data key of key type Mapping that map firstWord to an address addr. This is done by hashing the string word firstWord and concatenating its first 10 bytes with addr. As:

bytes10(firstWordHash):0000:<address>

Parameters

NameTypeDescription
firstWordstringThe word to retrieve the first 10 bytes of its hash.
addraddressAn address to map firstWord to.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Mapping that map firstWord to a specific address addr.

generateMappingKey

function generateMappingKey(
bytes10 keyPrefix,
bytes20 bytes20Value
) internal pure returns (bytes32);

Generate a data key of key type Mapping that map a 10 bytes keyPrefix to a bytes20Value. As:

keyPrefix:bytes20Value

Parameters

NameTypeDescription
keyPrefixbytes10The first part of the data key of key type Mapping.
bytes20Valuebytes20The second part of the data key of key type Mapping.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type Mapping that map a keyPrefix to a specific bytes20Value.

generateMappingWithGroupingKey

function generateMappingWithGroupingKey(
string firstWord,
string secondWord,
address addr
) internal pure returns (bytes32);

Generate a data key of key type MappingWithGrouping by using two strings firstWord mapped to a secondWord mapped itself to a specific address addr. As:

bytes6(keccak256("firstWord")):bytes4(keccak256("secondWord")):0000:<address>

Parameters

NameTypeDescription
firstWordstringThe word to retrieve the first 6 bytes of its hash.
secondWordstringThe word to retrieve the first 4 bytes of its hash.
addraddressThe address that makes the last part of the MappingWithGrouping.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type MappingWithGrouping that map a firstWord to a secondWord to a specific address addr.

generateMappingWithGroupingKey

function generateMappingWithGroupingKey(
bytes6 keyPrefix,
bytes4 mapPrefix,
bytes20 subMapKey
) internal pure returns (bytes32);

Generate a data key of key type MappingWithGrouping that map a keyPrefix to an other mapPrefix to a specific subMapKey. As:

keyPrefix:mapPrefix:0000:subMapKey

Parameters

NameTypeDescription
keyPrefixbytes6The first part (6 bytes) of the data key of keyType MappingWithGrouping.
mapPrefixbytes4The second part (4 bytes) of the data key of keyType MappingWithGrouping.
subMapKeybytes20The last part (bytes20) of the data key of keyType MappingWithGrouping.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type MappingWithGrouping that map a keyPrefix to a mapPrefix to a specific subMapKey.

generateMappingWithGroupingKey

function generateMappingWithGroupingKey(
bytes10 keyPrefix,
bytes20 bytes20Value
) internal pure returns (bytes32);

Generate a data key of key type MappingWithGrouping that map a 10 bytes keyPrefix to a specific bytes20Value. As:

Parameters

NameTypeDescription
keyPrefixbytes10The first part of the data key of keyType MappingWithGrouping.
bytes20Valuebytes20The last of the data key of keyType MappingWithGrouping.

Returns

NameTypeDescription
0bytes32The generated bytes32 data key of key type MappingWithGrouping that map a keyPrefix

generateJSONURLValue

function generateJSONURLValue(
string hashFunction,
string json,
string url
) internal pure returns (bytes);

Generate a JSONURL value content.

Parameters

NameTypeDescription
hashFunctionstringThe function used to hash the JSON file.
jsonstringBytes value of the JSON file.
urlstringThe URL where the JSON file is hosted.

generateASSETURLValue

function generateASSETURLValue(
string hashFunction,
string assetBytes,
string url
) internal pure returns (bytes);

Generate a ASSETURL value content.

Parameters

NameTypeDescription
hashFunctionstringThe function used to hash the JSON file.
assetBytesstringBytes value of the JSON file.
urlstringThe URL where the JSON file is hosted.

Returns

NameTypeDescription
0bytesThe encoded value as an ASSETURL.

isEncodedArray

function isEncodedArray(bytes data) internal pure returns (bool);

Verify if data is an abi-encoded array.

Parameters

NameTypeDescription
databytesThe bytes value to verify.

Returns

NameTypeDescription
0booltrue if the data represents an abi-encoded array, false otherwise.

isEncodedArrayOfAddresses

function isEncodedArrayOfAddresses(bytes data) internal pure returns (bool);

Verify if data is an abi-encoded array of addresses (address[]) encoded according to the ABI specs.

Parameters

NameTypeDescription
databytesThe bytes value to verify.

Returns

NameTypeDescription
0booltrue if the data represents an abi-encoded array of addresses, false otherwise.

isBytes4EncodedArray

function isBytes4EncodedArray(bytes data) internal pure returns (bool);

Verify if data is an abi-array of bytes4 values (bytes4[]) encoded according to the ABI specs.

Parameters

NameTypeDescription
databytesThe bytes value to verify.

Returns

NameTypeDescription
0booltrue if the data represents an abi-encoded array of bytes4, false otherwise.

isCompactBytesArray

function isCompactBytesArray(
bytes compactBytesArray
) internal pure returns (bool);

Verify if data is a valid array of value encoded as a CompactBytesArray according to the LSP2 CompactBytesArray valueType specification.

Parameters

NameTypeDescription
compactBytesArraybytesThe bytes value to verify.

Returns

NameTypeDescription
0booltrue if the data is correctly encoded CompactBytesArray, false otherwise.

isValidLSP2ArrayLengthValue

function isValidLSP2ArrayLengthValue(
bytes arrayLength
) internal pure returns (bool);

Validates if the bytes arrayLength are exactly 16 bytes long, and are of the exact size of an LSP2 Array length value

Parameters

NameTypeDescription
arrayLengthbytesPlain bytes that should be validated.

Returns

NameTypeDescription
0booltrue if the value is 16 bytes long, false otherwise.

removeLastElementFromArrayAndMap

function removeLastElementFromArrayAndMap(
bytes32 arrayKey,
uint128 newArrayLength,
bytes32 removedElementIndexKey,
bytes32 removedElementMapKey
) internal pure returns (bytes32[] dataKeys, bytes[] dataValues);

Generates Data Key/Value pairs for removing the last element from an LSP2 Array and a mapping Data Key.

Parameters

NameTypeDescription
arrayKeybytes32The Data Key of Key Type Array.
newArrayLengthuint128The new Array Length for the arrayKey.
removedElementIndexKeybytes32The Data Key of Key Type Array Index for the removed element.
removedElementMapKeybytes32The Data Key of a mapping to be removed.

removeElementFromArrayAndMap

info

The function assumes that the Data Value stored under the mapping Data Key is of length 20 where the last 16 bytes are the index of the element in the array.

function removeElementFromArrayAndMap(contract IERC725Y erc725YContract, bytes32 arrayKey, uint128 newArrayLength, bytes32 removedElementIndexKey, uint128 removedElementIndex, bytes32 removedElementMapKey) internal view returns (bytes32[] dataKeys, bytes[] dataValues);

Generates Data Key/Value pairs for removing an element from an LSP2 Array and a mapping Data Key.

Parameters

NameTypeDescription
erc725YContractcontract IERC725YThe ERC725Y contract.
arrayKeybytes32The Data Key of Key Type Array.
newArrayLengthuint128The new Array Length for the arrayKey.
removedElementIndexKeybytes32The Data Key of Key Type Array Index for the removed element.
removedElementIndexuint128the index of the removed element.
removedElementMapKeybytes32The Data Key of a mapping to be removed.