@boostxyz/sdk 0.0.0-alpha.16 → 0.0.0-alpha.18

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

@@ -131,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,
@@ -174,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,
@@ -196,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.ts

@@ -0,0 +1,323 @@
+import {
+  rbacAbi,
+  readRbacHasAllRoles,
+  readRbacHasAnyRole,
+  readRbacIsAuthorized,
+  readRbacRolesOf,
+  simulateRbacGrantRoles,
+  simulateRbacRevokeRoles,
+  simulateRbacSetAuthorized,
+  writeRbacGrantRoles,
+  writeRbacRevokeRoles,
+  writeRbacSetAuthorized,
+} from '@boostxyz/evm';
+import type { Abi, Address, ContractEventName } from 'viem';
+import { DeployableTarget } from '../Deployable/DeployableTarget';
+import type { GenericLog, ReadParams, WriteParams } from '../utils';
+export { rbacAbi };
+
+/**
+ *  Enum representing available roles for use with the `RBAC` authorization scheme.
+ * `MANAGER` has lowest level of write permissions, for specific implementations, see Budgets and ALlowLists
+ * `ADMIN` can additionally manage authorized users on the contract.
+ *
+ * @export
+ * @type {{ readonly MANAGER: 1n; readonly ADMIN_ROLE: 2n; }}
+ * @enum {bigint}
+ */
+export enum Roles {
+  //@ts-expect-error ts doesn't like bigint enum values
+  MANAGER = 1n,
+  //@ts-expect-error ts doesn't like bigint enum values
+  ADMIN = 2n,
+}
+
+/**
+ * A generic `viem.Log` event with support for `Rbac` event types.
+ *
+ * @export
+ * @typedef {RBACLog}
+ * @template {ContractEventName<typeof rbacAbi>} [event=ContractEventName<
+ *     typeof rbacAbi
+ *   >]
+ */
+export type RBACLog<
+  event extends ContractEventName<typeof rbacAbi> = ContractEventName<
+    typeof rbacAbi
+  >,
+> = GenericLog<typeof rbacAbi, event>;
+
+/**
+ * A minimal RBAC implementation that offers MANAGER and ADMIN roles, and
+ * Budgets and allowlists support this auth scheme
+ *
+ * @export
+ * @class DeployableTargetWithRBAC
+ * @typedef {DeployableTargetWithRBAC}
+ * @extends {DeployableTarget<RbacPayload>}
+ */
+export class DeployableTargetWithRBAC<
+  Payload,
+  ABI extends Abi,
+> extends DeployableTarget<Payload, ABI> {
+  /**
+   * 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} [params]
+   * @returns {Promise<void>}
+   */
+  public async setAuthorized(
+    addresses: Address[],
+    allowed: boolean[],
+    params?: WriteParams<typeof rbacAbi, '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} [params]
+   * @returns {Promise<void>}
+   */
+  public async setAuthorizedRaw(
+    addresses: Address[],
+    allowed: boolean[],
+    params?: WriteParams<typeof rbacAbi, 'setAuthorized'>,
+  ) {
+    const { request, result } = await simulateRbacSetAuthorized(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 writeRbacSetAuthorized(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * Grant many accounts permissions on the rbac.
+   *
+   * @example
+   * ```ts
+   * await rbac.grantRoles(['0xfoo', '0xbar], [RbacRoles.MANAGER, RbacRoles.ADMIN])
+   * ```
+   * @public
+   * @async
+   * @param {Address[]} addresses
+   * @param {RbacRoles[]} roles
+   * @param {?WriteParams} [params]
+   * @returns {Promise<void>}
+   */
+  public async grantRoles(
+    addresses: Address[],
+    roles: Roles[],
+    params?: WriteParams<typeof rbacAbi, 'grantRoles'>,
+  ) {
+    return await this.awaitResult(this.grantRolesRaw(addresses, roles, params));
+  }
+
+  /**
+   * Grant many accounts permissions on the rbac.
+   *
+   * @example
+   * ```ts
+   * await rbac.grantRoles(['0xfoo', '0xbar], [Roles.MANAGER, Roles.ADMIN])
+   *
+   * @public
+   * @async
+   * @param {Address[]} addresses
+   * @param {RbacRoles[]} roles
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: void; }>}
+   */
+  public async grantRolesRaw(
+    addresses: Address[],
+    roles: Roles[],
+    params?: WriteParams<typeof rbacAbi, 'grantRoles'>,
+  ) {
+    const { request, result } = await simulateRbacGrantRoles(this._config, {
+      address: this.assertValidAddress(),
+      args: [addresses, roles],
+      ...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 writeRbacGrantRoles(
+      this._config,
+      // biome-ignore lint/suspicious/noExplicitAny: negligible low level lack of type intersection
+      request as any,
+    );
+    return { hash, result };
+  }
+
+  /**
+   * Revoke many accounts' permissions on the rbac.
+   *
+   * @example
+   * ```ts
+   * await rbac.revokeRoles(['0xfoo', '0xbar], [RbacRoles.MANAGER, RbacRoles.ADMIN])
+   *
+   * @public
+   * @async
+   * @param {Address[]} addresses
+   * @param {RbacRoles[]} roles
+   * @param {?WriteParams} [params]
+   * @returns {Promise<void>}
+   */
+  public async revokeRoles(
+    addresses: Address[],
+    roles: Roles[],
+    params?: WriteParams<typeof rbacAbi, 'revokeRoles'>,
+  ) {
+    return await this.awaitResult(
+      this.revokeRolesRaw(addresses, roles, params),
+    );
+  }
+
+  /**
+   * Revoke many accounts' permissions on the rbac.
+   *
+   * @example
+   * ```ts
+   * await rbac.revokeRoles(['0xfoo', '0xbar], [RbacRoles.MANAGER, RbacRoles.ADMIN])
+   * @public
+   * @async
+   * @param {Address[]} addresses
+   * @param {RbacRoles[]} roles
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: void; }>}
+   */
+  public async revokeRolesRaw(
+    addresses: Address[],
+    roles: Roles[],
+    params?: WriteParams<typeof rbacAbi, 'revokeRoles'>,
+  ) {
+    const { request, result } = await simulateRbacRevokeRoles(this._config, {
+      address: this.assertValidAddress(),
+      args: [addresses, roles],
+      ...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 writeRbacRevokeRoles(
+      this._config,
+      // biome-ignore lint/suspicious/noExplicitAny: negligible low level lack of type intersection
+      request as any,
+    );
+    return { hash, result };
+  }
+
+  /**
+   * Return an array of the roles assigned to the given account.
+   * @example
+   * ```ts
+   * (await rbac.rolesOf(0xfoo)).includes(RbacRoles.ADMIN)
+   * @public
+   * @param {Address} account
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Array<RbacRoles>>}
+   */
+  public async rolesOf(
+    account: Address,
+    params?: ReadParams<typeof rbacAbi, 'rolesOf'>,
+  ) {
+    const roles = await readRbacRolesOf(this._config, {
+      address: this.assertValidAddress(),
+      args: [account],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+    return ([Roles.MANAGER, Roles.ADMIN] as unknown as Array<bigint>).filter(
+      (role) => (roles & role) === role,
+    ) as unknown as Roles[];
+  }
+
+  /**
+   * Returns whether given account has any of the provided roles bitmap.
+   *
+   * @example
+   * ```ts
+   * await rbac.hasAnyRole(0xfoo, RbacRoles.ADMIN | RbacRoles.MANAGER)
+   * @public
+   * @param {Address} account
+   * @param {RbacRoles} roles
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>}
+   */
+  public hasAnyRole(
+    account: Address,
+    roles: Roles,
+    params?: ReadParams<typeof rbacAbi, 'hasAnyRole'>,
+  ) {
+    return readRbacHasAnyRole(this._config, {
+      address: this.assertValidAddress(),
+      args: [account, roles],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Returns whether given account has all of the provided roles bitmap.
+   *
+   * @example
+   * ```ts
+   * await rbac.hasAllRoles(0xfoo, RbacRoles.ADMIN & RbacRoles.MANAGER)
+   *
+   * @public
+   * @param {Address} account
+   * @param {RbacRoles} roles
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>}
+   */
+  public hasAllRoles(
+    account: Address,
+    roles: Roles,
+    params?: ReadParams<typeof rbacAbi, 'hasAllRoles'>,
+  ) {
+    return readRbacHasAllRoles(this._config, {
+      address: this.assertValidAddress(),
+      args: [account, roles],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Check if the given account is authorized to use the rbac
+   *
+   * @public
+   * @param {Address} account
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>} - True if the account is authorized
+   */
+  public isAuthorized(
+    account: Address,
+    params?: ReadParams<typeof rbacAbi, 'isAuthorized'>,
+  ) {
+    return readRbacIsAuthorized(this._config, {
+      address: this.assertValidAddress(),
+      args: [account],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+}

package/src/Incentives/AllowListIncentive.ts

@@ -112,8 +112,8 @@ export class AllowListIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'owner'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Address>}
    */
   public async owner(
     params?: ReadParams<typeof allowListIncentiveAbi, 'owner'>,
@@ -131,7 +131,7 @@ export class AllowListIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'claims'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async claims(
@@ -150,7 +150,7 @@ export class AllowListIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'reward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async reward(
@@ -170,7 +170,7 @@ export class AllowListIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'claimed'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>}
    */
   public async claimed(
@@ -190,7 +190,7 @@ export class AllowListIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'allowList'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<SimpleAllowList>}
    */
   public async allowList(
@@ -212,8 +212,8 @@ export class AllowListIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'limit'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
    */
   public async limit(
     params?: ReadParams<typeof allowListIncentiveAbi, 'limit'>,
@@ -231,7 +231,7 @@ export class AllowListIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Pick<ClaimPayload, 'target'>} payload
-   * @param {?WriteParams<typeof allowListIncentiveAbi, 'claim'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<true>} - return true if successful, otherwise revert
    */
   protected async claim(
@@ -247,8 +247,8 @@ export class AllowListIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Pick<ClaimPayload, 'target'>} payload
-   * @param {?WriteParams<typeof allowListIncentiveAbi, 'claim'>} [params]
-   * @returns {Promise<true>} - return true if successful, otherwise revert
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - return true if successful, otherwise revert
    */
   protected async claimRaw(
     payload: Pick<ClaimPayload, 'target'>,
@@ -274,7 +274,7 @@ export class AllowListIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Pick<ClaimPayload, 'target'>} payload
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'isClaimable'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>} - True if the incentive is claimable based on the data payload
    */
   public async isClaimable(

package/src/Incentives/CGDAIncentive.ts

@@ -164,8 +164,8 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'owner'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Address>}
    */
   public async owner(params?: ReadParams<typeof cgdaIncentiveAbi, 'owner'>) {
     return await readCgdaIncentiveOwner(this._config, {
@@ -181,7 +181,7 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'claims'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async claims(params?: ReadParams<typeof cgdaIncentiveAbi, 'claims'>) {
@@ -198,7 +198,7 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof allowListIncentiveAbi, 'reward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async reward(params?: ReadParams<typeof cgdaIncentiveAbi, 'reward'>) {
@@ -216,7 +216,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'claimed'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>}
    */
   public async claimed(
@@ -236,8 +236,8 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'asset'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Address>}
    */
   public async asset(params?: ReadParams<typeof cgdaIncentiveAbi, 'asset'>) {
     return await readCgdaIncentiveAsset(this._config, {
@@ -252,7 +252,7 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'cgdaParams'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<CGDAParameters>}
    */
   public async cgdaParams(
@@ -277,7 +277,7 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'totalBudget'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async totalBudget(
@@ -296,7 +296,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof cgdaIncentiveAbi, 'claim'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - Returns true if successfully claimed
    */
   protected async claim(
@@ -312,7 +312,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof cgdaIncentiveAbi, 'claim'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - Returns true if successfully claimed
    */
   protected async claimRaw(
@@ -336,7 +336,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof cgdaIncentiveAbi, 'clawback'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
    */
   public async clawback(
@@ -352,7 +352,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof cgdaIncentiveAbi, 'clawback'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
    */
   public async clawbackRaw(
@@ -379,7 +379,7 @@ export class CGDAIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'isClaimable'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>} - True if the incentive is claimable based on the data payload
    */
   public async isClaimable(
@@ -401,7 +401,7 @@ export class CGDAIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof cgdaIncentiveAbi, 'currentReward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>} - The current reward
    */
   public async currentReward(