Perp DEX vault account API

Adapter protocol and reproducible capability declarations for perp vaults.

class PerpDexCapability

Bases: object

Protocol facts needed by generic storage and price joining.

The capability is data, not a protocol-specific cleaning branch. It is embedded in Parquet metadata to make re-cleaning deterministic.

__init__(protocol_slug, deployment_slug, quote_asset, public_positions, position_data_status, collection_cadence_seconds, maximum_position_valuation_skew_seconds)
Parameters

  • protocol_slug (str) –

  • deployment_slug (str) –

  • quote_asset (str) –

  • public_positions (bool) –

  • position_data_status (str) –

  • collection_cadence_seconds (int) –

  • maximum_position_valuation_skew_seconds (int) –

Return type

None

class PerpDexCapabilityRegistry

Bases: object

Canonical immutable set of capabilities used for one raw data artefact.

to_json()

Return deterministic JSON suitable for Parquet schema metadata.

Returns

Canonical compact JSON sorted by protocol and deployment.

Return type

str

sha256()

Return the deterministic registry JSON digest.

Returns

Lower-case hexadecimal SHA-256 digest.

Return type

str

__init__(capabilities, schema_version=1)
Parameters
Return type

None

embed_perp_capability_registry(schema, registry)

Add the canonical registry and its integrity hash to Parquet metadata.

Parameters
Returns

Schema with preserved and extended metadata.

Return type

pyarrow.lib.Schema

load_perp_capability_registry(schema)

Read and verify the embedded capability registry from Parquet metadata.

Parameters

schema (pyarrow.lib.Schema) – Raw or cleaned Parquet schema.

Returns

Verified capability registry.

Raises

ValueError – If metadata is absent, malformed or has an invalid hash.

Return type

eth_defi.perp_dex.adapter.PerpDexCapabilityRegistry

Protocol-independent perpetual DEX vault observations and calculations.

Adapters preserve one account observation and one signed notional for every non-zero open position. Long/short, gross/net and concentration are derived from those fundamental values and are never written to the source tables.

class SourcePositionDataStatus

Bases: enum.StrEnum

Availability states emitted directly by a protocol adapter.

__new__(value)
capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count()

Return the number of non-overlapping occurrences of substring sub in string S[start:end].

Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith()

Return True if the string ends with the specified suffix, False otherwise.

suffix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

format(*args, **kwargs)

Return a formatted version of the string, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping, /)

Return a formatted version of the string, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if all characters in the string are printable, False otherwise.

A character is printable if repr() may use it in its output.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, /, count=- 1)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

rindex()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith()

Return True if the string starts with the specified prefix, False otherwise.

prefix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class PerpParquetDataStatus

Bases: enum.StrEnum

Availability states materialised in the raw and cleaned price Parquet.

__new__(value)
capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count()

Return the number of non-overlapping occurrences of substring sub in string S[start:end].

Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith()

Return True if the string ends with the specified suffix, False otherwise.

suffix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

format(*args, **kwargs)

Return a formatted version of the string, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping, /)

Return a formatted version of the string, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if all characters in the string are printable, False otherwise.

A character is printable if repr() may use it in its output.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, /, count=- 1)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

rindex()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith()

Return True if the string starts with the specified prefix, False otherwise.

prefix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class PositionValuationBasis

Bases: enum.StrEnum

The source used to calculate a position’s current quote notional.

__new__(value)
capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count()

Return the number of non-overlapping occurrences of substring sub in string S[start:end].

Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith()

Return True if the string ends with the specified suffix, False otherwise.

suffix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

format(*args, **kwargs)

Return a formatted version of the string, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping, /)

Return a formatted version of the string, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if all characters in the string are printable, False otherwise.

A character is printable if repr() may use it in its output.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, /, count=- 1)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

rindex()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith()

Return True if the string starts with the specified prefix, False otherwise.

prefix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class PerpVaultIdentity

Bases: object

Stable identity shared by a native vault scanner and price exporter.

dataset_chain_id and dataset_address are the exact keys used in the vault price Parquet, including synthetic non-EVM chain and address values.

__init__(protocol_slug, deployment_slug, vault_id, dataset_chain_id, dataset_address)
Parameters

  • protocol_slug (str) –

  • deployment_slug (str) –

  • vault_id (str) –

  • dataset_chain_id (int) –

  • dataset_address (str) –

Return type

None

class PerpVaultAccountObservation

Bases: object

One immutable account observation and its position-set availability.

A unique snapshot_id identifies the write, while corrections are selected by identity and position_effective_at. total_equity is optional audit information and never gates valid position collection.

__init__(identity, snapshot_id, observed_at, written_at, position_effective_at, equity_effective_at, total_equity, quote_asset, position_data_status, position_data_reason, position_set_complete, source_endpoint, collector_version, raw_payload_reference=None)
Parameters
Return type

None

class PerpVaultPositionObservation

Bases: object

One non-zero open position valued in the account quote asset.

__init__(snapshot_id, source_market_id, signed_notional, quote_asset, valuation_basis, valuation_observed_at, source_endpoint)
Parameters
Return type

None

class PerpVaultObservationBundle

Bases: object

One account observation and its complete current position set.

__init__(account, positions)
Parameters
Return type

None

class DerivedPerpVaultExposure

Bases: object

Materialised exposure values calculated from one validated bundle.

__init__(long_notional, short_notional, open_position_count, largest_position_notional)
Parameters
Return type

None

create_unavailable_perp_vault_observation_bundle(identity, observed_at, total_equity, quote_asset, status, reason, source_endpoint, collector_version='1')

Create an explicit account-only source observation with no positions.

Account-only APIs still need a source availability state so downstream users see null exposure rather than an invented empty portfolio.

Parameters
Returns

Bundle with no position rows.

Return type

eth_defi.perp_dex.metrics.PerpVaultObservationBundle

validate_perp_vault_observation_bundle(bundle)

Validate source facts before an observation bundle reaches DuckDB.

Available observations must contain a complete response and a unique, non-zero, quote-consistent position set. Unavailable source states cannot carry positions, which prevents privacy or authentication gaps becoming a false empty portfolio.

Parameters

bundle (eth_defi.perp_dex.metrics.PerpVaultObservationBundle) – Account observation and its protocol-normalised positions.

Returns

None. Raises ValueError for invalid source facts.

Return type

None

derive_perp_vault_exposure(bundle)

Calculate the materialised exposure basis values for one bundle.

The returned values are null for unavailable/incomplete source data and zero for a validated available account with no open positions. Gross, net and concentration remain derived consumer values.

Parameters

bundle (eth_defi.perp_dex.metrics.PerpVaultObservationBundle) – Previously validated account and position observations.

Returns

Long, short, count and largest absolute current notional.

Return type

eth_defi.perp_dex.metrics.DerivedPerpVaultExposure

DuckDB persistence for protocol-independent perp vault observations.

initialise_perp_vault_observation_schema(connection)

Create common append-only observation tables in a protocol’s DuckDB file.

The caller owns the database and transaction boundary; no central database is created. The source-status constraint intentionally excludes pipeline statuses such as stale and not_collected.

Parameters

connection (_duckdb.DuckDBPyConnection) – Open DuckDB connection from the protocol’s metrics database.

Returns

None.

Return type

None

canonicalise_perp_source_payload(payload)

Serialise a trimmed source payload deterministically and hash it.

Parameters

payload (collections.abc.Mapping[str, Any]) – Whitelisted protocol-native source inputs used for one bundle.

Returns

(sha256_hex, canonical_json).

Return type

tuple[str, str]

write_perp_vault_observation_bundle(connection, bundle, payload, payload_schema_version=1)

Atomically store one validated observation bundle and its payload.

The immutable snapshot ID makes corrections append-only. A payload is content-addressed and deduplicated before its account row references it.

Parameters
Returns

SHA-256 payload reference written to the account observation.

Return type

str

read_perp_vault_observations(connection)

Read account and position observations in derivation-ready order.

Parameters

connection (_duckdb.DuckDBPyConnection) – Open protocol-owned DuckDB connection.

Returns

Account and position DataFrames.

Return type

tuple[pandas.DataFrame, pandas.DataFrame]

Shared materialised perpetual-vault metrics in the price Parquet pipeline.

PERP_METRICS_MAX_FORWARD_ALIGNMENT = datetime.timedelta(days=2)

Allow a newly collected account observation to attach to the latest native price row when a daily or otherwise delayed price source has not emitted a row at the collection time yet. Lighter’s daily feed can remain at the previous UTC midnight until the following day, requiring a 48-hour bound. The original observation timestamp is retained, and only the latest row for an account can receive this alignment.

PERP_DEX_NATIVE_CHAIN_IDS = frozenset({325, 9994, 9995, 9997, 9998, 9999})

Native chains whose price rows represent perpetual DEX vault accounts. This is used only for the generic not_collected default; adapters own real source observations and availability states.

ensure_perp_metric_columns(frame)

Add typed-null-compatible common perp columns to a price DataFrame.

Parameters

frame (pandas.DataFrame) – Raw or cleaned price rows.

Returns

Same frame with all seven common columns present.

Return type

pandas.DataFrame

normalise_perp_metric_parquet_dtypes(frame)

Normalise all materialised perp fields to their Arrow contract.

Observation timestamps are deliberately truncated to whole seconds. Account-level exposure does not need sub-second precision, while a stable second-resolution contract avoids leaking collector clock precision into Parquet schema inference.

Parameters

frame (pandas.DataFrame) – DataFrame containing all common perp columns.

Returns

DataFrame with nullable integer count and second-resolution timestamps.

Return type

pandas.DataFrame

select_perp_observation_corrections(accounts, positions)

Select one immutable bundle for every identity/effective-time correction set.

The latest write wins; a same-write tie uses PEP 440 collector version. Equal-rank conflicting bundles fail hard instead of combining stale and corrected position rows.

Parameters

  • accounts (pandas.DataFrame) – Account observation rows read from common DuckDB storage.

  • positions (pandas.DataFrame) – Position observation rows read from common DuckDB storage.

Returns

Selected account rows only.

Return type

pandas.DataFrame

derive_perp_vault_metric_snapshots(accounts, positions)

Derive one materialised exposure row per selected account observation.

The account table drives the calculation, so a complete available account with zero position rows produces zero values rather than disappearing.

Parameters
Returns

DataFrame ready for the generic price as-of join.

Return type

pandas.DataFrame

align_latest_perp_metrics_to_price_rows(price_rows, snapshots, maximum_forward_alignment)

Overlay a newer account observation on only the latest native price row.

Some native price feeds, notably Lighter’s daily history, timestamp the current price row at UTC midnight even though the account observation is collected later that day. For each account this helper overlays only the newest eligible snapshot on the latest price row. Older price history cannot receive the newer observation, and perp_metrics_observed_at always retains the real measurement time.

Parameters

  • price_rows (pandas.DataFrame) – Result of the ordinary backward as-of join, containing one or more rows per (chain, address) and all common metric columns.

  • snapshots (pandas.DataFrame) – Unique, correction-selected metric snapshots. Each row contains chain, address, position_effective_at and all common metric columns.

  • maximum_forward_alignment (datetime.timedelta) – Maximum permitted distance from the latest price row to the newer observation.

Returns

Price-row copy with eligible latest rows overlaid.

Return type

pandas.DataFrame

attach_perp_metrics_to_price_rows(price_rows, snapshots, maximum_forward_alignment=datetime.timedelta(days=2))

Join snapshots to native price rows and align the latest delayed feed.

Inputs are sorted deterministically for merge_asof and restored to the original price order afterwards. A bounded post-join overlay makes the newest account observation available on the newest daily/delayed price row without changing source timestamps or leaking it into older rows. The finalisation helper remains the sole owner of stale/default-status policy.

Parameters

  • price_rows (pandas.DataFrame) – Native raw price DataFrame containing chain, address and timestamp.

  • snapshots (pandas.DataFrame) – Metric snapshots from one or more protocol DuckDB files.

  • maximum_forward_alignment (datetime.timedelta) – Maximum distance for aligning a newer observation to the latest price row for the same account.

Returns

Price rows with the seven materialised metrics attached.

Return type

pandas.DataFrame

build_registered_perp_vault_index(frame)

Build the unique native perp account index from price rows.

This helper keeps account registration vectorised and centralises the lower-case comparison key without altering stored address values.

Parameters

frame (pandas.DataFrame) – Price rows containing chain and address.

Returns

Unique (chain, lower-case address) index for native perp rows.

Return type

pandas.MultiIndex

finalise_perp_metric_columns(frame, registered_perp_vaults, maximum_age=datetime.timedelta(seconds=21600))

Apply the single default and freshness policy for perp metric columns.

Staleness is calculated from each price row’s timestamp minus the observed position time. Static unavailable states never turn stale. Numeric values remain attached when stale: the status and original observation timestamp give consumers the age needed to accept or reject the measurement.

Parameters
Returns

Finalised common metric columns.

Return type

pandas.DataFrame

Final JSON export helpers for generic perpetual DEX vault metrics.

build_perp_dex_other_data(row)

Build other_data.perp_dex from one already-cleaned price row.

No protocol API or DuckDB lookup occurs here. Gross, net and concentration are derived from the four materialised price fields.

Parameters

row (collections.abc.Mapping[str, Any]) – Latest cleaned price-row mapping.

Returns

Additive JSON object, or None for a non-perp vault.

Raises

ValueError – If an available or stale measurement has lost its observation timestamp.

Return type

Optional[dict[str, Any]]