@boostxyz/sdk 0.0.0-alpha.9 → 1.1.0-alpha.23

package/src/Budgets/VestingBudget.ts

@@ -34,7 +34,7 @@ import type {
   DeployableOptions,
   GenericDeployableParams,
 } from '../Deployable/Deployable';
-import { DeployableTarget } from '../Deployable/DeployableTarget';
+import { DeployableTargetWithRBAC } from '../Deployable/DeployableTargetWithRBAC';
 import { DeployableUnknownOwnerProvidedError } from '../errors';
 import {
   type FungibleTransferPayload,
@@ -115,9 +115,9 @@ export type VestingBudgetLog<
  * @export
  * @class VestingBudget
  * @typedef {VestingBudget}
- * @extends {DeployableTarget<VestingBudgetPayload>}
+ * @extends {DeployableTargetWithRBAC<VestingBudgetPayload>}
  */
-export class VestingBudget extends DeployableTarget<
+export class VestingBudget extends DeployableTargetWithRBAC<
   VestingBudgetPayload,
   typeof vestingBudgetAbi
 > {
@@ -127,10 +127,11 @@ export class VestingBudget extends DeployableTarget<
    *
    * @public
    * @static
-   * @type {Address}
+   * @type {Record<number, Address>}
    */
-  public static override base: Address = import.meta.env
-    .VITE_VESTING_BUDGET_BASE;
+  public static override bases: Record<number, Address> = {
+    31337: import.meta.env.VITE_VESTING_BUDGET_BASE,
+  };
   /**
    * @inheritdoc
    *
@@ -144,7 +145,7 @@ export class VestingBudget extends DeployableTarget<
    * Get the owner of the budget
    *
    * @public
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'owner'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<Address>}
    */
   public owner(params?: ReadParams<typeof vestingBudgetAbi, 'owner'>) {
@@ -160,8 +161,8 @@ export class VestingBudget extends DeployableTarget<
    * The timestamp at which the vesting schedule begins
    *
    * @public
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'start'>} [params]
-   * @returns {*}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
    */
   public start(params?: ReadParams<typeof vestingBudgetAbi, 'start'>) {
     return readVestingBudgetStart(this._config, {
@@ -176,8 +177,8 @@ export class VestingBudget extends DeployableTarget<
    * The duration of the vesting schedule (in seconds)
    *
    * @public
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'duration'>} [params]
-   * @returns {*}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
    */
   public duration(params?: ReadParams<typeof vestingBudgetAbi, 'duration'>) {
     return readVestingBudgetDuration(this._config, {
@@ -192,8 +193,8 @@ export class VestingBudget extends DeployableTarget<
    * The duration of the cliff period (in seconds)
    *
    * @public
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'cliff'>} [params]
-   * @returns {*}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
    */
   public cliff(params?: ReadParams<typeof vestingBudgetAbi, 'cliff'>) {
     return readVestingBudgetCliff(this._config, {
@@ -212,7 +213,7 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'allocate'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if the allocation was successful
    */
   public async allocate(
@@ -230,8 +231,8 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'allocate'>} [params]
-   * @returns {Promise<boolean>} - True if the allocation was successful
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - True if the allocation was successful
    */
   public async allocateRaw(
     transfer: FungibleTransferPayload,
@@ -260,7 +261,7 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'clawback'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if the request was successful
    */
   public async clawback(
@@ -279,8 +280,8 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'clawback'>} [params]
-   * @returns {Promise<boolean>} - True if the request was successful
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - True if the request was successful
    */
   public async clawbackRaw(
     transfer: FungibleTransferPayload,
@@ -307,7 +308,7 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'disburse'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if the disbursement was successful
    */
   public async disburse(
@@ -324,8 +325,8 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {(FungibleTransferPayload)} transfer
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'disburse'>} [params]
-   * @returns {Promise<boolean>} - True if the disbursement was successful
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - True if the disbursement was successful
    */
   public async disburseRaw(
     transfer: FungibleTransferPayload,
@@ -351,7 +352,7 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {Array<FungibleTransferPayload>} transfers
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'disburseBatch'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if all disbursements were successful
    */
   public async disburseBatch(
@@ -367,8 +368,8 @@ export class VestingBudget extends DeployableTarget<
    * @public
    * @async
    * @param {Array<FungibleTransferPayload>} transfers
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'disburseBatch'>} [params]
-   * @returns {Promise<boolean>} - True if all disbursements were successful
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - True if all disbursements were successful
    */
   public async disburseBatchRaw(
     transfers: FungibleTransferPayload[],
@@ -388,82 +389,11 @@ export class VestingBudget extends DeployableTarget<
     return { hash, result };
   }
 
-  /**
-   * Set the authorized status of the given accounts
-   * The mechanism for managing authorization is left to the implementing contract
-   *
-   * @public
-   * @async
-   * @param {Address[]} addresses - The accounts to authorize or deauthorize
-   * @param {boolean[]} allowed - The authorization status for the given accounts
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'setAuthorized'>} [params]
-   * @returns {Promise<void>}
-   */
-  public async setAuthorized(
-    addresses: Address[],
-    allowed: boolean[],
-    params?: WriteParams<typeof vestingBudgetAbi, 'setAuthorized'>,
-  ) {
-    return await this.awaitResult(
-      this.setAuthorizedRaw(addresses, allowed, params),
-    );
-  }
-
-  /**
-   * Set the authorized status of the given accounts
-   * The mechanism for managing authorization is left to the implementing contract
-   *
-   * @public
-   * @async
-   * @param {Address[]} addresses - The accounts to authorize or deauthorize
-   * @param {boolean[]} allowed - The authorization status for the given accounts
-   * @param {?WriteParams<typeof vestingBudgetAbi, 'setAuthorized'>} [params]
-   * @returns {Promise<void>}
-   */
-  public async setAuthorizedRaw(
-    addresses: Address[],
-    allowed: boolean[],
-    params?: WriteParams<typeof vestingBudgetAbi, 'setAuthorized'>,
-  ) {
-    const { request, result } = await simulateVestingBudgetSetAuthorized(
-      this._config,
-      {
-        address: this.assertValidAddress(),
-        args: [addresses, allowed],
-        ...this.optionallyAttachAccount(),
-        // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
-        ...(params as any),
-      },
-    );
-    const hash = await writeVestingBudgetSetAuthorized(this._config, request);
-    return { hash, result };
-  }
-
-  /**
-   * Check if the given account is authorized to use the budget
-   *
-   * @public
-   * @param {Address} account
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'isAuthorized'>} [params]
-   * @returns {Promise<boolean>} - True if the account is authorized
-   */
-  public isAuthorized(
-    account: Address,
-    params?: ReadParams<typeof vestingBudgetAbi, 'isAuthorized'>,
-  ) {
-    return readVestingBudgetIsAuthorized(this._config, {
-      address: this.assertValidAddress(),
-      args: [account],
-      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
-      ...(params as any),
-    });
-  }
-
   /**
    * Get the end time of the vesting schedule
    *
    * @public
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'end'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public end(params?: ReadParams<typeof vestingBudgetAbi, 'end'>) {
@@ -480,12 +410,12 @@ export class VestingBudget extends DeployableTarget<
    * This is equal to the sum of the total current balance and the total distributed amount
    *
    * @public
-   * @param {Address} asset -  The address of the asset (or the zero address for native assets)
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'total'>} [params]
+   * @param {Address} [asset="0x0000000000000000000000000000000000000000"] -  The address of the asset (or the zero address for native assets)
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public total(
-    asset: Address,
+    asset: Address = zeroAddress,
     params?: ReadParams<typeof vestingBudgetAbi, 'total'>,
   ) {
     return readVestingBudgetTotal(this._config, {
@@ -501,12 +431,12 @@ export class VestingBudget extends DeployableTarget<
    * This is equal to the total vested amount minus any already distributed
    *
    * @public
-   * @param {Address} asset -  The address of the asset (or the zero address for native assets)
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'available'>} [params]
+   * @param {Address} [asset="0x0000000000000000000000000000000000000000"] -  The address of the asset (or the zero address for native assets)
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>} - The amount of assets currently available for distribution
    */
   public available(
-    asset: Address,
+    asset: Address = zeroAddress,
     params?: ReadParams<typeof vestingBudgetAbi, 'available'>,
   ) {
     return readVestingBudgetAvailable(this._config, {
@@ -521,12 +451,12 @@ export class VestingBudget extends DeployableTarget<
    * Get the amount of assets that have been distributed from the budget
    *
    * @public
-   * @param {Address} asset
-   * @param {?ReadParams<typeof vestingBudgetAbi, 'distributed'>} [params]
+   * @param {Address} [asset="0x0000000000000000000000000000000000000000"]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>} - The amount of assets distributed
    */
   public distributed(
-    asset: Address,
+    asset: Address = zeroAddress,
     params?: ReadParams<typeof vestingBudgetAbi, 'distributed'>,
   ) {
     return readVestingBudgetDistributed(this._config, {

package/src/Deployable/Contract.ts

@@ -61,7 +61,7 @@ export class Contract<ContractAbi extends Abi> {
    *
    * @public
    * @readonly
-   * @type {*}
+   * @type {Address | undefined}
    */
   public get address() {
     return this._address;
@@ -174,7 +174,6 @@ export class Contract<ContractAbi extends Abi> {
    * A typed wrapper for `wagmi.watchContractEvent`
    *
    * @public
-   * @async
    * @template {ContractEvent} event
    * @param {(
    *       log: WatchContractEventOnLogsParameter<ContractAbi, event, true>[number],
@@ -182,9 +181,9 @@ export class Contract<ContractAbi extends Abi> {
    * @param {?WatchParams<ContractAbi, event> & {
    *       eventName?: event;
    *     }} [params]
-   * @returns {unknown, params?: any) => unknown}
+   * @returns {() => void}
    */
-  public async subscribe<event extends ContractEventName<ContractAbi>>(
+  public subscribe<event extends ContractEventName<ContractAbi>>(
     cb: (
       log: WatchContractEventOnLogsParameter<ContractAbi, event, true>[number],
     ) => unknown,
@@ -218,7 +217,7 @@ export class Contract<ContractAbi extends Abi> {
    * @template [Result=unknown]
    * @param {Promise<HashAndSimulatedResult<Result>>} hashPromise
    * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams]
-   * @returns {unknown}
+   * @returns {Promise<Result>}
    */
   protected async awaitResult<Result = unknown>(
     hashPromise: Promise<HashAndSimulatedResult<Result>>,

package/src/Deployable/Deployable.ts

@@ -149,7 +149,7 @@ export class Deployable<
    * @param {?Payload} [_payload]
    * @param {?DeployableOptions} [_options]
    * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams] - See [viem.WaitForTransactionReceipt](https://v1.viem.sh/docs/actions/public/waitForTransactionReceipt.html#waitfortransactionreceipt)
-   * @returns {unknown}
+   * @returns {Promise<this>}
    */
   protected async deploy(
     _payload?: Payload,

package/src/Deployable/DeployableTarget.ts

@@ -1,6 +1,6 @@
 import {
   type aCloneableAbi,
-  readACloneableGetComponentInterface as readACloneableGetComponentInterface,
+  readACloneableGetComponentInterface,
   readACloneableSupportsInterface,
 } from '@boostxyz/evm';
 import { deployContract } from '@wagmi/core';
@@ -11,6 +11,7 @@ import {
   type Hex,
   type WaitForTransactionReceiptParameters,
   isAddress,
+  isAddressEqual,
   zeroAddress,
 } from 'viem';
 import {
@@ -38,13 +39,13 @@ export class DeployableTarget<
   ContractAbi extends Abi,
 > extends Deployable<Payload, ContractAbi> {
   /**
-   * A static property representing the address of the base implementation on chain, used when cloning base contracts.
+   * A static property representing a map of stringified chain ID's to the address of the base implementation on chain, used when cloning base contracts.
    *
    * @static
    * @readonly
-   * @type {Address}
+   * @type {Record<string, Address>}
    */
-  static readonly base: Address = zeroAddress;
+  static readonly bases: Record<number, Address> = {};
   /**
    * The target's registry type.
    *
@@ -59,9 +60,16 @@ export class DeployableTarget<
    * @readonly
    * @type {boolean}
    */
-  protected _isBase = true;
-  get isBase() {
-    if (!!this.address && this.address !== this.base) return false;
+  readonly _isBase: boolean = true;
+  public get isBase() {
+    if (
+      !!this.address &&
+      Object.values(this.bases).some((base) =>
+        // biome-ignore lint/style/noNonNullAssertion: won't evaluate this if address checked and defined above
+        isAddressEqual(this.address!, base),
+      )
+    )
+      return true;
     return this._isBase;
   }
 
@@ -75,7 +83,7 @@ export class DeployableTarget<
    */
   constructor(
     options: DeployableOptions,
-    payload: DeployablePayloadOrAddress<Payload>,
+    payload?: DeployablePayloadOrAddress<Payload>,
     isBase?: boolean,
   ) {
     super(options, payload);
@@ -83,22 +91,25 @@ export class DeployableTarget<
     if (
       typeof payload === 'string' &&
       isAddress(payload) &&
-      payload !== this.base &&
-      payload !== zeroAddress
+      payload !== zeroAddress &&
+      !Object.values(this.bases).some((base) => {
+        if (!payload || !base) return false;
+        return isAddressEqual(payload, base);
+      })
     )
       isBase = false;
     if (isBase !== undefined) this._isBase = isBase;
   }
 
   /**
-   * A getter that will return the base implementation's static address
+   * A getter that will return the base implementation's static addresses by numerical chain ID
    *
    * @public
    * @readonly
-   * @type {Address}
+   * @type {Record<number, Address>}
    */
-  public get base(): Address {
-    return (this.constructor as typeof DeployableTarget).base;
+  public get bases(): Record<number, Address> {
+    return (this.constructor as typeof DeployableTarget).bases;
   }
 
   /**
@@ -120,7 +131,7 @@ export class DeployableTarget<
    * @param {?Payload} [payload]
    * @param {?DeployableOptions} [options]
    * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams]
-   * @returns {unknown}
+   * @returns {Promise<this>}
    */
   protected override async deploy(
     payload?: Payload,
@@ -163,8 +174,8 @@ export class DeployableTarget<
    * @public
    * @async
    * @param {Hex} interfaceId - The interface identifier
-   * @param {?ReadParams<typeof contractActionAbi, 'supportsInterface'>} [params]
-   * @returns {unknown} - True if the contract supports the interface
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>} - True if the contract supports the interface
    */
   public async supportsInterface(
     interfaceId: Hex,
@@ -185,8 +196,8 @@ export class DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof contractActionAbi, 'getComponentInterface'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Hex>}
    */
   public async getComponentInterface(
     params?: ReadParams<typeof aCloneableAbi, 'getComponentInterface'>,

package/src/Deployable/DeployableTargetWithRBAC.test.ts

@@ -0,0 +1,103 @@
+import { loadFixture } from '@nomicfoundation/hardhat-network-helpers';
+import { beforeAll, describe, expect, test } from 'vitest';
+import { accounts } from '@boostxyz/test/accounts';
+import {
+  type Fixtures,
+  defaultOptions,
+  deployFixtures,
+  freshManagedBudget,
+} from '@boostxyz/test/helpers';
+import { Roles } from './DeployableTargetWithRBAC';
+
+let fixtures: Fixtures;
+
+beforeAll(async () => {
+  fixtures = await loadFixture(deployFixtures(defaultOptions));
+});
+
+describe('RBAC', () => {
+  test('can grant roles', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const manager = accounts[0].account;
+    expect(await budget.rolesOf(manager)).not.toContain(Roles.MANAGER);
+    await budget.grantRoles(manager, Roles.MANAGER);
+    expect(await budget.rolesOf(manager)).toContain(Roles.MANAGER);
+  });
+
+  test('can revoke roles', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const admin = accounts[1].account;
+    await budget.grantRoles(admin, Roles.ADMIN);
+    expect(await budget.rolesOf(admin)).toContain(Roles.ADMIN);
+    await budget.revokeRoles(admin, Roles.ADMIN);
+    expect(await budget.rolesOf(admin)).not.toContain(Roles.ADMIN);
+  });
+
+  test('can grant many roles', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const admin = accounts[2].account;
+    const manager = accounts[3].account;
+    await budget.grantManyRoles(
+      [admin, manager],
+      [Roles.ADMIN, Roles.MANAGER],
+    );
+    expect(await budget.hasAllRoles(admin, Roles.ADMIN)).toBe(true);
+    expect(await budget.hasAllRoles(manager, Roles.MANAGER)).toBe(true);
+  });
+
+  test('can revoke many roles', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const admin = accounts[4].account;
+    const manager = accounts[5].account;
+    await budget.grantManyRoles(
+      [admin, manager],
+      [Roles.ADMIN, Roles.MANAGER],
+    );
+    expect(await budget.hasAllRoles(admin, Roles.ADMIN)).toBe(true);
+    expect(await budget.hasAllRoles(manager, Roles.MANAGER)).toBe(true);
+    await budget.revokeManyRoles(
+      [admin, manager],
+      [Roles.ADMIN, Roles.MANAGER],
+    );
+    expect(await budget.hasAllRoles(admin, Roles.ADMIN)).toBe(false);
+    expect(await budget.hasAllRoles(manager, Roles.MANAGER)).toBe(false);
+  });
+
+  test('can check for any role', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const user = accounts[6].account;
+    expect(await budget.hasAnyRole(user, Roles.MANAGER | Roles.ADMIN)).toBe(false);
+    await budget.grantRoles(user, Roles.MANAGER);
+    expect(await budget.hasAnyRole(user, Roles.MANAGER | Roles.ADMIN)).toBe(true);
+  });
+
+  test('can check for all roles', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const user = accounts[7].account;
+    await budget.grantRoles(user, Roles.MANAGER);
+    expect(await budget.hasAllRoles(user, Roles.MANAGER | Roles.ADMIN)).toBe(false);
+    await budget.grantRoles(user, Roles.ADMIN);
+    expect(await budget.hasAllRoles(user, Roles.MANAGER | Roles.ADMIN)).toBe(true);
+  });
+
+  test('can get roles of an account', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const user = accounts[8].account;
+    await budget.grantRoles(user, Roles.MANAGER | Roles.ADMIN);
+    const roles = await budget.rolesOf(user);
+    expect(roles).toContain(Roles.MANAGER);
+    expect(roles).toContain(Roles.ADMIN);
+  });
+
+  test('can set and check authorization', async () => {
+    const budget = await loadFixture(freshManagedBudget(defaultOptions, fixtures));
+    const user = accounts[9].account;
+    expect(await budget.rolesOf(user)).not.toContain(Roles.MANAGER);
+    await budget.setAuthorized([user], [true]);
+    expect(await budget.isAuthorized(user)).toBe(true);
+    expect(await budget.rolesOf(user)).toContain(Roles.MANAGER);
+    await budget.setAuthorized([user], [false]);
+    expect(await budget.isAuthorized(user)).toBe(false);
+    expect(await budget.rolesOf(user)).not.toContain(Roles.MANAGER);
+  });
+});