IUserStore

Title: IUserStore

Interface for the per-user generic key/value store with per-key history.

Each user may claim at most one UserStore from StoreFactory. The store is bound to its claimer forever: _owner is set once at initialize and only that address may write. Each setValue snapshots the prior non-empty value into a per-key history list with a timestamp; current and history are both readable by anyone, paginated.

Note: security-contact: admin@parity.io

Functions

initialize

Initialises the store, binding it permanently to user_.

Callable exactly once via Initializable. user_ must be non-zero, otherwise

Note: reverts: InvalidUser.

function initialize(address user_) external;

Parameters

Name	Type	Description
`user_`	`address`	The user this store is bound to forever.

setValue

Sets the current value for key.

Callable only by the bound owner; any other caller @custom:reverts NotOwner. key must be non-zero, otherwise @custom:reverts InvalidKey. If a non-empty prior value existed it is pushed into the per-key history list with block.timestamp; empty prior values produce no history entry. Emits

Note: emits: ValueSet on every successful write.

function setValue(bytes32 key, bytes calldata value) external;

Parameters

Name	Type	Description
`key`	`bytes32`	The key to write.
`value`	`bytes`	The new current value (may be empty).

getValue

Returns the current value under key, or empty bytes if unset.

function getValue(bytes32 key) external view returns (bytes memory value);

Parameters

Name	Type	Description
`key`	`bytes32`	The key to read.

Returns

Name	Type	Description
`value`	`bytes`	The current value.

hasValue

Returns true iff the current value under key has non-zero length.

function hasValue(bytes32 key) external view returns (bool present);

Parameters

Name	Type	Description
`key`	`bytes32`	The key to check.

Returns

Name	Type	Description
`present`	`bool`	True iff `getValue(key).length != 0`.

getHistoryCount

Returns the number of prior (historical) values recorded for key.

function getHistoryCount(bytes32 key) external view returns (uint256 count);

Parameters

Name	Type	Description
`key`	`bytes32`	The key to read.

Returns

Name	Type	Description
`count`	`uint256`	Length of the history list.

getHistoryAt

Returns the historical entry at index for key.

function getHistoryAt(bytes32 key, uint256 index) external view returns (Entry memory entry);

Parameters

Name	Type	Description
`key`	`bytes32`	The key to read.
`index`	`uint256`	Zero-based index into the history list.

Returns

Name	Type	Description
`entry`	`Entry`	The `(value, timestamp)` pair.

getHistory

Paginated read over the per-key history list.

offset >= getHistoryCount(key) returns an empty array. Length is min(limit, getHistoryCount(key) - offset).

function getHistory(
    bytes32 key,
    uint256 offset,
    uint256 limit
)
    external
    view
    returns (Entry[] memory entries);

Parameters

Name	Type	Description
`key`	`bytes32`	The key to read.
`offset`	`uint256`	Start index.
`limit`	`uint256`	Maximum entries to return.

Returns

Name	Type	Description
`entries`	`Entry[]`	Slice of history entries.

getKeyCount

Returns the number of distinct keys ever written.

function getKeyCount() external view returns (uint256 count);

Returns

Name	Type	Description
`count`	`uint256`	Length of the key-insertion list.

getKeyAt

Returns the key at the given insertion-order index.

function getKeyAt(uint256 index) external view returns (bytes32 key);

Parameters

Name	Type	Description
`index`	`uint256`	Zero-based index into the key list.

Returns

Name	Type	Description
`key`	`bytes32`	The key at `index`.

getKeys

Paginated read over the insertion-order key list.

offset >= getKeyCount() returns an empty array. Length is min(limit, getKeyCount() - offset).

function getKeys(uint256 offset, uint256 limit) external view returns (bytes32[] memory keys);

Parameters

Name	Type	Description
`offset`	`uint256`	Start index.
`limit`	`uint256`	Maximum entries to return.

Returns

Name	Type	Description
`keys`	`bytes32[]`	Slice of keys.

Events

ValueSet

Emitted when the owner sets (or updates) a value under key.

event ValueSet(address indexed owner, bytes32 indexed key, bytes value);

Parameters

Name	Type	Description
`owner`	`address`	The user this store is bound to.
`key`	`bytes32`	The key being written.
`value`	`bytes`	The new current value.

Errors

NotOwner

Thrown when any caller other than the bound owner attempts a write.

error NotOwner(address caller);

Parameters

Name	Type	Description
`caller`	`address`	The unauthorised msg.sender.

InvalidUser

Thrown when initialize is called with a zero user address.

error InvalidUser(address user);

Parameters

Name	Type	Description
`user`	`address`	The invalid user argument.

InvalidKey

Thrown when setValue is called with a zero key.

error InvalidKey();

Structs

Entry

A historical (prior) value for a key and the block timestamp at which it was snapshotted. @param value The prior value that was just superseded.

struct Entry {
    bytes value;
    uint256 timestamp;
}

Properties

Name	Type	Description
`value`	`bytes`
`timestamp`	`uint256`	Block timestamp at the moment of supersession.