tokenised_fund.spiko.vault

Documentation for eth_defi.tokenised_fund.spiko.vault Python module.

Spiko permissioned tokenised-fund adapter.

Spiko fund shares are permissioned ERC-20 tokens, not ERC-4626 vaults. The issuer’s verified Oracle contract publishes NAV/share using the Chainlink AggregatorV3 interface. Combining that NAV with ERC-20 supply gives a safe read-only estimate of the tokenised fund’s total NAV.

See https://tech.spiko.io/posts/spiko-smart-contracts/ and https://github.com/spiko-tech/contracts/blob/main/contracts/oracle/Oracle.sol.

Module Attributes

`SPIKO_PERMISSIONED_FLOW_REASON`	Public flows must not be advertised for Spiko's permissioned lifecycle.
`USTBL_MANAGEMENT_FEE`	Backwards-compatible USTBL fee constant exported by this adapter module.

Functions

`export_spiko_denomination`(chain_id, symbol)	Export a non-transferable currency-denomination record.
`export_spiko_usd_denomination`(chain_id)	Export USTBL's legacy USD accounting-denomination record.

Classes

`SpikoVault`	Read-only adapter for reviewed Spiko tokenised-fund shares.
`SpikoVaultInfo`	Spiko product metadata exported to vault scan consumers.

SPIKO_PERMISSIONED_FLOW_REASON = 'Spiko subscriptions, transfers and redemptions require eligibility checks and issuer-operated daily servicing': Public flows must not be advertised for Spiko’s permissioned lifecycle.

USTBL_MANAGEMENT_FEE = 0.0025: Backwards-compatible USTBL fee constant exported by this adapter module.

class SpikoVaultInfo

Bases: eth_defi.vault.base.VaultInfo

Spiko product metadata exported to vault scan consumers.

__init__(*args, **kwargs)

__new__(**kwargs)

clear(): Remove all items from the dict.

copy(): Return a shallow copy of the dict.

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items(): Return a set-like object providing a view on the dict’s items.

keys(): Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values(): Return an object providing a view on the dict’s values.

export_spiko_denomination(chain_id, symbol)

Export a non-transferable currency-denomination record.

Spiko fund subscriptions can settle through issuer-operated routes, but the fund-token contract does not expose an ERC-4626 asset token. This accounting-only record makes the issuer NAV currency explicit without advertising a public ERC-20 dealing route.

Parameters

chain_id (int) – EVM chain id of the Spiko product.
symbol (str) – ISO currency symbol used by the issuer NAV oracle.

Returns

Token-like non-transferable currency metadata.

Return type

dict[str, object]

export_spiko_usd_denomination(chain_id)

Export USTBL’s legacy USD accounting-denomination record.

Parameters: chain_id (int) – EVM chain id of the USTBL deployment.
Returns: Token-like USD metadata without an ERC-20 address.
Return type: dict[str, object]

class SpikoVault

Bases: eth_defi.tokenised_fund.vault.TokenisedFundVault

Read-only adapter for reviewed Spiko tokenised-fund shares.

The adapter calculates NAV from ERC-20 supply and the official issuer Oracle. It cannot perform investor dealing: transfers and servicing are controlled by Spiko’s permission manager and redemption workflow.

Create a verified Spiko product adapter.

Parameters

web3 – Web3 connection to the product’s EVM chain.
spec – Chain and reviewed Spiko share-token identifier.
token_cache – Optional ERC-20 metadata cache.
features – Classification flags supplied by the shared factory.
default_block_identifier – Accepted for factory compatibility.
require_denomination_token – Accepted for VaultBase compatibility.

Raises

ValueError – If the requested product has not been reviewed.

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)

Create a verified Spiko product adapter.

Parameters

web3 (web3.main.Web3) – Web3 connection to the product’s EVM chain.
spec (eth_defi.vault.base.VaultSpec) – Chain and reviewed Spiko share-token identifier.
token_cache (Optional[dict]) – Optional ERC-20 metadata cache.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Classification flags supplied by the shared factory.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Accepted for factory compatibility.
require_denomination_token (bool) – Accepted for VaultBase compatibility.

Raises

ValueError – If the requested product has not been reviewed.

first_seen_at_block: int | None

Block number hint when this vault was deployed.

Must be set externally, as because of shitty Ethereum RPC we cannot query this. Allows us to avoid unnecessary work when scanning historical price data.

property chain_id: int

Return the reviewed Spiko deployment chain id.

Returns: EVM chain id of this product.

property address: eth_typing.evm.HexAddress

Return the Spiko share-token address.

Returns: Checksummed ERC-20 address.

property vault_address: eth_typing.evm.HexAddress

Return the shared scanner vault identifier.

Returns: Spiko share-token address.

property price_oracle_contract: web3.contract.contract.Contract

Return Spiko’s verified Chainlink-compatible NAV oracle.

Returns: Oracle contract instance.

property usd_price_oracle_contract: Optional[web3.contract.contract.Contract]

Return the optional issuer-currency to USD oracle.

Returns: Chainlink-compatible FX oracle for non-USD products, if reviewed.

property oracle_decimals: int

Read the NAV oracle decimal scale.

Returns: Number of oracle decimal places.

property usd_price_oracle_decimals: Optional[int]

Read the USD FX oracle decimal scale when configured.

Returns: FX oracle decimal places, or None for USD-native products.

property name: str

Return the onchain share-token name.

Returns: ERC-20 token name.

property symbol: str

Return the onchain share-token symbol.

Returns: ERC-20 token symbol.

property description: str

Return the public fund description.

Returns: Product-specific investment strategy description.

property short_description: str

Return a concise public listing description.

Returns: Product-specific strategy summary.

property manager_name: str

Return the protocol-operated curator identity.

Returns: Spiko.

fetch_share_token_address(block_identifier='latest')

Return the Spiko share-token address.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for shared scanner compatibility.
Returns: Spiko ERC-20 share-token address.
Return type: eth_typing.evm.HexAddress

fetch_share_token()

Fetch Spiko ERC-20 token details.

Returns: Share-token metadata and conversion methods.
Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Return no surrogate ERC-20 denomination token.

Returns: Always None because no single public ERC-20 asset exists.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Return no onchain denomination-token metadata.

Returns: Always None because Spiko’s issuer NAV currency is not a public ERC-20 subscription asset.
Return type: Optional[eth_defi.token.TokenDetails]

convert_raw_share_price(raw_price)

Convert oracle units to the issuer’s NAV currency per token.

Parameters: raw_price (int) – Raw Chainlink-compatible oracle answer.
Returns: Human-readable NAV/share in the product denomination.
Return type: decimal.Decimal

convert_raw_usd_exchange_rate(raw_price)

Convert FX-oracle units to USD per issuer currency unit.

Parameters: raw_price (int) – Raw answer from the reviewed Chainlink FX oracle.
Returns: USD per one source-denomination unit.
Return type: decimal.Decimal

convert_source_share_price_to_usd(source_share_price, usd_exchange_rate=None, block_identifier='latest')

Convert an issuer NAV/share to the shared USD denomination.

Parameters

source_share_price (decimal.Decimal) – NAV/share in Spiko’s published source currency.
usd_exchange_rate (Optional[decimal.Decimal]) – Optional USD per source-currency unit. When omitted, read the reviewed FX oracle at block_identifier.
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – EVM block tag for the optional FX oracle read.

Returns

USD-normalised NAV/share.

Return type

decimal.Decimal

fetch_share_price(block_identifier='latest')

Read the official NAV/share.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – EVM block tag or historical block number.
Returns: NAV/share in USD accounting units.
Raises: ValueError – If the oracle returns no valid NAV observation.
Return type: decimal.Decimal

fetch_total_supply(block_identifier='latest')

Read the outstanding share supply.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – EVM block tag or historical block number.
Returns: Human-readable outstanding shares.
Return type: decimal.Decimal

fetch_total_assets(block_identifier='latest')

Calculate estimated fund NAV from supply and issuer NAV/share.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – EVM block tag or historical block number.
Returns: Estimated total fund NAV in USD accounting units.
Return type: decimal.Decimal

fetch_nav(block_identifier='latest')

Read the tokenised fund’s total NAV.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – EVM block tag or historical block number.
Returns: Estimated total fund NAV in USD accounting units.
Return type: decimal.Decimal

fetch_info()

Export verified Spiko integration metadata.

Returns: Token, oracle, denomination and NAV-source identifiers.
Return type: eth_defi.tokenised_fund.spiko.vault.SpikoVaultInfo

fetch_scan_record_extra_data()

Expose valuation and restricted-flow diagnostics.

Returns: Product-specific scanner metadata.
Return type: dict[str, object]

fetch_portfolio(universe, block_identifier=None)

Return no directly observable underlying portfolio.

Parameters

universe (eth_defi.vault.base.TradingUniverse) – Ignored because holdings are offchain.
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Ignored because holdings are offchain.

Returns

Empty spot portfolio.

Return type

eth_defi.vault.base.VaultPortfolio

has_block_range_event_support()

Report unsupported generic flow-event accounting.

Returns: False because servicing is issuer-operated.
Return type: bool

has_deposit_distribution_to_all_positions()

Report unavailable onchain portfolio distribution.

Returns: False.
Return type: bool

get_flow_manager()

Reject unsupported generic flow accounting.

Raises: NotImplementedError – Always, as Spiko servicing is bespoke.
Return type: eth_defi.vault.base.VaultFlowManager

fetch_deposit_closed_reason()

Explain unavailable generic subscriptions.

Returns: Eligibility and issuer-servicing explanation.
Return type: str

fetch_redemption_closed_reason()

Explain unavailable generic redemptions.

Returns: Eligibility and issuer-servicing explanation.
Return type: str

get_historical_reader(stateful)

Construct the supply and NAV historical reader.

Parameters: stateful (bool) – Whether to retain shared adaptive reader state.
Returns: Spiko historical reader.
Return type: eth_defi.vault.base.VaultHistoricalReader

get_management_fee(block_identifier)

Return the published annual management fee.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for shared fee API compatibility.
Returns: Annual management fee as a fraction.
Return type: Optional[float]

get_performance_fee(block_identifier)

Return no separately published performance fee.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for shared fee API compatibility.
Returns: None.
Return type: Optional[float]

get_fee_data()

Return published Spiko fee metadata.

Returns: Management fee with no inferred dealing fees.
Return type: eth_defi.vault.fee.FeeData

get_link(referral=None)

Return the official Spiko product page.

Parameters: referral (Optional[str]) – Ignored because Spiko does not provide referral URLs.
Returns: Official product page.
Return type: str

property denomination_token: Optional[eth_defi.token.TokenDetails]

Get the token which denominates the vault valuation

Used in deposits and redemptions
Used in NAV calculation
Used in profit benchmarks
Usually USDC

Returns

Token wrapper instance.

Maybe None for broken vaults like https://arbiscan.io/address/0x9d0fbc852deccb7dcdd6cb224fa7561efda74411#code

Note

None results are not cached — the next access will retry the on-chain call. This avoids permanently caching a transient RPC failure.

property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager: Deposit manager assocaited with this vault

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Note: maxRedeem(address(0)) does NOT work as a proxy for available liquidity because it requires a specific address that has already deposited shares. For address(0), balanceOf is always 0, so maxRedeem returns 0 regardless of actual liquidity.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Amount in denomination token units (human-readable Decimal).
Return type: Optional[decimal.Decimal]

fetch_deposit_next_open()

Get when deposits will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when deposits will next be available, or None if:

Deposits are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_minimum_deposit(block_identifier='latest')

Fetch a source-proven minimum deposit in decimal token units.

A None result means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small deposits. A zero result means the adapter positively established that the vault has no minimum deposit.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
Returns: Decimal denomination-token minimum, or None when unknown.
Return type: Optional[decimal.Decimal]

fetch_minimum_redemption(block_identifier='latest')

Fetch a source-proven redemption minimum in decimal share units.

A None result means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small redemptions. A zero result means the adapter positively established that the vault has no minimum redemption.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
Returns: Decimal vault-share minimum, or None when unknown.
Return type: Optional[decimal.Decimal]

fetch_redemption_next_open()

Get when withdrawals/redemptions will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when withdrawals will next be available, or None if:

Withdrawals are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently lent out.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Utilisation as float between 0.0 and 1.0 (0% to 100%).
Return type: Optional[float]

property flow_manager: eth_defi.vault.base.VaultFlowManager: Flow manager associated with this vault

get_deposit_fee(block_identifier)

Deposit fee is set to zero by default as vaults usually do not have deposit fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_deposit_manager()

Return a manager that explicitly refuses public fund operations.

The manager gives runtime callers a typed refusal, while get_deposit_manager_capability() provides the corresponding report metadata. Concrete issuer integrations must replace both only after implementing their complete permission-aware dealing lifecycle.

Returns: Non-operational tokenised-fund deposit manager.
Return type: eth_defi.tokenised_fund.vault.TokenisedFundDepositManager

get_deposit_manager_capability()

Report explicit lack of public deposit and redemption support.

Returns: A two-direction capability with both operations disabled.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManagerCapability

get_estimated_lock_up()

What is the estimated lock-up period for this vault.

Returns: None if not know
Return type: Optional[datetime.timedelta]

get_fee_mode()

Get how this vault accounts its fees.

Return type: Optional[eth_defi.vault.fee.VaultFeeMode]

get_flags()

Return vault flags including the tokenised fund classification.

Preserve address- and protocol-specific flags supplied by the generic vault implementation, then add the descriptive flag used by tokenised fund listings.

Returns: A new set containing all generic flags and VaultFlag.tokenised_fund.
Return type: set[eth_defi.vault.flag.VaultFlag]

get_notes()

Get a human readable message if we know somethign special is going on with this vault.

Return type: Optional[str]

get_protocol_name()

Return the name of the vault protocol.

Return type: str

get_risk()

Get risk profile of this vault.

Return type: Optional[eth_defi.vault.risk.VaultTechnicalRisk]

get_share_price_source()

Return the source used for share-price observations.

Vault integrations override this method when they expose a share price. Returning None distinguishes unsupported or unknown pricing from a known source classification.

Returns: Share-price source, or None when the adapter does not provide one.
Return type: Optional[eth_defi.vault.price_source.PriceSource]

get_whitelist_notes()

Return an export caveat for the vault-wide whitelist status.

Adapters may attach a concise, stable explanation when a classification is an explicitly requested operating assumption or excludes an integration-specific permission mechanism. The note describes the policy classification only; it must not be used to report temporary deposit availability.

Returns: Export note, or None when the classification needs no caveat.
Return type: Optional[str]

get_withdraw_fee(block_identifier)

Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

has_custom_fees()

Does this vault have fees outside the shared fee model.

Custom fees cause risk in vault comparison because the shared management/performance/deposit/withdraw fee fields cannot describe the full fee structure.

Do not return True merely because a vault implements custom accessors for ordinary management, performance, deposit, or withdraw fees. Return True only when some vault fee cannot be reflected in those standard fields as a fee-like value.

Returns: True if the vault has fees outside the shared fee model.
Return type: bool

property info: eth_defi.vault.base.VaultInfo

Get info dictionary related to this vault deployment.

Get cached data on the various vault parameters

Returns: Vault protocol specific information dictionary

is_account_whitelisted(address)

Determine whether an account has completed the vault’s KYC policy.

The result concerns KYC or manual identity-approval membership only. A protocol may still require scheduling, a token balance, an allowance, available capacity, or an open epoch before a deposit can be submitted. Callers must use the relevant deposit manager pre-flight before broadcasting a transaction.

Parameters: address (eth_typing.evm.HexAddress) – Account whose deposit-policy membership is queried.
Returns: True when the account has the required KYC/identity approval.
Raises: NotImplementedError – If the adapter cannot safely query account membership.
Return type: bool

is_whitelisted_deposit()

Classify tokenised-fund subscriptions as permissioned.

Tokenised-fund adapters model issuer-operated products whose subscriptions require investor eligibility, issuer approval, or both. This is a vault-wide classification: individual adapters may expose different KYC, allow-list, transfer-agent, or offchain settlement mechanisms, so is_account_whitelisted() remains protocol-specific.

Returns: Always True because tokenised-fund deposits are permissioned.
Return type: bool

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption