@fairmint/ocp-equity-certificate

Chainable SDK for deploying and minting OCP Equity Certificate soulbound NFTs on Base.

Install

npm install @fairmint/ocp-equity-certificate viem

Quick start

import { createPublicClient, createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { EquityCertificateFactory } from '@fairmint/ocp-equity-certificate';

const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({
  chain: base,
  transport: http(),
  account: transferAgentAccount,
});

const factory = new EquityCertificateFactory({ publicClient, walletClient });

// Deploy a per-issuer certificate contract
const cert = await factory.deploy(issuerId);

// Mint a soulbound token
const token = await cert.mint({ to: shareholderWallet, stakeholderId, securityId });

console.log(cert.address, cert.txHash, token.tokenId);

API

EquityCertificateFactory

Created with a viem PublicClient + WalletClient (wallet must have an account configured).

const factory = new EquityCertificateFactory({ publicClient, walletClient });

factory.deploy(issuerId, options?)

Deploy an EquityCertificate BeaconProxy via the on-chain factory. Computes the CREATE2 salt from the issuer ID, sends the transaction, waits for the receipt, and extracts the proxy address from the EquityCertificateDeployed event.

Returns a DeployResult — an EquityCertificateContract enriched with txHash and salt.

const cert = await factory.deploy('issuer-uuid', { timeout: 50_000 });
cert.address; // deployed proxy address
cert.txHash;  // deploy transaction hash
cert.salt;    // CREATE2 salt used

factory.attach(address)

Wrap an already-deployed EquityCertificate proxy so you can call .mint().

const cert = factory.attach('0x...');

factory.computeAddress(issuerId)

Precompute the CREATE2 proxy address without deploying.

const address = await factory.computeAddress('issuer-uuid');

EquityCertificateContract

Returned by factory.deploy() and factory.attach(). Has one method:

cert.mint(options)

Mint a soulbound equity certificate to a shareholder wallet. Computes the position hash from stakeholder + security IDs, sends the transaction, waits for the receipt, and extracts tokenId from the EquityCertificateMinted event.

const token = await cert.mint({
  to: '0x...',          // shareholder wallet
  stakeholderId: '...', // OCF stakeholder ID
  securityId: '...',    // OCF security ID
  timeout: 50_000,      // optional, defaults to 60s
});
token.tokenId;      // bigint
token.txHash;       // transaction hash
token.positionHash; // keccak256(stakeholderId + ":" + securityId)

Hash utilities

import { issuerSalt, positionHash } from '@fairmint/ocp-equity-certificate';

const salt = issuerSalt(issuerId);                       // keccak256(toHex(issuerId))
const hash = positionHash(stakeholderId, securityId);    // keccak256(toHex(stakeholderId + ":" + securityId))

Error helpers

import { isAlreadyDeployedError } from '@fairmint/ocp-equity-certificate';

try {
  await factory.deploy(issuerId);
} catch (err) {
  if (isAlreadyDeployedError(err)) {
    const existing = factory.attach(await factory.computeAddress(issuerId));
    // continue with existing contract...
  } else {
    throw err;
  }
}

Address utilities

import { getFactoryAddress, isSupportedChain } from '@fairmint/ocp-equity-certificate';

if (isSupportedChain(chainId)) {
  const addr = getFactoryAddress(chainId);
}

Low-level building blocks

For consumers who need direct contract access, the package also exports all ABIs, bytecode, and deployment addresses as as const TypeScript:

import {
  equityCertificateAbi,
  equityCertificateFactoryAbi,
  equityCertificateBytecode,
  equityCertificateFactoryBytecode,
  equityCertificateAddresses,
} from '@fairmint/ocp-equity-certificate';

Types

| Type | Description | | --- | --- | | EquityCertificateContract | Certificate proxy — has .address and .mint() | | DeployResult | Extends EquityCertificateContract with .txHash and .salt | | MintResult | { tokenId, txHash, positionHash } | | MintOptions | { to, stakeholderId, securityId, timeout? } | | EquityCertificateChainId | Union of supported chain IDs | | EquityCertificateNetwork | Union of supported network names | | EquityCertificateDeployment | Deployment addresses for a network |