FranklinVault

Documentation for eth_defi.tokenised_fund.franklin.vault.FranklinVault Python class.

class FranklinVault

Bases: eth_defi.vault.base.VaultBase

Read-only adapter for Franklin Templeton Benji Ethereum fund shares.

The issuer-managed lastKnownPrice is a base-18 USD reference price. It is read at the requested archive block together with the ERC-20 supply; callers must still assess its freshness against current issuer materials.

Create a Benji fund adapter.

Parameters

web3 – Web3 connection to the product chain.
spec – Chain and fund-token address.
token_cache – ERC-20 metadata cache.
features – Shared pipeline feature flags.
default_block_identifier – Default metadata block retained for adapter compatibility.
require_denomination_token – Whether a missing ERC-20 denomination token is an error.

Attributes summary

`address`	Return the checksum fund-token address.
`chain_id`	Return the EVM chain id.
`curator_slug`	Return the curated manager identifier.
`denomination_token`	Get the token which denominates the vault valuation
`deposit_manager`	Deposit manager assocaited with this vault
`description`	Return the registered fund description.
`flow_manager`	Flow manager associated with this vault
`fund_contract`	Create the token proxy's stable price-view contract.
`info`	Get info dictionary related to this vault deployment.
`manager_name`	Return the product manager.
`name`	Return the registered product name.
`share_token`	ERC-20 that presents vault shares.
`short_description`	Return the registered compact fund description.
`symbol`	Return the ERC-20 share-token symbol.
`vault_address`	Return the scanner-compatible fund-token address.

Methods summary

`__init__`(web3, spec[, token_cache, ...])	Create a Benji fund adapter.
`fetch_available_liquidity`([block_identifier])	Get the amount of denomination token available for immediate withdrawal.
`fetch_denomination_token`()	Return no transferable denomination token.
`fetch_denomination_token_address`()	Return no transferable denomination token.
`fetch_deposit_closed_reason`()	Explain why the public deposit capability is unavailable.
`fetch_deposit_next_open`()	Get when deposits will next be open.
`fetch_info`()	Export adapter metadata.
`fetch_nav`([block_identifier])	Return the adapter's USD TVL estimate.
`fetch_portfolio`(universe[, block_identifier])	Return no on-chain portfolio.
`fetch_redemption_closed_reason`()	Explain why the public redemption capability is unavailable.
`fetch_redemption_next_open`()	Get when withdrawals/redemptions will next be open.
`fetch_scan_record_extra_data`()	Export scan diagnostics for the permissioned fund.
`fetch_share_price`([block_identifier])	Read the issuer-maintained USD reference price.
`fetch_share_token`()	Fetch ERC-20 share-token metadata.
`fetch_share_token_address`([block_identifier])	Return the Benji token address.
`fetch_total_assets`([block_identifier])	Calculate USD TVL from supply and reference price.
`fetch_total_supply`([block_identifier])	Read outstanding fund-share supply.
`fetch_utilisation_percent`([block_identifier])	Get the percentage of assets currently lent out.
`get_deposit_fee`(block_identifier)	Deposit fee is set to zero by default as vaults usually do not have deposit fees.
`get_deposit_manager`()	Reject public deposit and redemption management.
`get_deposit_manager_capability`()	Return static public transaction-adapter support, if any.
`get_estimated_lock_up`()	What is the estimated lock-up period for this vault.
`get_fee_data`()	Return unavailable product-level fee data.
`get_fee_mode`()	Get how this vault accounts its fees.
`get_flags`()	Get various vault state flags from the smart contract.
`get_flow_manager`()	Reject unsupported flow accounting.
`get_historical_reader`(stateful)	Return the Benji supply-and-price historical reader.
`get_link`([referral])	Return the official Benji platform link.
`get_management_fee`(block_identifier)	Return no on-chain management fee.
`get_notes`()	Return product-specific caveats.
`get_performance_fee`(block_identifier)	Return no on-chain performance fee.
`get_protocol_name`()	Return the name of the vault protocol.
`get_risk`()	Get risk profile of this vault.
`get_spec`()
`get_withdraw_fee`(block_identifier)	Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
`has_block_range_event_support`()	Return whether flow-event accounting is implemented.
`has_custom_fees`()	Does this vault have fees outside the shared fee model.
`has_deposit_distribution_to_all_positions`()	Return whether deposits are distributed to on-chain positions.

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

Create a Benji fund adapter.

Parameters

web3 (web3.main.Web3) – Web3 connection to the product chain.
spec (eth_defi.vault.base.VaultSpec) – Chain and fund-token address.
token_cache (Optional[dict]) – ERC-20 metadata cache.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Shared pipeline feature flags.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Default metadata block retained for adapter compatibility.
require_denomination_token (bool) – Whether a missing ERC-20 denomination token is an error.

property chain_id: int

Return the EVM chain id.

Returns: Chain id from the vault specification.

property address: eth_typing.evm.HexAddress

Return the checksum fund-token address.

Returns: Benji ERC-20 proxy address.

property vault_address: eth_typing.evm.HexAddress

Return the scanner-compatible fund-token address.

Returns: Benji ERC-20 proxy address.

property fund_contract: web3.contract.contract.Contract

Create the token proxy’s stable price-view contract.

Returns: Contract exposing lastKnownPrice.

property name: str

Return the registered product name.

Returns: On-chain name or reviewed registry fallback.

property symbol: str

Return the ERC-20 share-token symbol.

Returns: On-chain symbol.

property description: Optional[str]

Return the registered fund description.

Returns: Product description, if the address is reviewed.

property short_description: Optional[str]

Return the registered compact fund description.

Returns: Product short description, if available.

property manager_name: Optional[str]

Return the product manager.

Returns: Franklin Templeton.

property curator_slug: str

Return the curated manager identifier.

Returns: Franklin Templeton curator slug.

fetch_share_token_address(block_identifier='latest')

Return the Benji 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 historical-reader compatibility.
Returns: Fund token address.
Return type: eth_typing.evm.HexAddress

fetch_share_token()

Fetch ERC-20 share-token metadata.

Returns: Benji ERC-20 token details.
Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Return no transferable denomination token.

Returns: None because the servicing flow does not expose an ERC-4626 asset.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Return no transferable denomination token.

Returns: None because issuer subscription assets are not adapter inputs.
Return type: Optional[eth_defi.token.TokenDetails]

fetch_share_price(block_identifier='latest')

Read the issuer-maintained USD reference price.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical or latest Ethereum block identifier.
Returns: USD reference price per human-readable fund share.
Return type: decimal.Decimal

fetch_total_supply(block_identifier='latest')

Read outstanding fund-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]) – Historical or latest Ethereum block identifier.
Returns: Human-readable share supply.
Return type: decimal.Decimal

fetch_total_assets(block_identifier='latest')

Calculate USD TVL from supply and reference price.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical or latest Ethereum block identifier.
Returns: USD-denominated supply multiplied by the reference price.
Return type: decimal.Decimal

fetch_nav(block_identifier='latest')

Return the adapter’s USD TVL estimate.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical or latest Ethereum block identifier.
Returns: Fund total assets derived from the issuer reference price.
Return type: decimal.Decimal

fetch_info()

Export adapter metadata.

Returns: Token identity and valuation-source metadata.
Return type: eth_defi.tokenised_fund.franklin.vault.FranklinVaultInfo

fetch_scan_record_extra_data()

Export scan diagnostics for the permissioned fund.

Returns: USD denomination, restricted-flow and NAV-source details.
Return type: dict[str, object]

fetch_portfolio(universe, block_identifier=None)

Return no on-chain portfolio.

Parameters

universe (eth_defi.vault.base.TradingUniverse) – Ignored because fund holdings are not held by the share token.
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 no on-chain portfolio read is supported.

Returns

Empty spot portfolio.

Return type

eth_defi.vault.base.VaultPortfolio

has_block_range_event_support()

Return whether flow-event accounting is implemented.

Returns: False because issuer servicing events are not modelled.
Return type: bool

has_deposit_distribution_to_all_positions()

Return whether deposits are distributed to on-chain positions.

Returns: False because the adapter has no on-chain portfolio.
Return type: bool

get_flow_manager()

Reject unsupported flow accounting.

Returns: Never returns.
Raises: NotImplementedError – Always, because servicing flows are not implemented.
Return type: eth_defi.vault.base.VaultFlowManager

get_deposit_manager()

Reject public deposit and redemption management.

Returns: Never returns.
Raises: NotImplementedError – Always, because issuer approval and bespoke servicing are required.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManager

fetch_deposit_closed_reason()

Explain why the public deposit capability is unavailable.

Returns: Issuer compliance restriction.
Return type: Optional[str]

fetch_redemption_closed_reason()

Explain why the public redemption capability is unavailable.

Returns: Issuer compliance restriction.
Return type: Optional[str]

get_historical_reader(stateful)

Return the Benji supply-and-price historical reader.

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

get_fee_data()

Return unavailable product-level fee data.

Returns: Broken fee data because the token surface has no fund-fee schedule.
Return type: eth_defi.vault.fee.FeeData

get_management_fee(block_identifier)

Return no on-chain 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]) – Ignored because fees are not exposed by the token.
Returns: None.
Return type: Optional[float]

get_performance_fee(block_identifier)

Return no on-chain 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]) – Ignored because fees are not exposed by the token.
Returns: None.
Return type: Optional[float]

get_notes()

Return product-specific caveats.

Returns: Notes explaining the issuer-controlled reference price and flows.
Return type: str

get_link(referral=None)

Return the official Benji platform link.

Parameters: referral (Optional[str]) – Ignored because Benji does not expose a public address URL pattern.
Returns: Official Benji homepage.
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_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_capability()

Return static public transaction-adapter support, if any.

This method deliberately does not attempt to construct a manager or query live pause, cap, epoch, balance, allow-list, or liquidity state. Adapters opt in only after their complete deposit and redemption lifecycles have focused coverage. None is therefore the safe default for unknown and protocol-specific vaults.

Returns: Adapter-specific capability object, or None when unsupported.
Return type: Optional[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()

Get various vault state flags from the smart contract.

Override to add status flags
Also add flags from our manual flag list in eth_defi.vault.flag

Returns

Flag set.

Do not modify in place.

Return type

set[eth_defi.vault.flag.VaultFlag]

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_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

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption

first_seen_at_block: Optional[int]

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.