2.1.0 - Compliance checks

New features for pooled staking integration contract and how to opt-in to this version

The new implementation contract was deployed and verified by Kiln at the following address: 0xE0e27f00E7455188E93F6afFcbf82b15c7d4E871. You can check the source code on Etherscan to verify it matches the expected implementation. The corresponding audit report is available here, under "Audit - Kiln Onchain v2 Blocklist addition - Cantina".

Upgrade content: 2.1.0 - Compliance checks

To strengthen sanctions-compliance controls, we have introduced a lightweight upgrade to the Native20 (integrator) contract. With this version you will be able to enforce onchain OFAC oracle checks and manage an allowlist/blocklist with granular action management.

New features:

(Opt-in) Activate OFAC screening:

• New depositors can't interact with your integrator contract if they are on the OFAC sanctionned list

• User that is invested in the product and get sanctionned (part of the OFAC sanctionned list) can't withdraw their funds

1. Introduction

Each Native20 deployment is a TUPProxy (Transparent Upgradeable Pausable Proxy) aka integration contract. The proxy holds all user state (balances, approvals, pool config). The implementation contract holds the logic. Upgrading swaps the logic without touching user state.

This upgrade introduces AccountList rights enforcement. This means that after upgrade, users need default rights set to be able to stake and request exits. If you only call upgradeTo(), users will be locked out until setDefaultRights() is called separately by the admin, this mean we must have access to both admins in order to perform the upgrade.

Key actors involved in the upgrade:

Role	What it does	How to find it
Proxy Admin	Can call upgradeTo()	Stored in the proxy's ERC1967 admin slot
Integration Admin	Can call setDefaultRights()	Stored in the contract's $admin slot, readable via admin()

These are usually not the same address. The upgrade itself requires the proxy admin. Setting default rights requires the integration admin.

---

2. Prerequisites

You need:

• Foundry installed (forge, cast)

• An Ethereum RPC endpoint (Infura, Alchemy, or your own node)

• The proxy admin private key or access to the multisig that controls each proxy

• The integration admin private key or access to the multisig that can call setDefaultRights

Set your RPC URL:

export ETH_RPC_URL=<your RPC>

---

3. Understanding the Architecture

Each Native20 deployment looks like this:

User
  |
  v
TUPProxy (holds state: balances, pool config, rights, etc.)
  |
  |-- ERC1967 admin slot --> Proxy Admin address (can upgrade)
  |-- ERC1967 impl slot  --> Current Implementation address (logic)
  |
  v
Native20 Implementation (stateless logic)

Key ERC1967 storage slots:

Slot	Contents
0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc	Implementation address
0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103	Proxy admin address

Rights bit values (defined in MultiPool.sol):

Right	Hex	Decimal	Bit
FORBIDDEN	0x1	1	0
STAKE	0x2	2	1
TRANSFER	0x4	4	2
REQUEST_EXIT	0x8	8	3

The default rights value you want for normal operation is STAKE | REQUEST_EXIT = 0xA (decimal 10). This sets the rights to be iso with the behavior before the upgrade.

---

4. Identifying Proxy Admin Addresses

First we set our target contract address as environment variable:

export PROXY_ADDRESS=0x...  # The proxy address you want to upgrade

Read the admin from the ERC1967 storage slot:

cast storage $PROXY_ADDRESS 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 | cast parse-bytes32-address

Read the current implementation address:

cast storage $PROXY_ADDRESS 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc | cast parse-bytes32-address

To read the integration admin (the one that can call setDefaultRights):

cast call $PROXY_ADDRESS 'admin()(address)'

Alternatively you can also check theses values in Etherscan.

---

5. Record Pre-Upgrade State (Optional but Recommended)

Before upgrading, it's a good idea to record the current state to perform a quick sanity check after the upgrade. This includes:

• Rate (cast call $PROXY_ADDRESS 'rate()(uint256)')

• Total supply (cast call $PROXY_ADDRESS 'totalSupply()(uint256)')

• Total underlying supply (cast call $PROXY_ADDRESS 'totalUnderlyingSupply()(uint256)')

6. Performing the Upgrade

The new implementation contract was deployed and verified by Kiln at the following address: 0xE0e27f00E7455188E93F6afFcbf82b15c7d4E871. You can check the source code on Etherscan to verify it matches the expected implementation.

upgradeTo() + setDefaultRights() (Two transactions mandatory)

Step 1 and 2 must be done in order and should be done as close together as possible to minimize disruption. Users will be unable to stake or request exits between the two steps.

Step 1 — Upgrade (requires proxy admin):

export NEW_IMPL=0xE0e27f00E7455188E93F6afFcbf82b15c7d4E871
cast send $PROXY_ADDRESS 'upgradeTo(address)' $NEW_IMPL --ledger

Step 2 — Set default rights no OFAC screening (requires integration admin):

cast send $PROXY_ADDRESS 'setDefaultRights(uint248)' 10 --ledger

Step 3 (optional) — Enable OFAC sanctioned screening (requires integration admin):

cast send $PROXY_ADDRESS 'setSanctionsActivation(bool)' true --ledger

Note that if this feature is enabled OFAC wallet can't deposit more and OFAC sanctionned wallet will never be able to withdraw from the contract.

If using multisig (e.g., Gnosis Safe)

Start by creating both proposals (upgrade and set rights) in the multisig interface, bring them all to n-1 signatures, and get the last quorum members together to execute them back-to-back.

Step by step:

1. With the proxy admin multisig, create a transaction to call upgradeTo(new_impl) on the proxy address.

2. With the integration admin multisig, create a second transaction in to call setDefaultRights(10) on the proxy address.

3. Get all the necessary signatures but 1 on both transactions.

4. Coordinate the last signers on both multisig. First perform the last signature and execute the upgrade proposal, once done do the last signature and execute the set rights transaction as soon as possible.

---

7. Post-Upgrade Verification

After each upgrade, verify:

7.1 Implementation changed

cast storage $PROXY_ADDRESS 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc | cast parse-bytes32-address
# Should output $NEW_IMPL

7.2 Default rights are set

cast call $PROXY_ADDRESS 'defaultRights()(uint248)'
# Should output: 10 (or 0xa)

7.3 Basic view functions still work and return expected values

cast call $PROXY_ADDRESS 'name()(string)'
cast call $PROXY_ADDRESS 'symbol()(string)'
cast call $PROXY_ADDRESS 'totalSupply()(uint256)'
cast call $PROXY_ADDRESS 'totalUnderlyingSupply()(uint256)'

7.4 Rate is preserved

The rate should be the same as before upgrade. If you recorded the rate before:

cast call $PROXY_ADDRESS 'rate()(uint256)'
# Compare with the value recorded before upgrade

7.5 Staking works (optional, on a test fork)

On a mainnet fork, verify a fresh user can stake:

anvil --fork-url $ETH_RPC_URL
cast send $PROXY_ADDRESS 'stake()' --value 0.01ether --private-key $TEST_KEY --rpc-url http://localhost:8545

---

APPENDIX : Verifying the upgrade on a local fork first

Always test on a mainnet fork before executing on mainnet:

# Start a local fork
anvil --fork-url $ETH_RPC_URL --auto-impersonate

In another terminal you can the following bash commands, replacing the PROXY_ADDRESS with your target

# Set the RPC URL to the local fork
export ETH_RPC_URL=http://localhost:8545

export PROXY_ADDRESS= #  The proxy address you want to upgrade

export PROXY_ADMIN_ADDRESS=$(cast storage $PROXY_ADDRESS 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 | cast parse-bytes32-address)
export INTEGRATION_ADMIN_ADDRESS=$(cast call $PROXY_ADDRESS 'admin()(address)')
export NEW_IMPL=0xE0e27f00E7455188E93F6afFcbf82b15c7d4E871   # New implementation address

# Fund the impersonated accounts (proxy admin is usually a contract/multisig with no ETH)
cast send $PROXY_ADMIN_ADDRESS --value 1ether \
  --from 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --unlocked 
cast send $INTEGRATION_ADMIN_ADDRESS --value 1ether \
  --from 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --unlocked 

# Impersonate the proxy admin
cast send $PROXY_ADDRESS 'upgradeTo(address)' $NEW_IMPL \
  --from $PROXY_ADMIN_ADDRESS \
  --unlocked \
  --gas-limit 500000

# Impersonate the integration admin to set default rights
cast send $PROXY_ADDRESS 'setDefaultRights(uint248)' 10 \
  --from $INTEGRATION_ADMIN_ADDRESS \
  --unlocked \
  --gas-limit 500000 

# Test staking
cast send $PROXY_ADDRESS 'stake()' --value 1ether \
  --from 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --unlocked 

# Check balance of default anvil account (should have staked tokens)
cast call $PROXY_ADDRESS 'balanceOf(address)(uint256)' 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 

# Test requesting exit (use the balance from staking, not a hardcoded value)
BALANCE=$(cast call $PROXY_ADDRESS 'balanceOf(address)(uint256)' 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 | awk '{print $1}')

cast send $PROXY_ADDRESS 'requestExit(uint256)' $BALANCE \
  --from 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --unlocked 

Need help ?

If you need assistance to perform the upgrade of if you have questions, please reach out to our support team.