storage

Classes:

`StorageContext`	The storage context used to read and write data in smart contracts.
`StorageMap`	The key-value storage for the specific prefix in the given storage context.

Functions:

`get`	Gets a value from the persistent store based on the given key.
`get_int`	Gets a value as integer from the persistent store based on the given key.
`get_bool`	Gets a value as boolean from the persistent store based on the given key.
`get_str`	Gets a value as string from the persistent store based on the given key.
`get_list`	Gets a value as list from the persistent store based on the given key.
`get_dict`	Gets a value as dict from the persistent store based on the given key.
`get_object`	Gets a value as object from the persistent store based on the given key.
`get_uint160`	Gets a value as UInt160 from the persistent store based on the given key.
`get_uint256`	Gets a value as UInt256 from the persistent store based on the given key.
`get_ecpoint`	Gets a value as ECPoint from the persistent store based on the given key.
`try_get`	Gets a value from the persistent store based on the given key and returns whether the value is stored.
`try_get_int`	Gets a value as integer from the persistent store based on the given key and returns whether the value is stored.
`try_get_bool`	Gets a value as boolean from the persistent store based on the given key and returns whether the value is stored.
`try_get_str`	Gets a value as string from the persistent store based on the given key and returns whether the value is stored.
`try_get_list`	Gets a value as list from the persistent store based on the given key and returns whether the value is stored.
`try_get_dict`	Gets a value as dict from the persistent store based on the given key and returns whether the value is stored.
`try_get_object`	Gets a value as dict from the persistent store based on the given key and returns whether the value is stored.
`try_get_uint160`	Gets a value as UInt160 from the persistent store based on the given key and returns whether the value is stored.
`try_get_uint256`	Gets a value as UInt256 from the persistent store based on the given key and returns whether the value is stored.
`try_get_ecpoint`	Gets a value as ECPoint from the persistent store based on the given key and returns whether the value is stored.
`get_context`	Gets current storage context.
`get_read_only_context`	Gets current read only storage context.
`put`	Inserts a given bytes value in the key-value format into the persistent storage.
`put_int`	Inserts a given integer value in the key-value format into the persistent storage.
`put_bool`	Inserts a given boolean value in the key-value format into the persistent storage.
`put_str`	Inserts a given str value in the key-value format into the persistent storage.
`put_list`	Inserts a given list value in the key-value format into the persistent storage.
`put_dict`	Inserts a given dict value in the key-value format into the persistent storage.
`put_object`	Inserts a given object value in the key-value format into the persistent storage.
`put_uint160`	Inserts a given UInt160 value in the key-value format into the persistent storage.
`put_uint256`	Inserts a given UInt256 value in the key-value format into the persistent storage.
`put_ecpoint`	Inserts a given ECPoint value in the key-value format into the persistent storage.
`delete`	Removes a given key from the persistent storage if exists.
`find`	Searches in the storage for keys that start with the given prefix.

class StorageContext

Bases: object

The storage context used to read and write data in smart contracts.

Check out Neo’s Documentation to learn more about the StorageContext class.

Methods:

`create_map`	Creates a storage map with the given prefix.
`as_read_only`	Converts the specified storage context to a new readonly storage context.

create_map(prefix: bytes) → StorageMap

Creates a storage map with the given prefix.

Parameters:: prefix (bytes) – the identifier of the storage map
Returns:: a map with the key-values in the storage that match with the given prefix
Return type:: StorageMap

as_read_only() → Self

Converts the specified storage context to a new readonly storage context.

Returns:: current StorageContext as ReadOnly
Return type:: StorageContext

class StorageMap(context, prefix: bytes)

Bases: object

The key-value storage for the specific prefix in the given storage context.

Check out Neo’s Documentation to learn more about StorageMap.

Methods:

`get`	Gets a value from the map based on the given key.
`put`	Inserts a given value in the key-value format into the map.
`delete`	Removes a given key from the map if exists.

get(key: bytes) → bytes

Gets a value from the map based on the given key.

Parameters:: key (bytes) – value identifier in the store
Returns:: the value corresponding to given key for current storage context
Return type:: bytes

put(key: bytes, value: int | bytes | str)

Inserts a given value in the key-value format into the map.

Parameters:

key (bytes) – the identifier in the store for the new value
value (int or str or bytes) – value to be stored

delete(key: bytes)

Removes a given key from the map if exists.

Parameters:: key (bytes) – the identifier in the store for the new value

get(key: bytes, context: StorageContext = None) → bytes

Gets a value from the persistent store based on the given key.

>>> put(b'unit', b'test')
... get(b'unit')
b'test'

>>> get(b'fake_key')
b''

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

bytes

get_int(key: bytes, context: StorageContext = None) → int

Gets a value as integer from the persistent store based on the given key. It’s equivalent to boa3.sc.utils.to_int(get(key, context))

>>> put_int(b'unit', 5)
... get_int(b'unit')
5

>>> get_int(b'fake_key')
0

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

int

get_bool(key: bytes, context: StorageContext = None) → bool

Gets a value as boolean from the persistent store based on the given key. It’s equivalent to boa3.sc.utils.to_bool(get(key, context))

>>> put_bool(b'unit', True)
... get_bool(b'unit')
True

>>> get_bool(b'fake_key')
False

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

bool

get_str(key: bytes, context: StorageContext = None) → str

Gets a value as string from the persistent store based on the given key. It’s equivalent to boa3.sc.utils.to_str(get(key, context))

>>> put_str(b'unit', 'test')
... get_str(b'unit')
'test'

>>> get_str(b'fake_key')
''

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

str

get_list(key: bytes, context: StorageContext = None) → list

Gets a value as list from the persistent store based on the given key. It’s equivalent to boa3.sc.contracts.stdlib.StdLib.deserialize(get(key, context))

>>> put_list(b'unit', [1, 2, '3'])
... get_list(b'unit')
[1, 2, '3']

>>> get_list(b'fake_key')
[]

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

list

get_dict(key: bytes, context: StorageContext = None) → dict

Gets a value as dict from the persistent store based on the given key. It’s equivalent to boa3.sc.contracts.stdlib.StdLib.deserialize(get(key, context))

>>> put_dict(b'unit', {'example': 1, 'other_example': 2})
... get_dict(b'unit')
{'example': 1, 'other_example': 2}

>>> get_dict(b'fake_key')
{}

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

dict

get_object(key: bytes, context: StorageContext = None) → Any

Gets a value as object from the persistent store based on the given key. It’s equivalent to boa3.sc.contracts.stdlib.StdLib.deserialize(get(key, context)) Returns an empty struct if not found.

>>> example = SomeClass()
>>> put_object(b'unit', example)
... get_object(b'unit')
SomeClass

>>> get_object(b'fake_key')
object

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

Any

get_uint160(key: bytes, context: StorageContext = None) → UInt160

Gets a value as UInt160 from the persistent store based on the given key. It’s equivalent UInt160(get(key, context))

>>> put_uint160(b'unit', UInt160(b'0123456789ABCDEFGHIJ'))
... get_uint160(b'unit')
UInt160(0x4a49484746454443424139383736353433323130)

>>> get_uint160(b'fake_key')
UInt160(0x0000000000000000000000000000000000000000)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

boa3.sc.types.UInt160

get_uint256(key: bytes, context: StorageContext = None) → UInt256

Gets a value as UInt256 from the persistent store based on the given key. It’s equivalent UInt256(get(key, context))

>>> put_uint256(b'unit', UInt256(b'0123456789ABCDEFGHIJKLMNOPQRSTUV'))
... get_uint256(b'unit')
UInt256(0x565554535251504f4e4d4c4b4a49484746454443424139383736353433323130)

>>> get_uint160(b'fake_key')
UInt256(0x0000000000000000000000000000000000000000000000000000000000000000)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

boa3.sc.types.UInt256

get_ecpoint(key: bytes, context: StorageContext = None) → ECPoint

Gets a value as ECPoint from the persistent store based on the given key. It’s equivalent ECPoint(get(key, context))

>>> put_ecpoint(b'unit', ECPoint(b'0123456789ABCDEFGHIJKLMNOPQRSTUVW'))
... get_ecpoint(b'unit')
ECPoint(0x57565554535251504f4e4d4c4b4a49484746454443424139383736353433323130)

>>> get_ecpoint(b'fake_key')
ECPoint(0x000000000000000000000000000000000000000000000000000000000000000000)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context

Return type:

boa3.sc.types.ECPoint

try_get(key: bytes, context: StorageContext = None) → tuple[bytes, bool]

Gets a value from the persistent store based on the given key and returns whether the value is stored.

>>> put(b'unit', b'test')
... try_get(b'unit')
(b'test', True)

>>> try_get(b'fake_key')
(b'', False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[bytes, bool]

try_get_int(key: bytes, context: StorageContext = None) → tuple[int, bool]

Gets a value as integer from the persistent store based on the given key and returns whether the value is stored.

>>> put_int(b'unit', 5)
... try_get_int(b'unit')
(5, True)

>>> try_get_int(b'fake_key')
(0, False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[int, bool]

try_get_bool(key: bytes, context: StorageContext = None) → tuple[bool, bool]

Gets a value as boolean from the persistent store based on the given key and returns whether the value is stored.

>>> put_bool(b'unit', False)
... try_get_bool(b'unit')
(False, True)

>>> try_get_bool(b'fake_key')
(False, False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[bool, bool]

try_get_str(key: bytes, context: StorageContext = None) → tuple[str, bool]

Gets a value as string from the persistent store based on the given key and returns whether the value is stored.

>>> put_str(b'unit', 'test')
... try_get_str(b'unit')
('test', True)

>>> try_get_str(b'fake_key')
('', False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[str, bool]

try_get_list(key: bytes, context: StorageContext = None) → tuple[list, bool]

Gets a value as list from the persistent store based on the given key and returns whether the value is stored.

>>> put_list(b'unit', [1, 2, '3'])
... try_get_list(b'unit')
([1, 2, '3'], True)

>>> get_list(b'fake_key')
([], False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[list, bool]

try_get_dict(key: bytes, context: StorageContext = None) → tuple[dict, bool]

Gets a value as dict from the persistent store based on the given key and returns whether the value is stored.

>>> put_dict(b'unit', {'example': 1, 'other_example': 2})
... get_dict(b'unit')
({'example': 1, 'other_example': 2}, True)

>>> get_dict(b'fake_key')
({}, False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[dict, bool]

try_get_object(key: bytes, context: StorageContext = None) → tuple[Any, bool]

Gets a value as dict from the persistent store based on the given key and returns whether the value is stored.

>>> example = SomeClass()
>>> put_object(b'unit', example)
... try_get_object(b'unit')
(SomeClass, True)

>>> get_object(b'fake_key')
(object, False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[Any, bool]

try_get_uint160(key: bytes, context: StorageContext = None) → tuple[UInt160, bool]

Gets a value as UInt160 from the persistent store based on the given key and returns whether the value is stored.

>>> put_uint160(b'unit', UInt160(b'0123456789ABCDEFGHIJ'))
... try_get_uint160(b'unit')
(UInt160(0x4a49484746454443424139383736353433323130), True)

>>> get_uint160(b'fake_key')
(UInt160(0x0000000000000000000000000000000000000000), False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[boa3.sc.types.UInt160, bool]

try_get_uint256(key: bytes, context: StorageContext = None) → tuple[UInt256, bool]

Gets a value as UInt256 from the persistent store based on the given key and returns whether the value is stored.

>>> put_uint256(b'unit', UInt256(b'0123456789ABCDEFGHIJKLMNOPQRSTUV'))
... get_uint256(b'unit')
(UInt256(0x565554535251504f4e4d4c4b4a49484746454443424139383736353433323130), True)

>>> get_uint160(b'fake_key')
(UInt256(0x0000000000000000000000000000000000000000000000000000000000000000), False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[boa3.sc.types.UInt256, bool]

try_get_ecpoint(key: bytes, context: StorageContext = None) → tuple[ECPoint, bool]

Gets a value as ECPoint from the persistent store based on the given key and returns whether the value is stored.

>>> put_ecpoint(b'unit', ECPoint(b'0123456789ABCDEFGHIJKLMNOPQRSTUVW'))
... try_get_ecpoint(b'unit')
(ECPoint(0x57565554535251504f4e4d4c4b4a49484746454443424139383736353433323130), True)

>>> try_get_ecpoint(b'fake_key')
(ECPoint(0x000000000000000000000000000000000000000000000000000000000000000000), False)

Parameters:

key (bytes) – value identifier in the store
context (StorageContext) – storage context to be used

Returns:

the value corresponding to given key for current storage context and whether it was actually stored

Return type:

tuple[boa3.sc.types.ECPoint, bool]

get_context() → StorageContext

Gets current storage context.

>>> get_context()       # StorageContext cannot be read outside the blockchain
_InteropInterface

Returns:: the current storage context
Return type:: StorageContext

get_read_only_context() → StorageContext

Gets current read only storage context.

>>> get_context()       # StorageContext cannot be read outside the blockchain
_InteropInterface

Returns:: the current read only storage context
Return type:: StorageContext

put(key: bytes, value: bytes, context: StorageContext = None)

Inserts a given bytes value in the key-value format into the persistent storage.

>>> put(b'unit', b'test')
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (bytes) – value to be stored
context (StorageContext) – storage context to be used

put_int(key: bytes, value: int, context: StorageContext = None)

Inserts a given integer value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.utils.to_int(value), context)

>>> put_int(b'unit', 5)
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (int) – value to be stored
context (StorageContext) – storage context to be used

put_bool(key: bytes, value: bool, context: StorageContext = None)

Inserts a given boolean value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.utils.to_bool(value), context)

>>> put_bool(b'unit', True)
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (bool) – value to be stored
context (StorageContext) – storage context to be used

put_str(key: bytes, value: str, context: StorageContext = None)

Inserts a given str value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.utils.to_str(value), context)

>>> put_str(b'unit', 'test')
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (str) – value to be stored
context (StorageContext) – storage context to be used

put_list(key: bytes, value: list, context: StorageContext = None)

Inserts a given list value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.contracts.stdlib.StdLib.serialize(value), context)

>>> put_list(b'unit', [1, 2, '3'])
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (list) – value to be stored
context (StorageContext) – storage context to be used

put_dict(key: bytes, value: dict, context: StorageContext = None)

Inserts a given dict value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.contracts.stdlib.StdLib.serialize(value), context)

>>> put_dict(b'unit', {'example': 1, 'other_example': 2})
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (dict) – value to be stored
context (StorageContext) – storage context to be used

put_object(key: bytes, value: object, context: StorageContext = None)

Inserts a given object value in the key-value format into the persistent storage. It’s equivalent to put(key, boa3.sc.contracts.stdlib.StdLib.serialize(value), context)

>>> example = SomeClass()
>>> put_object(b'unit', example)
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (dict) – value to be stored
context (StorageContext) – storage context to be used

put_uint160(key: bytes, value: UInt160, context: StorageContext = None)

Inserts a given UInt160 value in the key-value format into the persistent storage. It’s equivalent to put(key, value, context) since UInt160 is a subclass of bytes

>>> put_uint160(b'unit', UInt160(b'0123456789ABCDEFGHIJ'))
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (boa3.sc.types.UInt160) – value to be stored
context (StorageContext) – storage context to be used

put_uint256(key: bytes, value: UInt256, context: StorageContext = None)

Inserts a given UInt256 value in the key-value format into the persistent storage. It’s equivalent to put(key, value, context) since UInt256 is a subclass of bytes

>>> put_uint256(b'unit', UInt256(b'0123456789ABCDEFGHIJKLMNOPQRSTUV'))
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (boa3.sc.types.UInt256) – value to be stored
context (StorageContext) – storage context to be used

put_ecpoint(key: bytes, value: ECPoint, context: StorageContext = None)

Inserts a given ECPoint value in the key-value format into the persistent storage. It’s equivalent to put(key, value, context) since ECPoint is a subclass of bytes

>>> put_ecpoint(b'unit', ECPoint(b'0123456789ABCDEFGHIJKLMNOPQRSTUVW'))
None

Parameters:

key (bytes) – the identifier in the store for the new value
value (boa3.sc.types.ECPoint) – value to be stored
context (StorageContext) – storage context to be used

delete(key: bytes, context: StorageContext = None)

Removes a given key from the persistent storage if exists.

>>> put(b'unit', 'test')
... delete()
... get(b'unit')
''

Parameters:

key (bytes) – the identifier in the store for the new value
context (StorageContext) – storage context to be used

find(prefix: bytes, context: StorageContext = None, options: FindOptions = FindOptions.NONE) → Iterator

Searches in the storage for keys that start with the given prefix.

>>> put(b'a1', 'one')
... put(b'a2', 'two')
... put(b'a3', 'three')
... put(b'b4', 'four')
... findIterator = find(b'a')
... findResults = []
... while findIterator.next():
...     findResults.append(findIterator.value)
... findResults
['one', 'two', 'three']

Parameters:

prefix (bytes) – prefix to find the storage keys
context (StorageContext) – storage context to be used
options (boa3.sc.types.FindOptions) – the options of the search

Returns:

an iterator with the search results

Return type:

Iterator