tokenised_fund.securitize.settlement

Documentation for eth_defi.tokenised_fund.securitize.settlement Python module.

Reconstruct Securitize fund NAV from asynchronous subscription settlements.

Some Securitize funds, such as the tokenised ARK Venture Fund, sell DSTokens through an ERC-7540-style AsyncFundVault. Investors request deposits in USDC, the requests are batched into generations, and a settler later calls fulfillDeposits(generationId, navPriceWAD) with the price at which the generation converts into fund shares. The contract emits:

event DepositGenerationFulfilled(uint256 indexed generationId, uint256 navPrice, uint256 totalDeposits);
event RedemptionGenerationFulfilled(uint256 indexed generationId, uint256 navPrice, uint256 fulfillmentRate, uint256 totalLiquidity);

When the vault has no onchain navProvider, these settlement prices are the only authoritative onchain fund value. The settler grosses the deposit price up by the tokenised-route subscription fee, so the fund NAV/share is navPrice * (1 - subscription_fee) rounded to the fund’s published NAV precision. Settlements are streamed with Hypersync, never eth_getLogs.

The historical multicall reader has a static call set, so it cannot look up the latest fulfilled generation at each block from contract state. Instead the adapter fetches the settlement timeline once per scan and picks the latest settlement at or before each sampled block.

See the verified AsyncFundVault implementation: https://etherscan.io/address/0x23848fc9b4da2b686358d39403d07256b51a3e9c#code

Module Attributes

DEPOSIT_GENERATION_FULFILLED_TOPIC

Topic of DepositGenerationFulfilled(uint256,uint256,uint256).

REDEMPTION_GENERATION_FULFILLED_TOPIC

Topic of RedemptionGenerationFulfilled(uint256,uint256,uint256,uint256).

SETTLEMENT_FETCH_ATTEMPTS

Hypersync attempts before a rate-limited historical settlement fetch fails.

SETTLEMENT_FETCH_RESET_MARGIN

Seconds added to the server-stated resets_in before retrying.

SETTLEMENT_FETCH_RETRY_SLEEP

Fallback wait in seconds when a rate-limit error has no resets_in.

SECURITIZE_SETTLEMENT_FEEDS

Reviewed Securitize products priced from subscription settlements.

Functions

calculate_settlement_share_price(...)

Convert a deposit settlement price to fund NAV/share.

decode_settlement_prices(logs, feed)

Decode settlement logs into a block-ordered NAV timeline.

fetch_settlement_prices(hypersync_client, ...)

Fetch the settlement NAV timeline with Hypersync.

find_settlement_price_at(prices, block_number)

Find the latest settlement at or before a block.

Classes

SecuritizeSettlementFeed

One reviewed Securitize subscription vault used as a NAV source.

SecuritizeSettlementPrice

One fulfilled deposit generation converted to fund NAV/share.

Exceptions

SecuritizeSettlementError

Raised when no settlement price is available for a block.
DEPOSIT_GENERATION_FULFILLED_TOPIC = '0x34380a1beae99170d09780fb25d293a753fea59b75ed07d0c9ff5e2c0ff1a40e'

Topic of DepositGenerationFulfilled(uint256,uint256,uint256).

REDEMPTION_GENERATION_FULFILLED_TOPIC = '0x43bb6d61de60d191110824522001029a5201ae48550e6874dcdd508407261918'

Topic of RedemptionGenerationFulfilled(uint256,uint256,uint256,uint256).

WAD = Decimal('1000000000000000000')

Fixed-point scale of navPrice values.

SETTLEMENT_NAV_JUMP_WARNING_THRESHOLD = Decimal('0.20')

Relative settlement-to-settlement NAV move that is logged for review.

A venture fund NAV rarely moves this much in one business day. A larger move more likely means the settler changed its fee gross-up, which would shift the whole reconstructed series.

SETTLEMENT_FETCH_ATTEMPTS = 3

Hypersync attempts before a rate-limited historical settlement fetch fails.

Bounded so a saturated API key delays the sequential tokenised-fund scheduler by at most a few minutes; the item is retried on the next tick.

SETTLEMENT_FETCH_RESET_MARGIN = 5

Seconds added to the server-stated resets_in before retrying.

resets_in is reported in whole seconds, so wait a little past it. A shared API key that another consumer saturates can still lose the race.

SETTLEMENT_FETCH_RETRY_SLEEP = 61

Fallback wait in seconds when a rate-limit error has no resets_in.

Longer than Hypersync’s 60-second rate-limit window.

exception SecuritizeSettlementError

Bases: RuntimeError

Raised when no settlement price is available for a block.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class SecuritizeSettlementFeed

Bases: object

One reviewed Securitize subscription vault used as a NAV source.

chain_id: int

EVM chain hosting the DSToken and its subscription vault.

token: eth_typing.evm.HexAddress

Lower-case DSToken address.

vault: eth_typing.evm.HexAddress

Lower-case AsyncFundVault proxy address emitting settlement events.

first_block: int

Block of the first fulfilled deposit generation.

subscription_fee: float

Subscription fee the settler grosses into deposit navPrice values.

nav_decimals: int

Decimal places of the fund’s published NAV/share.

__init__(chain_id, token, vault, first_block, subscription_fee, nav_decimals=2)
Parameters
Return type

None

class SecuritizeSettlementPrice

Bases: object

One fulfilled deposit generation converted to fund NAV/share.

block_number: int

Block where the generation was fulfilled.

generation_id: int

AsyncFundVault deposit generation id.

settlement_price: decimal.Decimal

Settlement price as emitted, in USD per share, including the fee gross-up.

share_price: decimal.Decimal

Fund NAV/share in USD after removing the subscription fee.

classmethod from_wad(block_number, generation_id, nav_price_wad, feed)

Create a settlement price from an emitted WAD navPrice.

Parameters
Returns

Settlement price with the fee-adjusted NAV/share.

Return type

eth_defi.tokenised_fund.securitize.settlement.SecuritizeSettlementPrice

__init__(block_number, generation_id, settlement_price, share_price)
Parameters
Return type

None

SECURITIZE_SETTLEMENT_FEEDS: dict[tuple[int, eth_typing.evm.HexAddress], eth_defi.tokenised_fund.securitize.settlement.SecuritizeSettlementFeed] = {(1, '0xdf1c8e71cbdf48af50b36f96ad2eb6f5094ba72a'): SecuritizeSettlementFeed(chain_id=1, token='0xdf1c8e71cbdf48af50b36f96ad2eb6f5094ba72a', vault='0xef312d033ed52e2796ba604fef12b4a56053b292', first_block=26005046, subscription_fee=0.02, nav_decimals=2)}

Reviewed Securitize products priced from subscription settlements.

calculate_settlement_share_price(nav_price_wad, feed)

Convert a deposit settlement price to fund NAV/share.

The settler back-computes navPrice from each generation’s USDC total and its share amount rounded to 0.001 shares, so the raw value carries rounding noise. Rounding half-up to the fund’s published precision removes the noise and reproduces the published NAV.

Example: 61.7224302451 * 0.98 = 60.48798... becomes 60.49.

Parameters
Returns

Fund NAV/share in USD.

Return type

decimal.Decimal

decode_settlement_prices(logs, feed)

Decode settlement logs into a block-ordered NAV timeline.

Only deposit settlements are priced. A fulfilled redemption generation logs a warning: its navPrice has not yet been checked against a published NAV, and ignoring it could leave the deposit-only series stale if deposits stop settling.

Parameters
Returns

Deposit settlement prices sorted by block number.

Return type

list[eth_defi.tokenised_fund.securitize.settlement.SecuritizeSettlementPrice]

fetch_settlement_prices(hypersync_client, feed, end_block, attempts=3)

Fetch the settlement NAV timeline with Hypersync.

Hypersync is a hard requirement: there is no RPC or archive-state fallback. The repository’s Hypersync client disables internal retries, so a rate-limited request is retried here. Each wait lasts until the server-stated resets_in, because a shared API key’s quota is usually only available right after its 60-second window resets.

Parameters
Returns

Deposit settlement prices sorted by block number.

Raises

RuntimeError – If Hypersync stays rate limited after all attempts, or If Hypersync returns no deposit settlement although end_block is at or after the known first settlement. An incomplete index must abort the scan rather than rewrite priced history as unpriced rows.

Return type

list[eth_defi.tokenised_fund.securitize.settlement.SecuritizeSettlementPrice]

find_settlement_price_at(prices, block_number)

Find the latest settlement at or before a block.

A settlement’s NAV stays in force until the next settlement, so rows between settlements repeat the last struck value.

Parameters
Returns

Latest settlement no later than block_number, or None before the first settlement.

Return type

Optional[eth_defi.tokenised_fund.securitize.settlement.SecuritizeSettlementPrice]