Permission

Query user permissions and role grants on contracts.

import { Client, Permission, ADMIN_ROLE, HOST_ROLE, DOOR_ROLE, MINTER_ROLE } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })

Try It

Permission Namespace Demo

Query user permissions and role grants on contracts. Roles include ADMIN, HOST, DOOR, and MINTER with bitmask-based access control.

SQL endpoint URL

Contract address

Query

User address

Get permission record for a user on a contract.

await client.permission.get({
  contractAddress,
  user,
})

Browser requests require CORS to be enabled.

Results

Methods

get

Get a permission record for a specific user on a contract.

import { Client, Permission } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const permission = await client.permission.get({
  contractAddress: '0x1234567890123456789012345678901234567890' as const,
  user: '0x2345678901234567890123456789012345678901' as const
})
 
if (permission) {
  // Decode the role bitmask
  const roles = Permission.decodeRoles(permission.roles)
  console.log('Admin:', roles.admin)
  console.log('Host:', roles.host)
  console.log('Door:', roles.door)
  console.log('Minter:', roles.minter)
}

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`user`	`Address`	The user address

Returns

Permission | null - The permission record or null if not found.

hasRole

Check if a user has a specific role on a contract.

import { Client, ADMIN_ROLE, HOST_ROLE, DOOR_ROLE, MINTER_ROLE } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
// Check admin role
const isAdmin = await client.permission.hasRole({
  contractAddress: '0x1234567890123456789012345678901234567890',
  user: '0x2345678901234567890123456789012345678901',
  role: ADMIN_ROLE
})
 
// Check door role (check-in capability)
const canCheckIn = await client.permission.hasRole({
  contractAddress: '0x1234567890123456789012345678901234567890',
  user: '0x2345678901234567890123456789012345678901',
  role: DOOR_ROLE
})

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`user`	`Address`	The user address
`role`	`bigint`	The role to check (e.g., `ADMIN_ROLE`)

Returns

boolean - True if the user has the role.

listByContract

List all permission records for a contract.

import { Client, Permission } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const permissions = await client.permission.listByContract({
  contractAddress: '0x1234567890123456789012345678901234567890',
  limit: 50
})
 
for (const perm of permissions) {
  const roles = Permission.decodeRoles(perm.roles)
  console.log(`${perm.userAddress}:`, roles)
}

Parameters

Parameter	Type	Default	Description
`contractAddress`	`Address`	required	The contract address
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

Permission[] - Array of permission records.

listByUser

List all contracts where a user has roles.

import { Client, Permission } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const permissions = await client.permission.listByUser({
  user: '0x2345678901234567890123456789012345678901',
  limit: 50
})
 
for (const perm of permissions) {
  const roles = Permission.decodeRoles(perm.roles)
  console.log(`Contract ${perm.contractAddress}:`, roles)
}

Parameters

Parameter	Type	Default	Description
`user`	`Address`	required	The user address
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

Permission[] - Array of permission records.

listByRole

List users with a specific role on a contract.

import { Client, ADMIN_ROLE, DOOR_ROLE } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
// Find all admins
const admins = await client.permission.listByRole({
  contractAddress: '0x1234567890123456789012345678901234567890',
  role: ADMIN_ROLE
})
 
for (const perm of admins) {
  console.log('Admin:', perm.userAddress)
}
 
// Find all door staff
const doorStaff = await client.permission.listByRole({
  contractAddress: '0x1234567890123456789012345678901234567890',
  role: DOOR_ROLE
})

Parameters

Parameter	Type	Default	Description
`contractAddress`	`Address`	required	The contract address
`role`	`bigint`	required	The role to filter by
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

Permission[] - Array of permission records for users with the role.

Utility Functions

Permission.decodeRoles

Decode a role bitmask into individual role flags.

import { Client, Permission } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const contractAddress = '0x1234567890123456789012345678901234567890'
const user = '0x2345678901234567890123456789012345678901'
 
const permission = await client.permission.get({ contractAddress, user })
 
if (permission) {
  const roles = Permission.decodeRoles(permission.roles)
 
  // Returns:
  // {
  //   admin: boolean,
  //   host: boolean,
  //   door: boolean,
  //   minter: boolean
  // }
 
  if (roles.admin) {
    console.log('User is an admin')
  }
}

Permission.hasRoleInMask

Check if a bitmask contains a specific role.

import { Client, Permission, ADMIN_ROLE, HOST_ROLE } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const permission = await client.permission.get({
  contractAddress: '0x1234567890123456789012345678901234567890', 
  user: '0x2345678901234567890123456789012345678901'
})
 
if (permission) {
  const hasAdmin = Permission.hasRoleInMask(permission.roles, ADMIN_ROLE)
  const hasHost = Permission.hasRoleInMask(permission.roles, HOST_ROLE)
}

Permission.combineRoles

Combine multiple roles into a single bitmask.

import { Permission, ADMIN_ROLE, HOST_ROLE, MINTER_ROLE } from '@sceneinfrastructure/sdk'
 
// Grant admin and minter roles
const roles = Permission.combineRoles([ADMIN_ROLE, MINTER_ROLE])
// roles = 9n (ADMIN=1 | MINTER=8)

Types

Permission

 
import type { Address, Hex } from 'viem'
 
type Permission = {
  contractAddress: Address
  userAddress: Address
  roles: bigint  // Role bitmask
  createdAt: bigint
  createdAtBlock: bigint
  createdAtLogIndex: number
  creationTxHash: Hex
  updatedAt: bigint
  updatedAtBlock: bigint
  updatedAtLogIndex: number
  updatedTxHash: Hex | null
}

Field	Type	Description
`contractAddress`	`Address`	The contract address
`userAddress`	`Address`	The user address
`roles`	`bigint`	Bitmask of granted roles

DecodedRoles

type DecodedRoles = {
  admin: boolean   // ADMIN_ROLE = 1
  host: boolean    // HOST_ROLE = 2
  door: boolean    // DOOR_ROLE = 4
  minter: boolean  // MINTER_ROLE = 8
}

Role Constants

import { ADMIN_ROLE, HOST_ROLE, DOOR_ROLE, MINTER_ROLE } from '@sceneinfrastructure/sdk'
 
// Values:
// ADMIN_ROLE  = 1n  (0x01) - Full contract control
// HOST_ROLE   = 2n  (0x02) - Event management
// DOOR_ROLE   = 4n  (0x04) - Check-in capability
// MINTER_ROLE = 8n  (0x08) - Token minting

Role Capabilities

Role	Value	Capabilities
`ADMIN_ROLE`	`1n`	Full control, grant/revoke roles
`HOST_ROLE`	`2n`	Manage event settings
`DOOR_ROLE`	`4n`	Check in attendees (stub tickets)
`MINTER_ROLE`	`8n`	Mint new tokens

Schema

Zod Validation

import { Permission } from '@sceneinfrastructure/sdk'
 
const data = {} // Data from API or external source
 
const result = Permission.schema.safeParse(data)
 
if (result.success) {
  console.log('Valid permission:', result.data)
}