From 4bfad4c4cf0d66645a0c5b5c63ee21b140aa09c8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 3 Sep 2026 22:14:25 +0000 Subject: [PATCH] docs: sync from base-std@be6d045 --- .../b20/reference/constants-addresses.mdx | 2 +- .../composite-policy-child-ids.mdx | 37 ++++++------ .../create-composite-policy.mdx | 60 ++++++++++++------- .../i-policy-registry/create-policy.mdx | 36 +++++++---- .../finalize-update-admin.mdx | 31 ++++++---- .../i-policy-registry/is-authorized.mdx | 29 +++++---- .../max-composite-child-policies.mdx | 2 +- .../pending-policy-admin.mdx | 18 ++++-- .../i-policy-registry/policy-admin.mdx | 27 +++++---- .../i-policy-registry/policy-exists.mdx | 26 ++++---- .../i-policy-registry/renounce-admin.mdx | 18 ++++-- .../i-policy-registry/stage-update-admin.mdx | 24 +++++--- .../i-policy-registry/update-allowlist.mdx | 27 +++++---- .../i-policy-registry/update-blocklist.mdx | 30 ++++++---- .../interfaces/ib20-asset/announce.mdx | 43 +++++++++---- .../interfaces/ib20-asset/balance-of-ui.mdx | 8 ++- .../interfaces/ib20-asset/batch-mint.mdx | 9 ++- .../interfaces/ib20-asset/effective-at.mdx | 8 ++- .../interfaces/ib20-asset/extra-metadata.mdx | 26 ++++---- .../interfaces/ib20-asset/from-ui-amount.mdx | 24 +++++++- .../interfaces/ib20-asset/multiplier.mdx | 31 ++++++---- .../ib20-asset/new-ui-multiplier.mdx | 6 +- .../ib20-asset/scaled-balance-of.mdx | 20 +++++-- .../interfaces/ib20-asset/to-raw-balance.mdx | 37 ++++++++---- .../ib20-asset/to-scaled-balance.mdx | 29 ++++++--- .../interfaces/ib20-asset/to-ui-amount.mdx | 24 +++++++- .../interfaces/ib20-asset/total-supply-ui.mdx | 14 ++++- .../interfaces/ib20-asset/ui-multiplier.mdx | 6 +- .../ib20-asset/update-multiplier.mdx | 21 ++++--- .../ib20-asset/update-ui-multiplier.mdx | 49 +++++++++++---- .../ib20-factory/get-b20-address.mdx | 22 +++++-- .../interfaces/ib20-stablecoin/currency.mdx | 9 ++- 32 files changed, 520 insertions(+), 233 deletions(-) diff --git a/docs/specifications/b20/reference/constants-addresses.mdx b/docs/specifications/b20/reference/constants-addresses.mdx index 11c3181a7..eb55a5c18 100644 --- a/docs/specifications/b20/reference/constants-addresses.mdx +++ b/docs/specifications/b20/reference/constants-addresses.mdx @@ -45,7 +45,7 @@ These addresses are identical on every network where B20 is active. | Name | Value | |---|---| | `ALWAYS_ALLOW` | `0` | -| `ALWAYS_BLOCK` | `(uint64(uint8(IPolicyRegistry.PolicyType.ALLOWLIST)) << 56) \| 1` | +| `ALWAYS_BLOCK` | `(uint64(uint8(IPolicyRegistry.PolicyType.ALLOWLIST)) << 56) \| 1` | Custom policy IDs use this layout: diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/composite-policy-child-ids.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/composite-policy-child-ids.mdx index 76c9c5125..56757e8a5 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/composite-policy-child-ids.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/composite-policy-child-ids.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.compositePolicyChildIds" -description: "Generated B20 reference for compositePolicyChildIds(uint64)." +description: "Returns the child-policy set of a composite policy." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,26 +16,31 @@ function compositePolicyChildIds(uint64 policyId) external view returns (uint64[ ## Description -Returns the child-policy set of the composite `policyId`. -Dev: Child-policies are listed in the order they were last written. -Dev: Returns an empty array for simple policies, built-in sentinels, unknown IDs, and -malformed IDs. Never reverts. -Dev: An empty return unambiguously means "not a composite". -Dev: The registry preserves the caller's ordering verbatim and neither sorts nor -de-duplicates. -Param: policyId Policy to query. -Return: Child policy IDs, or an empty array. +Returns the ordered child-policy ID set of the composite identified by `policyId`. -## Access Control +- Child policies are returned in the order they were last written; the registry preserves caller ordering verbatim without sorting or de-duplicating. +- Returns an empty array for simple policies, built-in sentinels (`ALWAYS_ALLOW`, `ALWAYS_BLOCK`), unknown IDs, and malformed IDs. +- Never reverts. +- An empty return unambiguously means "not a composite". + +## Parameters -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | The composite policy to query. | -## Policy Interaction +## Returns + +| Type | Description | +|---|---| +| `uint64[] memory` | Child policy IDs, or an empty array if `policyId` is not a composite. | + +## Access Control -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +Read-only. Always callable regardless of whether the PolicyRegistry feature is active. ## Example ```solidity Usage Example -IPolicyRegistry(target).compositePolicyChildIds(arg0); +uint64[] memory children = IPolicyRegistry(registry).compositePolicyChildIds(policyId); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/create-composite-policy.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/create-composite-policy.mdx index d9a145786..13ea7be6c 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/create-composite-policy.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/create-composite-policy.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.createCompositePolicy" -description: "Generated B20 reference for createCompositePolicy(address,uint8,uint64[])." +description: "Creates a new composite policy combining existing simple policies under a logic gate." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,33 +16,49 @@ function createCompositePolicy(address admin, PolicyType policyType, uint64[] ca ## Description -Creates a new composite policy that combines existing simple policies under a logic -gate. -Dev: Child policies must be simple policies (ALLOWLIST or BLOCKLIST), never another composite. -The child-policy set is capped at 4. -Dev: Reverts with `IncompatiblePolicyType` when `policyType` is not UNION or INTERSECT. -Dev: Reverts with `ZeroAddress` when `admin` is `address(0)`. -Dev: Reverts with `ChildPoliciesOutsideOfRange` when `childPolicyIds.length` is not in -`[MIN_COMPOSITE_CHILD_POLICIES, MAX_COMPOSITE_CHILD_POLICIES]`. -Dev: Reverts with `PolicyNotFound` when any child policy does not exist. -Dev: Reverts with `InvalidChildPolicy` when any child policy is not a simple policy or a built-in policy. -Dev: Panics with arithmetic overflow (Panic 0x11) when the policy counter has reached its maximum value. -Param: admin Initial admin authorized to update child policies and transfer or renounce -administration. -Param: policyType UNION or INTERSECT. -Param: childPolicyIds Existing simple policy IDs to combine. -Return: newPolicyId The newly assigned composite policy ID. +Creates a new composite policy that combines 2–4 existing simple (`ALLOWLIST` or `BLOCKLIST`) policies under a `UNION` (OR) or `INTERSECT` (AND) logic gate. The composite references its children live: `isAuthorized` reads current child membership on every call, so updating a child's membership immediately affects what the composite authorizes. + +The new policy is assigned a `uint64` ID whose top byte encodes `PolicyType`; the low 56 bits come from a global counter. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `admin` | `address` | Initial admin authorized to update child policies and transfer or renounce administration. Must not be `address(0)`. | +| `policyType` | `PolicyType` (`uint8`) | Must be `UNION` or `INTERSECT`. | +| `childPolicyIds` | `uint64[]` | Existing simple policy IDs to combine. Must contain 2–4 entries (`MIN_COMPOSITE_CHILD_POLICIES` to `MAX_COMPOSITE_CHILD_POLICIES`). No composites and no built-in sentinels (`ALWAYS_ALLOW` / `ALWAYS_BLOCK`). | + +## Returns + +| Name | Type | Description | +|---|---|---| +| `newPolicyId` | `uint64` | The newly assigned composite policy ID. | + +## Revert Conditions + +| Error | Condition | +|---|---| +| `ZeroAddress` | `admin` is `address(0)`. | +| `IncompatiblePolicyType` | `policyType` is not `UNION` or `INTERSECT`. | +| `ChildPoliciesOutsideOfRange` | `childPolicyIds.length` is outside `[MIN_COMPOSITE_CHILD_POLICIES, MAX_COMPOSITE_CHILD_POLICIES]` (2–4 inclusive). | +| `PolicyNotFound` | Any child policy ID does not exist. | +| `InvalidChildPolicy` | Any child is a composite policy or a built-in sentinel. | +| `Panic(0x11)` | The global policy counter has reached its maximum value (arithmetic overflow). | ## Access Control -Permissionless creation, but state-changing registry calls require the feature to be active. +Permissionless creation, but this call reverts with `FeatureNotActivated` while the PolicyRegistry feature is inactive. + +## Events Emitted -## Policy Interaction +On success, three events are emitted: -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +- `PolicyCreated(newPolicyId, creator, policyType)` +- `PolicyAdminUpdated(newPolicyId, address(0), admin)` +- `CompositePolicyUpdated(newPolicyId, creator, childPolicyIds)` ## Example ```solidity Usage Example -IPolicyRegistry(target).createCompositePolicy(arg0, arg1, arg2); +IPolicyRegistry(target).createCompositePolicy(admin, PolicyType.UNION, childPolicyIds); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/create-policy.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/create-policy.mdx index bd455b956..d6c6932a4 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/create-policy.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/create-policy.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.createPolicy" -description: "Generated B20 reference for createPolicy(address,uint8)." +description: "Creates a new simple (ALLOWLIST or BLOCKLIST) policy with no initial members." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,20 +16,34 @@ function createPolicy(address admin, PolicyType policyType) external returns (ui ## Description -Creates a new simple policy with no initial members. Permissionless. -Dev: Reverts with `ZeroAddress` when `admin` is `address(0)`. -Dev: Reverts with `IncompatiblePolicyType` when `policyType` is a composite gate. -Param: admin Initial admin authorized to modify membership and transfer or renounce administration. -Param: policyType BLOCKLIST or ALLOWLIST. -Return: newPolicyId The newly assigned policy ID. +Creates a new simple policy with no initial members. Any caller may invoke this function. The newly created policy has an empty member set and the specified `admin`. + +To seed an initial member set in the same call, use `createPolicyWithAccounts` instead. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `admin` | `address` | Initial admin authorized to modify membership and transfer or renounce administration. Must not be `address(0)`. | +| `policyType` | `PolicyType` | `ALLOWLIST` or `BLOCKLIST`. Composite gate types (`UNION`, `INTERSECT`) are not accepted here. | + +## Returns + +| Name | Type | Description | +|---|---|---| +| `newPolicyId` | `uint64` | The newly assigned policy ID. The top byte encodes the `PolicyType`; the low 56 bits are a global counter. | ## Access Control -Permissionless creation, but state-changing registry calls require the feature to be active. +Permissionless creation. This is a state-changing call, so it reverts with `FeatureNotActivated` while the PolicyRegistry feature is inactive. -## Policy Interaction +## Revert Conditions -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +| Error | Condition | +|---|---| +| `ZeroAddress` | `admin` is `address(0)`. | +| `IncompatiblePolicyType` | `policyType` is a composite gate (`UNION` or `INTERSECT`). | +| `FeatureNotActivated` | The PolicyRegistry feature has not been activated. | ## Example diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/finalize-update-admin.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/finalize-update-admin.mdx index 5d8c71d98..f0df0c191 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/finalize-update-admin.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/finalize-update-admin.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.finalizeUpdateAdmin" -description: "Generated B20 reference for finalizeUpdateAdmin(uint64)." +description: "Completes a two-step admin transfer on a PolicyRegistry policy." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,22 +16,31 @@ function finalizeUpdateAdmin(uint64 policyId) external; ## Description -Completes a two-step admin transfer. Promotes the caller to active admin and clears the pending slot. -Dev: Reverts with `PolicyNotFound` when `policyId` does not exist. -Dev: Reverts with `NoPendingAdmin` when no transfer is in flight. -Dev: Reverts with `Unauthorized` when the caller is not the staged pending admin. -Param: policyId Policy whose admin transfer is being finalized. +Completes a two-step admin transfer. The caller must be the staged pending admin. On success, the caller becomes the active admin and the pending slot is cleared. + +This function is gated by the `ActivationRegistry`; it reverts with `FeatureNotActivated` while the feature is inactive. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | ID of the policy whose pending admin transfer is being finalized. | ## Access Control -Callable only by the staged pending admin for the target policy; finalization promotes the caller to active admin. +Callable only by the staged pending admin for the target policy. -## Policy Interaction +## Revert Conditions -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +| Error | Condition | +|---|---| +| `FeatureNotActivated` | The PolicyRegistry feature is not yet active. | +| `PolicyNotFound` | `policyId` does not exist. | +| `NoPendingAdmin` | No transfer is in flight for this policy. | +| `Unauthorized` | Caller is not the staged pending admin. | ## Example ```solidity Usage Example -IPolicyRegistry(target).finalizeUpdateAdmin(arg0); +IPolicyRegistry(target).finalizeUpdateAdmin(policyId); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/is-authorized.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/is-authorized.mdx index 57eeebf25..e5c73e0fb 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/is-authorized.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/is-authorized.mdx @@ -3,8 +3,6 @@ title: "IPolicyRegistry.isAuthorized" description: "Generated B20 reference for isAuthorized(uint64,address)." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,21 +16,30 @@ function isAuthorized(uint64 policyId, address account) external view returns (b ## Description -Returns whether `account` is authorized under `policyId`. Never reverts; unknown -or malformed IDs collapse to empty-member-set semantics (ALLOWLIST -> false, -BLOCKLIST -> true). -Dev: Callers that store policy IDs MUST validate `policyExists(policyId)` at write time. -Param: policyId Policy to query. -Param: account Account to check. -Return: Whether `account` is authorized. +Returns whether `account` is authorized under `policyId`. Never reverts; unknown or malformed IDs collapse to empty-member-set semantics (`ALLOWLIST` → `false`, `BLOCKLIST` → `true`). + +Callers that store policy IDs **must** validate `policyExists(policyId)` at write time. A typo'd `BLOCKLIST` ID silently behaves as `ALWAYS_ALLOW` because an unknown ID collapses to an empty member set. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy to query. | +| `account` | `address` | Account to check. | + +## Returns + +| Type | Description | +|---|---| +| `bool` | `true` if `account` is authorized under `policyId`, `false` otherwise. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Always callable. This function is never gated by the `ActivationRegistry`, regardless of whether the PolicyRegistry feature is active. ## Policy Interaction -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +Part of the singleton `PolicyRegistry` surface used by B20 policy scopes. For composite policies (`UNION`/`INTERSECT`), this function reads current child-policy membership on every call, so updating a child's membership immediately affects what the composite authorizes. ## Example diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/max-composite-child-policies.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/max-composite-child-policies.mdx index ac6f2e055..9f7866f04 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/max-composite-child-policies.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/max-composite-child-policies.mdx @@ -23,7 +23,7 @@ Return: Maximum permitted child-policy count. ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only. Always callable regardless of activation state. ## Policy Interaction diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/pending-policy-admin.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/pending-policy-admin.mdx index abbf1cedf..1d1d8f397 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/pending-policy-admin.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/pending-policy-admin.mdx @@ -21,16 +21,22 @@ function pendingPolicyAdmin(uint64 policyId) external view returns (address); Returns the currently-staged pending admin for `policyId`, or `address(0)` when no transfer is in flight or for built-in sentinels, unknown IDs, and malformed IDs. Never reverts. -Param: policyId Policy to query. -Return: Pending admin, or `address(0)`. -## Access Control +**Parameters** + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy to query. | -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +**Returns** -## Policy Interaction +| Type | Description | +|---|---| +| `address` | Pending admin, or `address(0)` if no transfer is in flight. | + +## Access Control -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +Read-only. Always callable regardless of whether the PolicyRegistry feature is active. ## Example diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-admin.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-admin.mdx index fbd514d0f..1638bb6e0 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-admin.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-admin.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.policyAdmin" -description: "Generated B20 reference for policyAdmin(uint64)." +description: "Returns the current admin of a policy in the PolicyRegistry." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,21 +16,26 @@ function policyAdmin(uint64 policyId) external view returns (address); ## Description -Returns the current admin of `policyId`, or `address(0)` for built-in sentinels, -renounced policies, unknown IDs, and malformed IDs. Never reverts. -Param: policyId Policy to query. -Return: Current admin, or `address(0)`. +Returns the current admin of `policyId`. Returns `address(0)` for built-in sentinels (`ALWAYS_ALLOW`, `ALWAYS_BLOCK`), renounced policies, unknown IDs, and malformed IDs. Never reverts. -## Access Control +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | The policy to query. | -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +## Returns -## Policy Interaction +| Type | Description | +|---|---| +| `address` | Current admin, or `address(0)` if none. | + +## Access Control -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +Always callable. This read-only function is not gated by the ActivationRegistry. ## Example ```solidity Usage Example -IPolicyRegistry(target).policyAdmin(arg0); +address admin = IPolicyRegistry(target).policyAdmin(policyId); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-exists.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-exists.mdx index b091321ea..aaf7f198d 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-exists.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/policy-exists.mdx @@ -1,10 +1,8 @@ --- title: "IPolicyRegistry.policyExists" -description: "Generated B20 reference for policyExists(uint64)." +description: "Returns whether a given policy ID is a built-in sentinel or a previously-assigned custom ID." --- - - ## Signature ```solidity IPolicyRegistry.sol @@ -18,20 +16,26 @@ function policyExists(uint64 policyId) external view returns (bool); ## Description -Returns whether `policyId` is a built-in sentinel or a previously-assigned custom ID. Never reverts. -Param: policyId Policy to query. -Return: Whether the policy exists. +Returns `true` if `policyId` is a built-in sentinel (`ALWAYS_ALLOW` or `ALWAYS_BLOCK`) or a previously-assigned custom policy ID. Never reverts, regardless of the input value. -## Access Control +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | The policy ID to query. | -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +## Returns -## Policy Interaction +| Type | Description | +|---|---| +| `bool` | `true` if the policy exists; `false` otherwise. | + +## Access Control -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +Read-only. Always callable — this function is never gated by the `ActivationRegistry`, whether or not the PolicyRegistry feature is active. ## Example ```solidity Usage Example -IPolicyRegistry(target).policyExists(arg0); +IPolicyRegistry(policyRegistry).policyExists(policyId); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/renounce-admin.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/renounce-admin.mdx index eeb2ce86e..b48cefe9b 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/renounce-admin.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/renounce-admin.mdx @@ -20,13 +20,23 @@ function renounceAdmin(uint64 policyId) external; Permanently relinquishes administration of `policyId`. The member set is frozen and the policy can never be re-administered; `isAuthorized` queries continue to work. -Dev: Reverts with `PolicyNotFound` when `policyId` does not exist. -Dev: Reverts with `Unauthorized` when the caller is not the current admin. -Param: policyId Policy whose administration is being renounced. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy whose administration is being renounced. | ## Access Control -Callable by the policy admin for the target policy. +Callable by the current admin of the target policy. + +## Revert Conditions + +| Error | Condition | +|---|---| +| `PolicyNotFound` | `policyId` does not exist. | +| `Unauthorized` | Caller is not the current admin. | ## Policy Interaction diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/stage-update-admin.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/stage-update-admin.mdx index f97bec05c..9a03c32c2 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/stage-update-admin.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/stage-update-admin.mdx @@ -20,21 +20,29 @@ function stageUpdateAdmin(uint64 policyId, address newAdmin) external; Stages a proposed new admin for `policyId`. The active admin does not change until `pendingAdmin` calls `finalizeUpdateAdmin`. -Dev: Reverts with `PolicyNotFound` when `policyId` does not exist. -Dev: Reverts with `Unauthorized` when the caller is not the current admin. -Param: policyId Policy whose admin is being staged. -Param: newAdmin Proposed new admin, or `address(0)` to clear any pending nomination. + +Passing `address(0)` as `newAdmin` cancels any in-flight transfer. Re-staging while a pending admin already exists overwrites the prior nomination — the previous candidate loses their ability to finalize. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy whose admin is being staged. | +| `newAdmin` | `address` | Proposed new admin, or `address(0)` to clear any pending nomination. | ## Access Control -Callable by the policy admin for the target policy. +Callable by the current policy admin for the target policy. -## Policy Interaction +## Revert Conditions -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +| Error | Condition | +|---|---| +| `PolicyNotFound` | `policyId` does not exist. | +| `Unauthorized` | Caller is not the current admin. | ## Example ```solidity Usage Example -IPolicyRegistry(target).stageUpdateAdmin(arg0, arg1); +IPolicyRegistry(target).stageUpdateAdmin(policyId, newAdmin); ``` diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/update-allowlist.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/update-allowlist.mdx index 44a37c27b..c38717349 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/update-allowlist.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/update-allowlist.mdx @@ -19,21 +19,28 @@ function updateAllowlist(uint64 policyId, bool allowed, address[] calldata accou ## Description Sets `accounts` membership in an ALLOWLIST policy to `allowed` in one batch. -Dev: Reverts with `PolicyNotFound` when `policyId` does not exist. -Dev: Reverts with `IncompatiblePolicyType` when the policy is not ALLOWLIST. -Dev: Reverts with `Unauthorized` when the caller is not the current admin. -Dev: Reverts with `BatchSizeTooLarge` when `accounts.length` exceeds the registry limit. -Param: policyId Policy to update. -Param: allowed Membership state to apply to every account in the batch. -Param: accounts Accounts to update. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy to update. Must be an existing ALLOWLIST policy. | +| `allowed` | `bool` | Membership state to apply to every account in the batch. | +| `accounts` | `address[]` | Accounts to update. | ## Access Control -Callable by the policy admin for the target policy. +Callable by the policy admin for the target policy. Gated by the ActivationRegistry — reverts with `FeatureNotActivated` while the feature is inactive. -## Policy Interaction +## Revert Conditions -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +| Error | Condition | +|---|---| +| `FeatureNotActivated` | The feature is not yet active. | +| `PolicyNotFound` | `policyId` does not exist. | +| `IncompatiblePolicyType` | The policy is not an ALLOWLIST policy. | +| `Unauthorized` | Caller is not the current admin. | +| `BatchSizeTooLarge` | `accounts.length` exceeds the registry limit. | ## Example diff --git a/docs/specifications/b20/reference/interfaces/i-policy-registry/update-blocklist.mdx b/docs/specifications/b20/reference/interfaces/i-policy-registry/update-blocklist.mdx index 40533d088..5526394b8 100644 --- a/docs/specifications/b20/reference/interfaces/i-policy-registry/update-blocklist.mdx +++ b/docs/specifications/b20/reference/interfaces/i-policy-registry/update-blocklist.mdx @@ -18,25 +18,31 @@ function updateBlocklist(uint64 policyId, bool blocked, address[] calldata accou ## Description -Sets `accounts` membership in a BLOCKLIST policy to `blocked` in one batch. -Dev: Reverts with `PolicyNotFound` when `policyId` does not exist. -Dev: Reverts with `IncompatiblePolicyType` when the policy is not BLOCKLIST. -Dev: Reverts with `Unauthorized` when the caller is not the current admin. -Dev: Reverts with `BatchSizeTooLarge` when `accounts.length` exceeds the registry limit. -Param: policyId Policy to update. -Param: blocked Membership state to apply to every account in the batch. -Param: accounts Accounts to update. +Sets `accounts` membership in a `BLOCKLIST` policy to `blocked` in one batch. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `policyId` | `uint64` | Policy to update. Must be an existing `BLOCKLIST` policy. | +| `blocked` | `bool` | Membership state to apply to every account in the batch. | +| `accounts` | `address[]` | Accounts to update. | ## Access Control -Callable by the policy admin for the target policy. +Callable by the policy admin for the target policy. Reverts with `FeatureNotActivated` when the PolicyRegistry feature is not active. -## Policy Interaction +## Revert Conditions -This is part of the singleton PolicyRegistry surface used by B20 policy scopes. +| Error | Condition | +|---|---| +| `PolicyNotFound` | `policyId` does not exist. | +| `IncompatiblePolicyType` | The policy is not a `BLOCKLIST` policy. | +| `Unauthorized` | Caller is not the current admin. | +| `BatchSizeTooLarge` | `accounts.length` exceeds the registry limit. | ## Example ```solidity Usage Example -IPolicyRegistry(target).updateBlocklist(arg0, arg1, arg2); +IPolicyRegistry(target).updateBlocklist(policyId, blocked, accounts); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/announce.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/announce.mdx index e89f74228..0bece4189 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/announce.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/announce.mdx @@ -3,7 +3,9 @@ title: "IB20Asset.announce" description: "Generated B20 reference for announce(bytes[],string,string,string)." --- - + +The `docs/B20/Asset.md` source file that previously documented the Asset variant (including announcements) has been removed as part of a documentation restructure. This reference page reflects the last verified interface state. + ## Signature @@ -22,21 +24,27 @@ Posts a holder-impacting announcement and atomically dispatches each entry in `internalCalls` via self-`delegatecall` (preserving `msg.sender`). Emits `Announcement` then `EndAnnouncement` with the same `id`. Pass an empty `internalCalls` for a pure disclosure. -Dev: Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `OPERATOR_ROLE`. -Dev: Reverts with `AnnouncementIdAlreadyUsed` when `id` has previously been consumed. -Dev: Reverts with `InternalCallMalformed` when an entry in `internalCalls` is shorter than four bytes. -Dev: Reverts with `AnnouncementInProgress` when an entry in `internalCalls` targets `announce` itself. -Dev: An inner call that raises a Solidity `Panic` (e.g. arithmetic overflow) propagates the -raw Panic unchanged; any other inner revert wraps as `InternalCallFailed(call)`. An inner + +Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `OPERATOR_ROLE`. +Reverts with `AnnouncementIdAlreadyUsed` when `id` has previously been consumed. +Reverts with `InternalCallMalformed` when an entry in `internalCalls` is shorter than four bytes. +Reverts with `AnnouncementInProgress` when an entry in `internalCalls` targets `announce` itself. +An inner call that raises a Solidity `Panic` (e.g. arithmetic overflow) propagates the +raw `Panic` unchanged; any other inner revert wraps as `InternalCallFailed(call)`. An inner out-of-gas halts the whole call. -Param: internalCalls ABI-encoded calldata blobs executed in order via self-`delegatecall`; may be empty. -Param: id Caller-chosen announcement id; single-use over the token's lifetime. -Param: description Human-readable summary of the announcement. -Param: uri Off-chain URI containing the full announcement contents. + +## Parameters + +| Parameter | Type | Description | +|---|---|---| +| `internalCalls` | `bytes[] calldata` | ABI-encoded calldata blobs executed in order via self-`delegatecall`; may be empty. | +| `id` | `string calldata` | Caller-chosen announcement id; single-use over the token's lifetime. | +| `description` | `string calldata` | Human-readable summary of the announcement. | +| `uri` | `string calldata` | Off-chain URI containing the full announcement contents. | ## Access Control -`OPERATOR_ROLE` gates this Asset call. +`OPERATOR_ROLE` gates this call. ## Policy Interaction @@ -45,5 +53,14 @@ No direct policy interaction. ## Example ```solidity Usage Example -IB20Asset(target).announce(arg0, arg1, arg2, arg3); +// Disclose and schedule a 2:1 forward split, effective at the ex-date. +bytes[] memory calls = new bytes[](1); +calls[0] = abi.encodeCall(IB20Asset.updateUIMultiplier, (2e18, exDateTimestamp)); + +IB20Asset(token).announce({ + internalCalls: calls, + id: "2026-Q3-split", + description: "2:1 forward split, effective at ex-date", + uri: "https://disclosures.example.com/..." +}); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/balance-of-ui.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/balance-of-ui.mdx index 5e52a0fbe..6ab5f1b01 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/balance-of-ui.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/balance-of-ui.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.balanceOfUI" description: "ERC-8056 UI-adjusted balance reference." --- + +The source file that defined the B20 Asset interface (`docs/B20/Asset.md`) has been removed as part of a documentation restructure. The information below is preserved from the previous specification. Refer to the current B20 reference pages for up-to-date normative content. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,6 @@ function balanceOfUI(address account) external view returns (uint256); ## Description -Returns the UI-adjusted balance of `account`. +`balanceOfUI` is part of the optional ERC-8056 Balances extension (`0xd890fd71`). It aliases `scaledBalanceOf(account)`, returning the account's raw balance scaled by the current `uiMultiplier()`. + +Scaling divides by `WAD_PRECISION` (`1e18`) and rounds down. The result is a display-oriented value; raw balances — used by `balanceOf`, `transfer`, and `totalSupply` — are not affected. diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/batch-mint.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/batch-mint.mdx index 11d3e9cfe..5ff3987cd 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/batch-mint.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/batch-mint.mdx @@ -21,6 +21,11 @@ function batchMint(address[] calldata recipients, uint256[] calldata amounts) ex Mints `amounts[i]` to `recipients[i]` in one call. All-or-nothing: any element revert unwinds the whole transaction. Emits `Transfer(address(0), recipients[i], amounts[i])` per element. + + +This function is deleted upstream. The source file `docs/B20/Asset.md` has been removed. The content below reflects the last known state; verify against the current `IB20Asset` interface before use. + + Dev: Reverts with `ContractPaused(MINT)` when `MINT` is paused. Dev: Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `MINT_ROLE`. Dev: Reverts with `LengthMismatch` when `recipients.length != amounts.length`. @@ -33,11 +38,11 @@ Param: amounts Per-recipient amounts, parallel to `recipients`. ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Gated by `MINT_ROLE`. Should be wrapped in `announce()`, which additionally requires `OPERATOR_ROLE`. ## Policy Interaction -No direct policy interaction. +Checks `MINT_RECEIVER_POLICY` for each recipient. Any recipient that is not authorized causes the whole batch to revert. ## Example diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/effective-at.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/effective-at.mdx index 0ab7df83e..e73fbd25b 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/effective-at.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/effective-at.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.effectiveAt" description: "ERC-8056 pending multiplier timestamp reference." --- + +The source file that documented this function (`docs/B20/Asset.md`) has been removed as part of a documentation restructure. The content below reflects the last verified state of this function's behavior. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,6 @@ function effectiveAt() external view returns (uint256); ## Description -Returns the timestamp at which the pending UI multiplier becomes effective. +Returns the timestamp at which the pending UI multiplier becomes effective. This is part of the ERC-8056 required extension (`0x4bd27648`), alongside `newUIMultiplier()`. + +When no pending update is scheduled, the value is not meaningful; pair this call with `newUIMultiplier()` to determine whether a pending update exists. diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/extra-metadata.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/extra-metadata.mdx index 6abef90a5..d17a589ca 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/extra-metadata.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/extra-metadata.mdx @@ -1,10 +1,8 @@ --- title: "IB20Asset.extraMetadata" -description: "Generated B20 reference for extraMetadata(string)." +description: "Returns the value of a named metadata entry on a B20 Asset token." --- - - ## Signature ```solidity IB20Asset.sol @@ -18,15 +16,23 @@ function extraMetadata(string calldata key) external view returns (string memory ## Description -The value of the named metadata entry, or the empty string if not set. A -variant-agnostic key/value store; the issuer chooses the key namespace -(e.g. `"category"`, `"region"`, `"reference"`). -Param: key Metadata entry key. -Return: Current value, or the empty string. +Returns the value of the named metadata entry, or the empty string if no entry exists for that key. Each Asset token carries an arbitrary key/value store the issuer can use freely — for example `"category"` → `"electronics"`, `"region"` → `"north-america"`, or `"reference"` → `"REF-2024-001"`. All entries are optional and added post-creation; the factory seeds none at token creation. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `key` | `string` | Metadata entry key. An empty key reverts with `InvalidMetadataKey` on write operations; read calls with an empty key return the empty string. | + +## Returns + +| Type | Description | +|---|---| +| `string` | Current value for the key, or the empty string if not set. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +View — no role required. ## Policy Interaction @@ -35,5 +41,5 @@ No direct policy interaction. ## Example ```solidity Usage Example -IB20Asset(target).extraMetadata(arg0); +string memory category = IB20Asset(token).extraMetadata("category"); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/from-ui-amount.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/from-ui-amount.mdx index be5a1087b..8f90fd904 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/from-ui-amount.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/from-ui-amount.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.fromUIAmount" description: "ERC-8056 UI-to-raw conversion reference." --- + +The source file that documented this function (`docs/B20/Asset.md`) has been removed as part of a documentation restructure. The content below reflects the last verified state of this function's behavior. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,22 @@ function fromUIAmount(uint256 uiAmount) external view returns (uint256); ## Description -Converts `uiAmount` to its raw token representation at the effective multiplier. +Converts `uiAmount` to its raw token representation at the effective multiplier. The result is integer-floored, so a round-trip through `toUIAmount` → `fromUIAmount` can lose up to one ULP of the scaled amount. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `uiAmount` | `uint256` | The UI (scaled) amount to convert to raw. | + +## Returns + +| Type | Description | +|---|---| +| `uint256` | The raw token amount, rounded down. | + +## Behavior + +- Applies the currently effective multiplier (see `uiMultiplier()`). +- Division rounds down; the raw result may be one ULP less than the exact quotient. +- Part of the ERC-8056 optional Conversion extension (`0x57854fc3`). diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/multiplier.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/multiplier.mdx index b6a76a397..6608f31be 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/multiplier.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/multiplier.mdx @@ -1,10 +1,8 @@ --- title: "IB20Asset.multiplier" -description: "Generated B20 reference for multiplier()." +description: "Returns the current raw-balance multiplier for a B20 Asset token." --- - - ## Signature ```solidity IB20Asset.sol @@ -18,22 +16,35 @@ function multiplier() external view returns (uint256); ## Description -The current multiplier, scaled to `WAD_PRECISION`. Holder balances are stored -as raw units; the multiplier scales them into a derived "scaled" view, similar -in shape to wstETH wrapping stETH. -Dev: Alias of the ERC-8056 `uiMultiplier()`. -Return: Current (effective) multiplier. +Returns the current effective multiplier in WAD precision (`1e18`, exposed as `WAD_PRECISION()`). Each account's balance is stored as a **raw** value; the multiplier scales that raw balance into a derived **scaled** view for display. The multiplier applies uniformly to all accounts, so an issuer can rebase every displayed balance at once without rewriting individual storage entries. + +This function is an alias of the ERC-8056 `uiMultiplier()`. + +`balanceOf`, `transfer`, and `totalSupply` operate on raw values and are mechanically unaffected by multiplier changes. ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +View — no role required. ## Policy Interaction No direct policy interaction. +## Related Functions + +| Function | Purpose | +|---|---| +| `uiMultiplier()` | ERC-8056 alias of `multiplier()` | +| `newUIMultiplier()` | Pending scheduled multiplier target | +| `effectiveAt()` | Timestamp when the pending multiplier becomes active | +| `toUIAmount(uint256)` | Convert a raw amount to its scaled view | +| `fromUIAmount(uint256)` | Convert a scaled amount to raw (integer-floored) | +| `scaledBalanceOf(address)` | `balanceOf` result expressed in scaled units | +| `updateUIMultiplier(uint256, uint256)` | Schedule a future multiplier change | +| `cancelUIMultiplierUpdate()` | Cancel a pending scheduled update | + ## Example ```solidity Usage Example -IB20Asset(target).multiplier(); +uint256 current = IB20Asset(target).multiplier(); // e.g. 2e18 after a 2:1 split ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/new-ui-multiplier.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/new-ui-multiplier.mdx index 30af86871..7b35f1ff8 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/new-ui-multiplier.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/new-ui-multiplier.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.newUIMultiplier" description: "ERC-8056 pending UI multiplier reference." --- + +The `docs/B20/Asset.md` source file that backed this function's full context has been removed as part of a documentation restructure. The signature and selector below remain accurate. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,4 @@ function newUIMultiplier() external view returns (uint256); ## Description -Returns the pending UI multiplier scheduled to take effect at `effectiveAt`, represented with 18 decimals (`1e18 = 1.0`). +Returns the pending UI multiplier scheduled to take effect at `effectiveAt`, represented with 18 decimals (`1e18 = 1.0`). When no update is pending, returns the current `uiMultiplier()` value. diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/scaled-balance-of.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/scaled-balance-of.mdx index 153b20770..029c03a49 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/scaled-balance-of.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/scaled-balance-of.mdx @@ -18,13 +18,23 @@ function scaledBalanceOf(address account) external view returns (uint256); ## Description -Convenience for `toUIAmount(balanceOf(account))`. -Param: account Account whose scaled balance is being queried. -Return: Scaled balance. +Convenience for `toUIAmount(balanceOf(account))`. Returns the account's raw ERC-20 balance expressed in its scaled (UI) form by applying the active multiplier. Equivalent to `balanceOfUI` in the ERC-8056 Balances extension. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `account` | `address` | Account whose scaled balance is being queried. | + +## Returns + +| Type | Description | +|---|---| +| `uint256` | Scaled balance: `balanceOf(account) * uiMultiplier() / 1e18`, rounded down. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only. No role required. ## Policy Interaction @@ -33,5 +43,5 @@ No direct policy interaction. ## Example ```solidity Usage Example -IB20Asset(target).scaledBalanceOf(arg0); +IB20Asset(target).scaledBalanceOf(account); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/to-raw-balance.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/to-raw-balance.mdx index d89209127..f92566331 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/to-raw-balance.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/to-raw-balance.mdx @@ -1,9 +1,11 @@ --- title: "IB20Asset.toRawBalance" -description: "Generated B20 reference for toRawBalance(uint256)." +description: "Deprecated alias for fromUIAmount. Converts a scaled (UI) balance back to its raw representation." --- - + +`toRawBalance` is a deprecated alias retained in `IB20Asset` for backward compatibility. Prefer `fromUIAmount(uiAmount)` for new integrations. + ## Signature @@ -18,17 +20,28 @@ function toRawBalance(uint256 scaledBalance) external view returns (uint256 rawB ## Description -Converts a scaled balance back to its raw representation: +Converts a scaled (UI) balance back to its raw representation using the current multiplier: `scaledBalance * WAD_PRECISION / multiplier`. -Dev: Integer division rounds toward zero; conversions are not exactly reversible when -`multiplier != WAD_PRECISION`. `toRawBalance(toScaledBalance(x))` may return a -value slightly less than `x`. -Param: scaledBalance Scaled token amount to convert back. -Return: rawBalance Raw balance at the current multiplier. + +Integer division rounds toward zero. Conversions are not exactly reversible when `multiplier != WAD_PRECISION`: `toRawBalance(toScaledBalance(x))` may return a value slightly less than `x`. + +The canonical replacement is `fromUIAmount(uiAmount)`, which applies the same division. Both round down, so the round-trip from raw → UI → raw can lose up to one ULP of the scaled amount only. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `scaledBalance` | `uint256` | Scaled (UI) token amount to convert back to raw. | + +## Returns + +| Name | Type | Description | +|---|---|---| +| `rawBalance` | `uint256` | Raw balance at the current multiplier, rounded down. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only. No role required. ## Policy Interaction @@ -37,5 +50,9 @@ No direct policy interaction. ## Example ```solidity Usage Example -IB20Asset(target).toRawBalance(arg0); +// Deprecated — prefer fromUIAmount +uint256 raw = IB20Asset(token).toRawBalance(scaledAmount); + +// Preferred equivalent +uint256 raw = IB20Asset(token).fromUIAmount(scaledAmount); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/to-scaled-balance.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/to-scaled-balance.mdx index 2bc052f39..82fce31d5 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/to-scaled-balance.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/to-scaled-balance.mdx @@ -1,9 +1,11 @@ --- title: "IB20Asset.toScaledBalance" -description: "Generated B20 reference for toScaledBalance(uint256)." +description: "Deprecated alias for scaledBalanceOf. Converts a raw balance to its scaled view using the current multiplier." --- - + +`toScaledBalance` is a deprecated alias retained in `IB20Asset` for backward compatibility. Prefer `scaledBalanceOf(account)` for new integrations. + ## Signature @@ -18,13 +20,25 @@ function toScaledBalance(uint256 rawBalance) external view returns (uint256); ## Description -Converts a raw balance to its scaled view: `rawBalance * multiplier / WAD_PRECISION`. -Param: rawBalance Raw token amount to scale. -Return: Scaled balance at the current multiplier. +Converts a raw token amount to its scaled (UI) view: `rawBalance * multiplier / WAD_PRECISION`. + +This function is a deprecated alias for the conversion logic exposed by `toUIAmount(rawAmount)` and the convenience read `scaledBalanceOf(account)`. It applies the effective multiplier at the time of the call. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `rawBalance` | `uint256` | Raw token amount to convert. | + +## Returns + +| Type | Description | +|---|---| +| `uint256` | Scaled balance at the current multiplier, rounded down. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only. No role required. ## Policy Interaction @@ -33,5 +47,6 @@ No direct policy interaction. ## Example ```solidity Usage Example -IB20Asset(target).toScaledBalance(arg0); +// Deprecated — prefer toUIAmount or scaledBalanceOf +uint256 scaled = IB20Asset(token).toScaledBalance(rawAmount); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/to-ui-amount.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/to-ui-amount.mdx index deaff04f5..ad8ed70d4 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/to-ui-amount.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/to-ui-amount.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.toUIAmount" description: "ERC-8056 raw-to-UI conversion reference." --- + +The source file `docs/B20/Asset.md` that backed this page has been removed as part of a documentation restructure. The content below reflects the last known specification; verify against the current interface source before relying on it. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,22 @@ function toUIAmount(uint256 rawAmount) external view returns (uint256); ## Description -Converts `rawAmount` to its UI representation at the effective multiplier. +Converts `rawAmount` to its UI (scaled) representation using the effective multiplier. The result is `rawAmount * multiplier / 1e18`, rounded **down**. This is part of the optional ERC-8056 Conversion extension (`0x57854fc3`). + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `rawAmount` | `uint256` | Raw (unscaled) token amount to convert. | + +## Returns + +| Type | Description | +|---|---| +| `uint256` | Scaled UI amount, integer-floored. The round-trip through `fromUIAmount` can lose up to one ULP. | + +## Behavior + +- Uses the **effective** multiplier at the time of the call. If a multiplier update has been scheduled via `updateUIMultiplier` and `block.timestamp` has reached `effectiveAt`, the new multiplier is applied; otherwise the current multiplier is used. +- Division is integer-floored, so rounding loss is at most 1 wei of the scaled amount. +- The raw balance stored on-chain is never modified by this call. diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/total-supply-ui.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/total-supply-ui.mdx index dc6fcaaac..f42f87f89 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/total-supply-ui.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/total-supply-ui.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.totalSupplyUI" description: "ERC-8056 UI-adjusted supply reference." --- + +The source file that documented this function (`docs/B20/Asset.md`) has been removed as part of a documentation restructure. The content below reflects the last verified state of this function's specification. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,12 @@ function totalSupplyUI() external view returns (uint256); ## Description -Returns the UI-adjusted total supply. +Returns the UI-adjusted total supply. Computed as `totalSupply() * uiMultiplier() / 1e18`, where `1e18` is `WAD_PRECISION`. This is part of the optional ERC-8056 Balances extension (`0xd890fd71`). + +The result is scaled by the current effective multiplier. If a scheduled multiplier update has not yet reached its `effectiveAt` timestamp, the current (pre-update) multiplier is used. + +## Returns + +| Name | Type | Description | +|---|---|---| +| _(unnamed)_ | `uint256` | Raw total supply scaled by `uiMultiplier()`, divided by `WAD_PRECISION` (`1e18`), rounded down. | diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/ui-multiplier.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/ui-multiplier.mdx index ddf7c4482..faf1950ec 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/ui-multiplier.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/ui-multiplier.mdx @@ -3,6 +3,10 @@ title: "IB20Asset.uiMultiplier" description: "ERC-8056 UI multiplier reference." --- + +The `docs/B20/Asset.md` source file that backed the detailed multiplier documentation has been removed as part of a documentation restructure. The information below reflects the last verified state of this function's interface. + + ## Signature ```solidity IB20Asset.sol @@ -16,4 +20,4 @@ function uiMultiplier() external view returns (uint256); ## Description -Returns the current ERC-8056 UI multiplier, represented with 18 decimals (`1e18 = 1.0`). +Returns the current ERC-8056 UI multiplier, represented with 18 decimals (`1e18 = 1.0`). This is the standard alias of `multiplier()` and satisfies the ERC-8056 core interface (`0xa60bf13d`). diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/update-multiplier.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/update-multiplier.mdx index 1574a8f72..527a7888a 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/update-multiplier.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/update-multiplier.mdx @@ -3,7 +3,9 @@ title: "IB20Asset.updateMultiplier" description: "Generated B20 reference for updateMultiplier(uint256)." --- - + +`updateMultiplier` is deprecated. The source file `docs/B20/Asset.md` has been removed as part of a documentation restructure. This function reference is retained for backward compatibility. Prefer `updateUIMultiplier` for routine corporate actions. + ## Signature @@ -18,16 +20,19 @@ function updateMultiplier(uint256 newMultiplier) external; ## Description -DEPRECATED. Instant failsafe / emergency override — sets the current multiplier immediately and -cancels any live pending update without a scheduling window. Emits both `MultiplierUpdated` and -`UIMultiplierUpdated`. Prefer `updateUIMultiplier` for routine corporate actions. -Dev: Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `OPERATOR_ROLE`. -Dev: Reverts with `InvalidMultiplier` when `newMultiplier` is zero or above `type(uint128).max`. -Param: newMultiplier New multiplier scaled to `WAD_PRECISION`; must be in `(0, type(uint128).max]`. +DEPRECATED. Instant failsafe / emergency override — sets the current multiplier immediately and cancels any live pending update without a scheduling window. Emits both the deprecated `MultiplierUpdated` and `UIMultiplierUpdated`. Prefer `updateUIMultiplier` for routine corporate actions. + +Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `OPERATOR_ROLE`. Reverts with `InvalidMultiplier` when `newMultiplier` is zero or above `type(uint128).max`. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `newMultiplier` | `uint256` | New multiplier scaled to `WAD_PRECISION` (`1e18`); must be in `(0, type(uint128).max]`. | ## Access Control -`OPERATOR_ROLE` gates this Asset call. +`OPERATOR_ROLE` gates this call. ## Policy Interaction diff --git a/docs/specifications/b20/reference/interfaces/ib20-asset/update-ui-multiplier.mdx b/docs/specifications/b20/reference/interfaces/ib20-asset/update-ui-multiplier.mdx index cdc0cc0b5..155f90be4 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-asset/update-ui-multiplier.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-asset/update-ui-multiplier.mdx @@ -3,7 +3,9 @@ title: "IB20Asset.updateUIMultiplier" description: "Generated B20 reference for updateUIMultiplier(uint256,uint256)." --- - + +The source file `docs/B20/Asset.md` that previously documented this function has been deleted as part of a documentation restructure. The content below is preserved from the last verified state of this reference page. + ## Signature @@ -18,19 +20,32 @@ function updateUIMultiplier(uint256 newMultiplier, uint256 effectiveAt) external ## Description -Schedules a multiplier update to take effect at `effectiveAt` — the standard path -for corporate actions (splits, reinvested dividends). -Dev: Reverts with `AccessControlUnauthorizedAccount` when the caller does not hold `OPERATOR_ROLE`. -Dev: Reverts with `InvalidMultiplier` when `newMultiplier` is zero or above `type(uint128).max`. -Dev: Reverts with `EffectiveAtInPast` when `effectiveAt` is not in the future. -Dev: Reverts with `EffectiveAtTooFar` when `effectiveAt` exceeds `type(uint64).max`. -Dev: Reverts with `UIMultiplierUpdateExists` when a live pending update already exists. -Param: newMultiplier New multiplier scaled to `WAD_PRECISION`. -Param: effectiveAt Timestamp at which `newMultiplier` becomes effective; must be in the future. +Schedules a multiplier update to take effect at `effectiveAt` — the standard path for corporate actions such as stock splits and reinvested dividends. Evaluation is lazy: `multiplier()` / `uiMultiplier()` flip on their own once `block.timestamp` reaches `effectiveAt`. + +Only one pending update is live at a time. To replace an existing pending update, explicitly cancel it with `cancelUIMultiplierUpdate()` and re-schedule in a single `announce()` bracket. + +Emits `UIMultiplierUpdated(oldMultiplier, newMultiplier, effectiveAtTimestamp)` when the scheduled update takes effect. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `newMultiplier` | `uint256` | New multiplier scaled to `WAD_PRECISION` (`1e18`). Must be non-zero and at most `type(uint128).max`. | +| `effectiveAt` | `uint256` | Unix timestamp at which `newMultiplier` becomes effective. Must be in the future and must not exceed `type(uint64).max`. | + +## Revert Conditions + +| Error | Condition | +|---|---| +| `AccessControlUnauthorizedAccount` | Caller does not hold `OPERATOR_ROLE`. | +| `InvalidMultiplier` | `newMultiplier` is zero or exceeds `type(uint128).max` (exposed as `MAX_UI_MULTIPLIER()`). | +| `EffectiveAtInPast` | `effectiveAt` is not strictly in the future. | +| `EffectiveAtTooFar` | `effectiveAt` exceeds `type(uint64).max`. | +| `UIMultiplierUpdateExists` | A live pending update already exists. | ## Access Control -`OPERATOR_ROLE` gates this Asset call. +Gated by `OPERATOR_ROLE`. ## Policy Interaction @@ -38,6 +53,14 @@ No direct policy interaction. ## Example -```solidity Usage Example -IB20Asset(target).updateUIMultiplier(arg0, arg1); +```solidity Title Schedule a 2:1 forward split +bytes[] memory internalCalls = new bytes[](1); +internalCalls[0] = abi.encodeCall(IB20Asset.updateUIMultiplier, (2e18, exDateTimestamp)); + +IB20Asset(token).announce({ + internalCalls: internalCalls, + id: "2026-Q3-split", + description: "2:1 forward split, effective at ex-date", + uri: "https://disclosures.example.com/..." +}); ``` diff --git a/docs/specifications/b20/reference/interfaces/ib20-factory/get-b20-address.mdx b/docs/specifications/b20/reference/interfaces/ib20-factory/get-b20-address.mdx index 7739e6f4e..dddbf53a8 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-factory/get-b20-address.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-factory/get-b20-address.mdx @@ -19,14 +19,26 @@ function getB20Address(B20Variant variant, address sender, bytes32 salt) externa ## Description Returns the deterministic address `createB20` would assign for `(variant, sender, salt)`. Never reverts. -Param: variant Variant of the token whose address is being predicted. -Param: sender Account that would call `createB20`. -Param: salt Caller-chosen salt. -Return: The deterministic token address. + +B20 addresses are deterministic: `[B20 prefix (10 bytes)][variant byte (1 byte)][bytes9(keccak256(deployer, salt))]`. The variant byte is recoverable from the address, so off-chain tooling can identify the variant without an RPC call. + +## Parameters + +| Name | Type | Description | +|---|---|---| +| `variant` | `B20Variant` (`uint8`) | Variant of the token whose address is being predicted. | +| `sender` | `address` | Account that would call `createB20`. | +| `salt` | `bytes32` | Caller-chosen salt. | + +## Returns + +| Type | Description | +|---|---| +| `address` | The deterministic token address. | ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only. No role required. ## Policy Interaction diff --git a/docs/specifications/b20/reference/interfaces/ib20-stablecoin/currency.mdx b/docs/specifications/b20/reference/interfaces/ib20-stablecoin/currency.mdx index 483fa0daa..69dadc62f 100644 --- a/docs/specifications/b20/reference/interfaces/ib20-stablecoin/currency.mdx +++ b/docs/specifications/b20/reference/interfaces/ib20-stablecoin/currency.mdx @@ -18,12 +18,15 @@ function currency() external view returns (string memory); ## Description -The currency code this stablecoin tracks (e.g. `"USD"`, `"EUR"`, `"JPY"`). -Return: Currency code. +Returns the ISO-style currency code this stablecoin tracks (e.g. `"USD"`, `"EUR"`, `"JPY"`). + +The value is set once via `B20StablecoinCreateParams.currency` at creation and is immutable thereafter. It is restricted to `A`–`Z` bytes — no lowercase, no digits, no separators. + +The code is **self-declared**: the contract does not verify it against any registry or allowlist. Wallets and indexers can use it to group stablecoins by underlying fiat without an external lookup, but it is not a proof of fiat backing. ## Access Control -Read-only or ERC-20-standard access rules unless the NatSpec states otherwise. +Read-only; callable by anyone. ## Policy Interaction