Organigram JS

Organigram JS is the JavaScript/TypeScript client for the Organigram Protocol, a suite of smart contracts for running organizations on Ethereum-compatible blockchains. It deploys, reads and operates those contracts from any JavaScript environment, browser or Node.js, and is the library used under the hood by Organigram.ai and by @organigram/react.

Installation

viem is a peer dependency: Organigram JS never holds keys itself, it uses the viem clients you give it.

How it works

An organization is modelled as an organigram: a set of organs connected by procedures, optionally holding assets. Each of them is a smart contract, and each has a class in this library that loads its on-chain state, writes to it, and serializes it to JSON.

The client

OrganigramClient.load() connects to the OrganigramClient contract deployed on the chain of your viem public client, and reads the procedure types registered there. The public client is used for every read; the wallet client, when provided, signs the transactions. Without a wallet client, the library is read-only.

The client keeps loaded organs, procedures and assets in memory: loadOrgan(), loadProcedure() and loadAsset() return the cached object unless you pass { fresh: true }.

Organs and permissions

An organ stores three things:

• entries: each one an Ethereum address (a member) or a content reference (a document), or both;
• permissions: which addresses may act on the organ, as a bit field from PERMISSIONS (ADD_ENTRIES, WITHDRAW_ETHER, ADD_PERMISSIONS…). getPermissionsSet() turns a value back into names;
• assets: ether and ERC-20 tokens, which only addresses with the matching permission can withdraw.

In a governed organization, permissions are granted to procedures rather than to people, so that every change goes through a decision.

Proposals and decisions

A procedure names three roles, each held by the members of an organ (or, for an ERC-20 vote, by the token holders): the proposers who may submit proposals, the moderators who may filter them when moderation is enabled, and the deciders who adopt or reject them. A proposal is a list of operations, calls to organs that the procedure has permission to make, plus a reference to its off-chain metadata.

1. propose() submits the proposal.
2. With moderation, a moderator either accepts it with presentProposal() or rejects it with blockProposal().
3. The deciders decide: nominate() or reject() for a nomination, vote() then count() once the vote is over for the vote procedures.
4. Adoption executes the operations on the target organs. applyProposal() retries the operations that were not processed yet.

Every write also exists as a …BySig variant: the user signs an EIP-712 message and any relayer submits it, so users do not need gas.

Deploying an organigram

organigram.deploy() deploys organs, assets and procedures in one transaction, then loads them back from the chain. Under the hood it calls client.deployOrganigram(), which you can call directly when you only need the new addresses. Contracts are deployed as clones at addresses predicted from a salt, which lets a draft reference contracts that do not exist yet, for example a procedure deciding on an organ deployed in the same batch. templates provides ready-made organigrams (sas, sarl, nonProfit, openSource…), and isTemplateSupportedOnChain() tells whether a chain has the contracts a template needs.

Off-chain storage

Contracts only store references. Metadata and documents live off-chain and are referenced by CID refs of the form og://workspace/<workspace>/<key>, built with formatCidRef() and read with parseCidRef(). Proposals must carry such a reference.

The encryption helpers (generateUserEncryptionKeyPair, wrapGroupKeyForRecipient, encryptBytes…) implement the end-to-end encryption of documents used by Organigram.ai: content keys encrypt documents, group keys wrap content keys, and each member's key pair unwraps group keys. They run on the Web Crypto API of the user's device. Keep private keys there: never send them to a server, never log them, and only export them to a storage you encrypt yourself.

Usage

Connect to the protocol with a browser wallet:

Deploy an organization from a template:

Propose to add a member to an organ, then adopt the proposal through a nomination procedure:

The procedure must hold the ADD_ENTRIES permission on the organ, and the connected account must belong to its proposers and deciders.

Contributing

We are looking for TypeScript developers and testers to keep this project secure and up to date. Please open issues on GitHub, fork the repository and send pull requests.

Client

Everything starts with an OrganigramClient, connected to the protocol on one chain through two viem clients: a public client to read, and a wallet client to sign. Without a wallet client, the library is read-only. The client deploys contracts, loads them, and keeps what it loaded in cache until you ask for a fresh read. Every write accepts TransactionOptions, to follow a transaction as soon as it is sent.

OrganigramClient

Definition

constructor(input: {

publicClient: PublicClient;

address?: string;

chainId?: string;

procedureTypes?: ProcedureType[];

contract?: OrganigramContract;

walletClient?: WalletClient;

});

OrganigramClient.deployAsset

Deploy a single ERC-20 asset clone.

Signature

deployAsset(input: {

name: string;

symbol: string;

initialSupply?: number;

salt?: string;

options?: TransactionOptions;

}): Promise<string>;

Parameters

Name	Type	Description
input	{ name: string; symbol: string; initialSupply?: number; salt?: string; options?: TransactionOptions; }	Token name and symbol, supply in whole tokens before conversion to wei, optional deterministic clone salt and transaction controls.

Returns

Type	Description
Promise<string>	The address of the deployed asset contract.

OrganigramClient.deployAssets

Deploy several assets in one batch transaction.

Signature

deployAssets(assets: AssetInput[], options?: TransactionOptions): Promise<string[]>;

Parameters

Name	Type	Description
assets	AssetInput[]	Assets to deploy.
options	TransactionOptions	Optional transaction controls.

Returns

Type	Description
Promise<string[]>	The deployed asset addresses in deployment order.

OrganigramClient.deployClient

Deploy a fresh Organigram client contract together with its linked library.

Signature

static deployClient(input: {

publicClient: PublicClient;

walletClient: WalletClient;

}): Promise<OrganigramClient>;

Parameters

Name	Type	Description
input	{ publicClient: PublicClient; walletClient: WalletClient; }	Clients used to broadcast deployments and wait for receipts.

Returns

Type	Description
Promise<OrganigramClient>	A ready-to-use SDK instance pointing at the newly deployed client.

OrganigramClient.deployOrgan

Deploy a single organ clone and hydrate the resulting SDK object.

When no permissions are provided, the connected wallet is granted the full admin bitmask by default so the organ remains operable after deployment.

Signature

deployOrgan(input?: DeployOrganInput): Promise<Organ>;

Parameters

Name	Type	Description
input	DeployOrganInput	Optional organ metadata, permissions, entries, and transaction options.

OrganigramClient.deployOrganigram

Deploy a full organigram, including its organs, assets, and procedures.

Signature

deployOrganigram(input: DeployOrganigramInput): Promise<DeployOrganigramResult>;

Parameters

Name	Type	Description
input	DeployOrganigramInput	Batch deployment input for the whole organigram.

Returns

Type	Description
Promise<DeployOrganigramResult>	The deployed organ, asset, and procedure addresses, and the input updated with them. Use Organigram.deploy() to get a loaded Organigram.

OrganigramClient.deployOrgans

Deploy several organs in one batch transaction.

Signature

deployOrgans(deployOrgansInput: DeployOrganInput[]): Promise<Organ[]>;

Parameters

Name	Type	Description
deployOrgansInput	DeployOrganInput[]	Organ definitions to deploy.

OrganigramClient.deployProcedure

Deploy a single procedure clone from one registered procedure type.

Signature

deployProcedure(input: DeployProcedureInput): Promise<Procedure>;

Parameters

Name	Type	Description
input	DeployProcedureInput	Procedure type, role organs, optional metadata, and initialization args.

OrganigramClient.deployProcedures

Deploy several procedures in one batch transaction.

Signature

deployProcedures(deployProceduresInput: DeployProcedureInput[]): Promise<Procedure[]>;

Parameters

Name	Type	Description
deployProceduresInput	DeployProcedureInput[]	Procedure definitions to deploy.

OrganigramClient.estimateDeployOrganigramGas

Estimate the gas a full organigram deployment would use, without a wallet.

Signature

estimateDeployOrganigramGas(input: DeployOrganigramInput, account: string): Promise<bigint>;

Parameters

Name	Type	Description
input	DeployOrganigramInput	Batch deployment input for the whole organigram.
account	string	Address the deployment would be sent from.

Returns

Type	Description
Promise<bigint>	The estimated gas, or 0n when nothing remains to deploy.

OrganigramClient.getProcedureType

Infer the registered procedure type of a deployed procedure clone.

Signature

getProcedureType(procedureAddress: string): Promise<ProcedureType | null>;

Parameters

Name	Type	Description
procedureAddress	string	Address of the deployed procedure instance.

OrganigramClient.load

Connect the SDK to an already deployed Organigram client contract.

Signature

static load(input: {

address?: string;

publicClient: PublicClient;

walletClient?: WalletClient;

}): Promise<OrganigramClient>;

Parameters

Name	Type	Description
input	{ address?: string; publicClient: PublicClient; walletClient?: WalletClient; }	Address override plus the viem clients used for reads and writes.

OrganigramClient.loadAsset

Load one deployed asset and keep it in the client cache.

Signature

loadAsset(address: string, input?: {

fresh?: boolean;

initial?: Asset;

}): Promise<Asset>;

Parameters

Name	Type	Description
address	string	Asset contract address.
input	{ fresh?: boolean; initial?: Asset; }	fresh reads the chain even when the asset is cached; initial holds fallback metadata merged into the loaded asset.

OrganigramClient.loadContract

Attempt to load one deployed contract as an organ or procedure.

Signature

loadContract(address: string, input?: {

fresh?: boolean;

}): Promise<Organ | Procedure | null>;

Parameters

Name	Type	Description
address	string	Contract address to inspect.
input	{ fresh?: boolean; }	fresh reads the chain even when the contract is cached.

OrganigramClient.loadContracts

Load a heterogeneous list of deployed contract addresses into an organigram.

Signature

loadContracts(contractAddresses: string[]): Promise<Organigram>;

Parameters

Name	Type	Description
contractAddresses	string[]	Addresses to resolve as organs, procedures, or assets.

OrganigramClient.loadOrgan

Load one deployed organ and keep it in the client cache.

Signature

loadOrgan(address: string, input?: {

fresh?: boolean;

initial?: OrganInput;

}): Promise<Organ>;

Parameters

Name	Type	Description
address	string	Organ contract address.
input	{ fresh?: boolean; initial?: OrganInput; }	fresh reads the chain even when the organ is cached; initial holds fallback metadata merged into the loaded organ.

OrganigramClient.loadOrganigram

Hydrate every deployed object referenced by an organigram definition.

Undeployed placeholders are preserved as-is, while deployed organs, procedures, and assets are refreshed from chain state.

Signature

loadOrganigram(organigram: Organigram, input?: {

fresh?: boolean;

}): Promise<Organigram>;

Parameters

Name	Type	Description
organigram	Organigram	Organigram definition to hydrate.
input	{ fresh?: boolean; }	fresh: false reuses the organs, procedures and assets already in the client cache instead of reading them again.

OrganigramClient.loadProcedure

Load one deployed procedure and keep it in the client cache.

Signature

loadProcedure(address: string, input?: {

fresh?: boolean;

initial?: ProcedureInput;

}): Promise<Procedure>;

Parameters

Name	Type	Description
address	string	Procedure contract address.
input	{ fresh?: boolean; initial?: ProcedureInput; }	fresh reads the chain even when the procedure is cached; initial holds fallback metadata merged into the loaded procedure.

OrganigramClient.loadProcedureType

Load metadata for one deployed procedure implementation.

Signature

static loadProcedureType(input: {

addr: string;

cid?: string;

}, publicClient: PublicClient): Promise<ProcedureType>;

Parameters

Name	Type	Description
input	{ addr: string; cid?: string; }	Address and optional CID used to identify the procedure type.
publicClient	PublicClient	Read-only client used for interface checks.

OrganigramClient.loadProcedureTypes

Read the procedure registry and resolve every supported procedure type.

Signature

static loadProcedureTypes(input: {

publicClient: PublicClient;

address?: string;

}): Promise<ProcedureType[]>;

Parameters

Name	Type	Description
input	{ publicClient: PublicClient; address?: string; }	Optional client contract address and the public client used to query it.

DeployOrganigramInput

TransactionOptions

TransactionOptions.onTransaction

Called with the transaction as soon as it is sent, before it is mined.

Signature

onTransaction?: (tx: OrganigramTransaction, description: string) => void;

DeployOrganInput

Definition

export type DeployOrganInput = OrganInput & {

options?: TransactionOptions;

};

DeployProcedureInput

Definition

export type DeployProcedureInput = ProcedureInput & {

typeName: ProcedureTypeName;

options?: TransactionOptions;

args?: unknown[];

};

DeployOrganigramResult

Definition

export type DeployOrganigramResult = readonly [

organs: string[],

assets: string[],

procedures: string[]

] & {

organigram: DeployOrganigramInput;

};

ContractClients

Definition

export type ContractClients = {

publicClient: PublicClient;

walletClient?: WalletClient | null;

};

OrganigramContract

Definition

export type OrganigramContract = GetContractReturnType<Abi, PublicClient | {

public: PublicClient;

wallet: WalletClient;

}>;

OrganigramTransaction

Definition

export type OrganigramTransaction = {

hash: Hex;

wait: () => Promise<OrganigramTransactionReceipt>;

};

OrganigramTransactionReceipt

Definition

export type OrganigramTransactionReceipt = TransactionReceipt & {

gasPrice?: bigint | null;

};

bufferEstimatedGas

Signature

bufferEstimatedGas: (estimatedGas: bigint) => bigint

createContractWriteTransaction

Signature

createContractWriteTransaction: <TAbi extends Abi | readonly unknown[]>(input: {

address: string;

abi: TAbi;

functionName: string;

args?: unknown[];

clients: ContractClients;

nonce?: number;

value?: bigint;

}) => Promise<OrganigramTransaction>

getWalletAddress

Signature

getWalletAddress: (walletClient: WalletClient) => Promise<Address>

Organigrams and templates

An Organigram gathers the organs, procedures and assets of one organization. Start from a template with getTemplate(), or from your own data, attach a client, and deploy everything in one transaction with organigram.deploy(). Contracts are clones at addresses predicted from a salt, so that a draft can reference contracts that do not exist yet.

Organigram

The organigram itself has no contract. Create one from a template or from data, attach an OrganigramClient, then call deploy().

Definition

constructor(input?: OrganigramInput | keyof typeof templates | string[]);

Organigram.deploy

Deploy every contract of the organigram in one transaction, then read them back from chain.

Requires an attached organigramClient with a wallet client.

Signature

deploy(): Promise<Organigram>;

Organigram.editDetails

Change the name, description or diagram layout.

Signature

editDetails(input: {

name?: string;

description?: string;

edgeType?: OrganigramEdgeType;

nodePositions?: OrganigramNodePositions;

contractAddresses?: string[];

}): void;

Organigram.load

Read every deployed organ, procedure and asset of the organigram from chain.

Signature

load: (input?: {

walletClient?: WalletClient | null;

publicClient?: PublicClient | null;

}) => Promise<Organigram>;

Organigram.setAssets

Replace the assets.

Signature

setAssets(assets: Asset[]): void;

Organigram.setOrgans

Replace the organs.

Signature

setOrgans(organs: Organ[]): void;

Organigram.setProcedures

Replace the procedures.

Signature

setProcedures(procedures: Procedure[]): void;

Organigram.toJson

Convert the organigram into plain JSON.

Signature

toJson: () => OrganigramJson;

OrganigramEdgeType

Definition

export type OrganigramEdgeType = (typeof organigramEdgeTypes)[number];

OrganigramInput

Definition

export type OrganigramInput = {

id?: string | null;

slug?: string | null;

name?: string | null;

description?: string | null;

edgeType?: string | null;

nodePositions?: unknown;

chainId?: string | null;

organs: OrganInput[];

procedures: ProcedureInput[];

assets: AssetInput[];

organigramClient?: OrganigramClient | null;

walletClient?: WalletClient | null;

publicClient?: PublicClient | null;

contractAddresses?: string[] | null;

workspaceId?: string | null;

};

OrganigramJson

Definition

export type OrganigramJson = {

id: string;

slug: string;

name: string;

description: string;

edgeType: OrganigramEdgeType;

nodePositions: OrganigramNodePositions;

chainId: string;

organs: OrganJson[];

procedures: ProcedureJson[];

assets: AssetJson[];

workspaceId?: string | null;

};

OrganigramNodePosition

Definition

export type OrganigramNodePosition = {

x: number;

y: number;

};

OrganigramNodePositions

Definition

export type OrganigramNodePositions = Record<string, OrganigramNodePosition>;

ProcedureRoleTypeName

Definition

export type ProcedureRoleTypeName = 'proposers' | 'moderators' | 'deciders';

defaultChainId

Definition

const defaultChainId: string

defaultOrganigramEdgeType

Definition

const defaultOrganigramEdgeType: OrganigramEdgeType

organigramEdgeTypes

Definition

const organigramEdgeTypes: readonly ["default", "straight", "step", "smoothstep"]

TemplateName

Definition

export type TemplateName = keyof typeof templates;

getTemplate

Signature

getTemplate: (templateName: TemplateName, chainId: string) => OrganigramInput

isTemplateSupportedOnChain

Signature

isTemplateSupportedOnChain: (templateName: TemplateName, chainId: string) => boolean

renewSaltsAndAddresses

Signature

renewSaltsAndAddresses: (organigram: OrganigramInput, chainId: string) => OrganigramInput

templates

Organs

An organ is a group: a registry of entries, each a member, a document or both, a list of permissions, and a balance of assets. Each change requires a permission from PERMISSIONS. In a governed organization, those permissions belong to procedures rather than to people, so that every change goes through a decision.

Organ

Every change to an organ must come from an address holding the matching permission. In a governed organization, that address is a procedure, so that each change goes through a decision.

Definition

constructor(input: OrganInput);

Organ.addEntries

Add members or documents to the registry.

Signature

addEntries: (entries: OrganEntryInput[], options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.addPermission

Grant permissions to an address.

Signature

addPermission: (permission: OrganPermission, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.checkAddressPermissions

Read the permission flags an address holds on an organ.

Signature

static checkAddressPermissions(organAddress: string, addressToCheck: string, clients: ContractClients): Promise<number>;

Organ.getBalance

Read the ether balance of an organ, in wei.

Signature

static getBalance(address: string, clients: ContractClients): Promise<bigint>;

Organ.isOrgan

Tell whether a contract is an organ.

Signature

static isOrgan(address: string, clients: ContractClients): Promise<boolean>;

Organ.load

Read an organ from chain: its entries, permissions and metadata.

Signature

static load(address: string, clients: ContractClients, initialOrgan?: OrganInput): Promise<Organ>;

Organ.loadData

Read the metadata reference and registry sizes of an organ.

Signature

static loadData(address: string, clients: ContractClients): Promise<OrganContractData>;

Organ.loadEntries

Read every entry of an organ.

Signature

static loadEntries(address: string, clients: ContractClients, data?: OrganContractData): Promise<OrganEntry[]>;

Organ.loadEntry

Read one entry of an organ, by index.

Signature

static loadEntry(address: string, index: string, clients: ContractClients): Promise<OrganEntry>;

Organ.loadEntryForAccount

Find the entry of an address in an organ, if it is a member.

Signature

static loadEntryForAccount(address: string, account: string, clients: ContractClients): Promise<OrganEntry | undefined>;

Organ.loadPermission

Read one permission of an organ, by index.

Signature

static loadPermission(address: string, index: string, clients: ContractClients): Promise<OrganPermission>;

Organ.loadPermissions

Read every permission of an organ.

Signature

static loadPermissions(address: string, clients: ContractClients, data?: OrganContractData): Promise<OrganPermission[]>;

Organ.populateTransaction

Encode a call to an organ function, to use it as a proposal operation with Procedure.createOperation().

Signature

static populateTransaction(address: string, walletClient: WalletClient, functionName: OrganFunctionName | string, ...args: unknown[]): Promise<{

to: string;

data: string;

functionName: string;

}>;

Organ.reload

Read the whole organ again from chain.

Signature

reload(): Promise<Organ>;

Organ.reloadData

Read the metadata reference again from chain.

Signature

reloadData(): Promise<Organ>;

Organ.reloadEntries

Read the entries again from chain.

Signature

reloadEntries(): Promise<Organ>;

Organ.reloadPermissions

Read the permissions again from chain.

Signature

reloadPermissions(): Promise<Organ>;

Organ.removeEntries

Remove entries from the registry, by index.

Signature

removeEntries: (indexes: string[], options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.removePermission

Revoke every permission of an address.

Signature

removePermission: (permission: string, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.replaceEntry

Replace one entry of the registry.

Signature

replaceEntry: (index: number, entry: OrganEntryInput, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.replacePermission

Move permissions from one address to another.

Signature

replacePermission: (oldPermissionAddress: string, newOrganPermission: OrganPermission, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.toJson

Convert the organ into plain JSON.

Signature

toJson: () => OrganJson;

Organ.updateCid

Replace the reference to the off-chain metadata of the organ.

Signature

updateCid: (cid: string, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.withdrawERC20

Send ERC-20 tokens held by the organ.

Signature

withdrawERC20: (token: string, to: string, amount: string | number | bigint, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.withdrawERC721

Send an ERC-721 token held by the organ.

Signature

withdrawERC721: (token: string, to: string, tokenId: string | number | bigint, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

Organ.withdrawEther

Send ether held by the organ.

Signature

withdrawEther: (to: string, value: string | number | bigint, options?: TransactionOptions) => Promise<OrganigramTransactionReceipt>;

OrganEntry

OrganEntryInput

OrganInput

OrganJson

OrganPermission

OrganFunctionName

getPermissionsSet

Signature

getPermissionsSet: (permissions: number) => string[]

PERMISSIONS

Procedures and proposals

A procedure lets the members of some organs change other organs. Proposers submit a proposal, a list of operations built with Procedure.createOperation(). With moderation, a moderator presents or blocks it. Deciders then adopt or reject it, alone in a NominationProcedure, by vote in a VoteProcedure, or by token-weighted vote in an ERC20VoteProcedure, and adoption runs the operations. Every action also exists as a signed variant: the user signs with a sign… method, and any account submits the signature with the matching …BySig method, so that users need no gas.

Procedure

A proposal is a list of operations. Proposers submit it with propose(). With moderation, a moderator presents it with presentProposal() or blocks it with blockProposal(). Deciders then adopt or reject it, depending on the procedure type, and adoption runs its operations. Every action also has a signed variant (sign… then …BySig), so that a relayer submits it and users need no gas.

Definition

constructor(input: ProcedureInput);

Procedure.applyProposal

Settle a proposal: for a vote, count the ballots once it is over, then run or close it.

Signature

applyProposal(proposalKey: string, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.applyProposalBySig

Settle a proposal, with an application signed by another account.

Signature

applyProposalBySig(input: SignedProposalActionInput & {

signature: string;

}, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.blockProposal

Block a proposal as a moderator, before its decision.

Signature

blockProposal(proposalKey: string, reason: string, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.blockProposalBySig

Block a proposal signed by a moderator.

Signature

blockProposalBySig(input: SignedBlockProposalInput & {

signature: string;

}, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.createExternalCallOperation

Build an operation that makes an organ call a contract outside the organization.

Signature

static createExternalCallOperation(input: ExternalCallOperationInput): ProcedureProposalOperation;

Procedure.createOperation

Turn a contract call, such as the result of Organ.populateTransaction(), into a proposal operation.

Signature

static createOperation(input: {

to: string;

data: string;

value?: number | string | bigint;

index?: number | string;

}): ProcedureProposalOperation;

Procedure.getClients

The viem clients of the procedure.

Signature

protected getClients(): ContractClients;

Procedure.getNonce

Read the next signature nonce of an account.

Signature

getNonce(account: string): Promise<bigint>;

Procedure.getTypedDataDomain

EIP-712 domain of the signatures of this procedure.

Signature

getTypedDataDomain(): {

name: string;

version: string;

chainId: bigint;

verifyingContract: `0x${string}`;

};

Procedure.isProcedure

Tell whether a contract is a procedure.

Signature

static isProcedure(address: string, clients: ContractClients): Promise<boolean>;

Procedure.load

Read a procedure from chain, with its proposals.

Signature

static load(address: string, clients: ContractClients, initialProcedure?: ProcedureInput): Promise<Procedure>;

Procedure.loadData

Read the roles, metadata reference and proposal count of a procedure.

Signature

static loadData(address: string, clients: ContractClients): Promise<ProcedureContractData>;

Procedure.loadProposal

Read one proposal of a procedure.

Signature

static loadProposal(address: string, proposalKey: string, clients: ContractClients): Promise<ProcedureProposal>;

Procedure.loadProposals

Read every proposal of a procedure.

Signature

static loadProposals(address: string, clients: ContractClients, data?: ProcedureContractData): Promise<ProcedureProposal[]>;

Procedure.parseOperation

Normalize an operation read from chain.

Signature

static parseOperation(rawOperation: unknown): ProcedureProposalOperation;

Procedure.presentProposal

Present a proposal to the deciders, as a moderator.

Signature

presentProposal(proposalKey: string, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.presentProposalBySig

Present a proposal signed by a moderator.

Signature

presentProposalBySig(input: SignedProposalActionInput & {

signature: string;

}, options?: TransactionOptions): Promise<OrganigramTransactionReceipt>;

Procedure.propose

Submit a proposal.

Signature

propose(input: {

cid: string;

operations: ProcedureProposalOperation[];

options?: TransactionOptions;

}): Promise<ProcedureProposal>;

Parameters

Name	Type	Description
input	{ cid: string; operations: ProcedureProposalOperation[]; options?: TransactionOptions; }	Reference to the proposal metadata, which must be a CID reference, and its operations.

Procedure.proposeBySig

Submit a proposal signed by another account.

Signature

proposeBySig(input: SignedProposalInput & {

signature: string;

}): Promise<OrganigramTransaction>;

Procedure.reloadData

Read the roles and metadata reference again from chain.

Signature

reloadData(): Promise<Procedure>;

Procedure.reloadProposal

Read one proposal again from chain.

Signature

reloadProposal(proposalKey: string): Promise<Procedure>;

Procedure.reloadProposals

Read every proposal again from chain.

Signature

reloadProposals(): Promise<Procedure>;

Procedure.signApplyProposal

Sign the application of a proposal, for applyProposalBySig().

Signature

signApplyProposal(input: SignedProposalActionInput): Promise<string>;

Procedure.signBlockProposal

Sign the block of a proposal, for blockProposalBySig().

Signature

signBlockProposal(input: SignedBlockProposalInput): Promise<string>;

Procedure.signPresentProposal

Sign the presentation of a proposal, for presentProposalBySig().

Signature

signPresentProposal(input: SignedProposalActionInput): Promise<string>;

Procedure.signProposal

Sign a proposal, so that another account submits it with proposeBySig().

The signer pays no gas: any account can submit the signature with the matching …BySig method.

Signature

signProposal(input: SignedProposalInput): Promise<string>;

Procedure.toJson

Convert the procedure into plain JSON.

Signature

toJson: () => ProcedureJson;

ExternalCallOperationInput

OperationParam

ProcedureInput

ProcedureProposal

ProcedureProposalOperation

Build it with Procedure.createOperation() rather than by hand.

ProcedureProposalOperationFunction

ProcedureType

ProcedureTypeField

ProposalMetadata

SignedBlockProposalInput

Extends SignedProposalActionInput.

SignedProposalActionInput

SignedProposalInput

AccountInOrgans

Definition

export type AccountInOrgans = {

moderators?: boolean;

proposers?: boolean;

deciders?: boolean;

};

Election

Definition

export type Election = {

proposalKey: string;

start: string;

votesCount: string;

hasVoted: boolean;

approvals?: string;

objections?: string;

eligibleVotes?: string;

approved?: boolean;

};

OperationKey

Definition

export type OperationKey = 'addEntries' | 'removeEntries' | 'replaceEntry' | 'addPermission' | 'removePermission' | 'replacePermission' | 'updateMetadata' | 'withdrawEther' | 'withdrawERC20' | 'withdrawERC721' | 'externalCall' | string;

OperationParamAction

Definition

export type OperationParamAction = 'select' | 'create' | 'update' | 'delete' | 'withdraw' | 'deposit' | 'transfer' | 'block';

OperationParamType

Definition

export type OperationParamType = 'cid' | 'entry' | 'entries' | 'address' | 'bytes' | 'addresses' | 'index' | 'indexes' | 'organ' | 'oldPermissionAddress' | 'newPermissionAddress' | 'permissionAddress' | 'permissionValue' | 'proposal' | 'proposals' | 'amount' | 'tokenId';

OperationTag

Definition

export type OperationTag = 'cid' | 'entries' | 'permissions' | 'coins' | 'collectibles' | 'erc721' | 'erc20' | 'erc1155' | 'ether' | 'add' | 'replace' | 'remove' | 'deposit' | 'withdraw' | 'transfer';

ProcedureJson

Definition

export type ProcedureJson = {

isDeployed: boolean;

address: string;

deciders: string;

typeName: ProcedureTypeName;

name: string;

description: string;

cid: string;

salt?: string | null;

chainId: string;

data: string;

metadata?: string;

proposers: string;

moderators: string;

withModeration: boolean;

proposerMode?: ERC20VoteRoleMode;

moderatorMode?: ERC20VoteRoleMode;

voterMode?: ERC20VoteRoleMode;

requireMemberMajority?: boolean;

forwarder: string;

proposals?: ProcedureProposal[];

args?: unknown[];

type: ProcedureType;

organigramId?: string | null;

};

NominationProcedure

Definition

constructor(procedureInput: ProcedureInput);

NominationProcedure.load

Read a nomination procedure from chain, with its proposals.

Signature

static load(address: string, clients: ContractClients, initialProcedure?: ProcedureInput): Promise<NominationProcedure>;

NominationProcedure.nominate

Adopt a proposal as a decider, which runs its operations.

Signature

nominate(proposalKey: string, options?: TransactionOptions): Promise<void>;

NominationProcedure.nominateBySig

Adopt a proposal with an adoption signed by a decider.

Signature

nominateBySig(input: {

proposalKey: string;

nonce: bigint;

deadline: bigint | number;

signature: string;

}): Promise<void>;

NominationProcedure.reject

Reject a proposal as a decider.

Signature

reject(proposalKey: string, options?: TransactionOptions): Promise<void>;

NominationProcedure.signNomination

Sign the adoption of a proposal, for nominateBySig().

The signer pays no gas: any account can submit the signature with the matching …BySig method.

Signature

signNomination(input: {

proposalKey: string;

nonce: bigint;

deadline: bigint | number;

}): Promise<string>;

VoteProcedure

The vote opens when a proposal is presented. Once it is over, anyone calls applyProposal() to count the ballots and settle the proposal.

Definition

constructor(input: VoteProcedureInput);

VoteProcedure.count

Tell whether a proposal passed, once its vote is over.

Signature

count(proposalKey: string): Promise<boolean>;

VoteProcedure.load

Read a vote procedure from chain, with its proposals and elections.

Signature

static load(address: string, clients: ContractClients, initialProcedure?: ProcedureInput): Promise<VoteProcedure>;

VoteProcedure.loadElection

Read the state of the vote on one proposal.

Signature

static loadElection(address: string, proposalKey: string, clients: ContractClients, voteDuration?: bigint, contract?: OrganigramContract, blockTimestamp?: bigint): Promise<Election>;

VoteProcedure.loadElections

Read the state of the vote on every proposal.

Signature

static loadElections(address: string, clients: ContractClients, proposalsLength?: number): Promise<Election[]>;

VoteProcedure.signVote

Sign a vote, for voteBySig().

The signer pays no gas: any account can submit the signature with the matching …BySig method.

Signature

signVote(input: {

proposalKey: string;

approval: boolean;

nonce: bigint;

deadline: bigint | number;

}): Promise<string>;

VoteProcedure.toJson

Convert the procedure into plain JSON.

Signature

toJson: () => ProcedureJson;

VoteProcedure.vote

Vote for or against a proposal, as a decider.

Signature

vote(proposalKey: string, choice: 'for' | 'against', options?: TransactionOptions): Promise<void>;

VoteProcedure.voteBySig

Cast a vote signed by a decider.

Signature

voteBySig(input: {

proposalKey: string;

approval: boolean;

nonce: bigint;

deadline: bigint | number;

signature: string;

}): Promise<void>;

VoteProcedureInput

Definition

export type VoteProcedureInput = ProcedureInput & {

quorumSize: string;

voteDuration: string;

majoritySize: string;

elections: Election[];

};

ERC20VoteProcedure

Ballots weigh the balances held just before the vote opened, so tokens moved during the vote do not count twice.

Definition

constructor(input: ERC20VoteProcedureInput);

ERC20VoteProcedure.erc20Balance

Read the token balance of an account, or of the connected wallet.

Signature

erc20Balance(account?: string): Promise<bigint>;

ERC20VoteProcedure.load

Read an ERC-20 vote procedure from chain, with its proposals and elections.

Signature

static load(address: string, clients: ContractClients, initialProcedure?: ProcedureInput): Promise<ERC20VoteProcedure>;

ERC20VoteProcedure.toJson

Convert the procedure into plain JSON.

Signature

toJson: () => ProcedureJson;

ERC20VoteProcedure.vote

Vote for or against a proposal, with the weight of your tokens.

Signature

vote(proposalKey: string, choice: 'for' | 'against', options?: TransactionOptions): Promise<void>;

ERC20VoteProcedureInput

Definition

export type ERC20VoteProcedureInput = Omit<VoteProcedureInput, 'type' | 'typeName'> & {

erc20: string;

proposerMode?: ERC20VoteRoleMode;

moderatorMode?: ERC20VoteRoleMode;

voterMode?: ERC20VoteRoleMode;

requireMemberMajority?: boolean;

};

PopulateInitializeInput

ERC20VoteRoleMode

Definition

export type ERC20VoteRoleMode = 'organ' | 'token' | 'disabled';

PopulatedTransactionData

Definition

export type PopulatedTransactionData = {

data: string;

};

ProcedureTypeName

Definition

export type ProcedureTypeName = 'erc20Vote' | 'nomination' | 'vote';

getProcedureClass

Signature

getProcedureClass: (typeName: string) => Promise<typeof import("./erc20Vote").ERC20VoteProcedure | typeof import("./vote").VoteProcedure | typeof import("./nomination").NominationProcedure>

getProcedureTypes

Signature

getProcedureTypes: (chainId?: string) => Partial<Record<ProcedureTypeName, ProcedureType>>

Assets

Assets are ERC-20 tokens held by organs: plain assets, or company equity whose transfers a procedure approves.

Asset

Definition

constructor(input: AssetInput);

Asset.load

Hydrate an asset from chain state.

Signature

static load: (address: string, clients: ContractClients, initialAsset?: AssetInput) => Promise<(Asset & {

userBalance: string;

}) | undefined>;

Asset.toJson

Convert the asset into a JSON-safe structure.

Signature

toJson(): AssetJson;

AssetInput

AssetJson

ERC20_INITIAL_SUPPLY

Definition

const ERC20_INITIAL_SUPPLY = 10000000

Off-chain content and encryption

Contracts only store references. Metadata and documents live off-chain, and are referenced by CID references of the form og://workspace/<workspace>/<key>. Each version of a file is described by a manifest. Encrypted files use three levels of keys: a content key encrypts one file, a group key shared by the members of an access group wraps content keys, and the key pair of each member unwraps group keys. These functions run on the Web Crypto API of the user's device: keep private keys there, never send them to a server or log them.

EncryptedCidAccessGroup

EncryptedCidManifest

EncryptionPublicKeySiweResource

ParsedCidRef

PublicFileVersionManifest

RecipientEncryptionKey

ScopeEnvelopeCheckpoint

ScopeEnvelopeItem

ScopeEnvelopeReference

StoredUserEncryptionKeyPair

WrappedContentKey

WrappedGroupKey

AccessGroupScopeType

Definition

export type AccessGroupScopeType = 'workspace' | 'organization' | 'organ' | 'procedure' | 'certifiedProof';

EncryptedCidContentType

Definition

export type EncryptedCidContentType = 'entry' | 'proposal' | 'organMetadata' | 'procedureMetadata' | 'certifiedProof' | 'file' | string;

FileVersionManifest

Definition

export type FileVersionManifest = PublicFileVersionManifest | EncryptedCidManifest;

ScopeEnvelopeContentType

Definition

export type ScopeEnvelopeContentType = EncryptedCidContentType;

ScopeEnvelopeRetentionState

Definition

export type ScopeEnvelopeRetentionState = 'current' | 'superseded' | 'revoked' | 'archived';

ScopeEnvelopeScopeType

Definition

export type ScopeEnvelopeScopeType = 'workspace';

bytesToArrayBuffer

Signature

bytesToArrayBuffer: (value: ArrayBuffer | Uint8Array) => ArrayBuffer

bytesToText

Signature

bytesToText: (value: ArrayBuffer | Uint8Array) => string

computeScopeEnvelopeRoot

Signature

computeScopeEnvelopeRoot: (items: Record<string, ScopeEnvelopeItem>) => Promise<string>

createEncryptionKeyVersion

Signature

createEncryptionKeyVersion: (timestamp?: number) => number

createEncryptionPublicKeyMessage

Signature

createEncryptionPublicKeyMessage: (address: string, publicKey: JsonWebKey, keyVersion: number) => string

createEncryptionPublicKeySiweResource

Signature

createEncryptionPublicKeySiweResource: (address: string, publicKey: JsonWebKey, keyVersion: number) => string

createFileVersionManifest

Signature

createFileVersionManifest: (input: {

contentType: ScopeEnvelopeContentType;

scopeRef: ScopeEnvelopeReference;

logicalKey: string;

encryptedCid: string;

encryptedContentIv: string;

encryptedContentSize: number;

wrappedContentKey: WrappedContentKey;

previousManifestCid?: string | null;

retentionState?: ScopeEnvelopeRetentionState;

scopeEnvelope?: ScopeEnvelopeCheckpoint;

mime?: string;

name?: string;

signature?: string | null;

signedByAddress?: string | null;

createdAt?: Date | string;

}) => FileVersionManifest

createPublicFileVersionManifest

Signature

createPublicFileVersionManifest: (input: {

contentType: ScopeEnvelopeContentType;

scopeRef: ScopeEnvelopeReference;

logicalKey: string;

publicCid: string;

publicContentSize: number;

previousManifestCid?: string | null;

retentionState?: ScopeEnvelopeRetentionState;

scopeEnvelope?: ScopeEnvelopeCheckpoint;

mime?: string;

name?: string;

signature?: string | null;

signedByAddress?: string | null;

createdAt?: Date | string;

}) => PublicFileVersionManifest

createScopeEnvelopeCheckpoint

Signature

createScopeEnvelopeCheckpoint: (input: {

epoch: number;

membershipHash: string;

rootHash: string;

}) => ScopeEnvelopeCheckpoint

createScopeEnvelopeItem

Signature

createScopeEnvelopeItem: (input: {

logicalKey: string;

currentManifestCid: string;

contentType: ScopeEnvelopeContentType;

version?: number;

retentionState?: ScopeEnvelopeRetentionState;

previousManifestCid?: string;

updatedAt?: Date | string;

}) => ScopeEnvelopeItem

createScopeEnvelopeSignatureMessage

Signature

createScopeEnvelopeSignatureMessage: (input: {

scopeRef: ScopeEnvelopeReference;

checkpoint: ScopeEnvelopeCheckpoint;

items: Record<string, ScopeEnvelopeItem>;

previousEnvelopeCid?: string | null;

}) => string

decryptBytes

Signature

decryptBytes: (encryptedBytes: ArrayBuffer | Uint8Array, key: CryptoKey, iv: string) => Promise<Uint8Array>

encryptBytes

Signature

encryptBytes: (bytes: ArrayBuffer | Uint8Array, key: CryptoKey) => Promise<{

encryptedBytes: Uint8Array;

iv: string;

}>

exportUserPrivateKey

Only store the result encrypted, for example in a passkey vault.

Signature

exportUserPrivateKey: (keyPair: CryptoKeyPair) => Promise<JsonWebKey>

exportUserPublicKey

Signature

exportUserPublicKey: (keyPair: CryptoKeyPair) => Promise<JsonWebKey>

formatCidRef

Signature

formatCidRef: (scopeRef: ScopeEnvelopeReference, logicalKey: string, manifestCid?: string) => string

generateContentKey

Signature

generateContentKey: () => Promise<CryptoKey>

generateGroupKey

Signature

generateGroupKey: () => Promise<CryptoKey>

generateUserEncryptionKeyPair

Keep the private key on the user's device: never send it to a server or log it.

Signature

generateUserEncryptionKeyPair: () => Promise<CryptoKeyPair>

getCrypto

Signature

getCrypto: () => Crypto

getRandomIv

Signature

getRandomIv: () => Uint8Array

importExtractableUserPublicKey

Signature

importExtractableUserPublicKey: (publicKey: JsonWebKey) => Promise<CryptoKey>

importUserPrivateKey

Signature

importUserPrivateKey: (privateKey: JsonWebKey) => Promise<CryptoKey>

isCidRef

Signature

isCidRef: (value?: string | null) => boolean

isEncryptedCidManifest

Signature

isEncryptedCidManifest: (value: unknown) => value is EncryptedCidManifest

isFileVersionManifest

Signature

isFileVersionManifest: (value: unknown) => value is FileVersionManifest

isValidEncryptionKeyVersion

Signature

isValidEncryptionKeyVersion: (keyVersion: number) => boolean

normalizeEncryptionKeyVersion

Signature

normalizeEncryptionKeyVersion: (keyVersion: number) => number | null

parseCidRef

Signature

parseCidRef: (value?: string | null) => ParsedCidRef | null

parseEncryptionPublicKeySiweResource

Signature

parseEncryptionPublicKeySiweResource: (resources: string[] | undefined, address: string) => EncryptionPublicKeySiweResource | null

unwrapContentKey

Signature

unwrapContentKey: (wrappedContentKey: WrappedContentKey, groupKey: CryptoKey) => Promise<CryptoKey>

unwrapGroupKey

Signature

unwrapGroupKey: (wrappedGroupKey: WrappedGroupKey, recipientPrivateKey: CryptoKey) => Promise<CryptoKey>

wrapContentKey

Signature

wrapContentKey: (contentKey: CryptoKey, groupKey: CryptoKey) => Promise<WrappedContentKey>

wrapGroupKeyForRecipient

Signature

wrapGroupKeyForRecipient: (groupKey: CryptoKey, recipient: RecipientEncryptionKey) => Promise<WrappedGroupKey>

ENCRYPTED_CID_KIND

Definition

const ENCRYPTED_CID_KIND: "organigram.encrypted-cid.v1"

ENCRYPTION_ALGORITHM

Definition

const ENCRYPTION_ALGORITHM: "A256GCM"

ENCRYPTION_PUBLIC_KEY_SIWE_RESOURCE_KIND

Definition

const ENCRYPTION_PUBLIC_KEY_SIWE_RESOURCE_KIND: "organigram.encryption-public-key.v1"

FILE_VERSION_MANIFEST_KIND

Definition

const FILE_VERSION_MANIFEST_KIND: "organigram.file-version-manifest.v1"

GROUP_KEY_ALGORITHM

Definition

const GROUP_KEY_ALGORITHM: "ECDH-P256+A256GCM"

Networks and deployments

The protocol contracts are deployed once per chain. These functions tell which chains are supported, where the contracts are, and at which address a new clone will be deployed.

getChainExplorerBaseUrl

Signature

getChainExplorerBaseUrl: (chainId: string) => string | undefined

getConfiguredChain

Signature

getConfiguredChain: (chainId: string) => Chain | undefined

getDefaultChainId

Signature

getDefaultChainId: () => string

Returns

Type	Description
string	The default chain id.

getDeployment

Signature

getDeployment: (chainId: string | number | bigint | null | undefined, deploymentName: ProtocolDeploymentName) => string

getHostUrl

Signature

getHostUrl: (hostUrl?: string | undefined) => URL | null

getSupportedChainIds

Signature

getSupportedChainIds: () => string[]

isLocalHost

Signature

isLocalHost: (hostUrl?: string) => boolean

isSupportedChainId

Signature

isSupportedChainId: (chainId: string | number | bigint | null | undefined) => boolean

deployedAddresses

Definition

const deployedAddresses: ProtocolDeployments

ContractName

Definition

export type ContractName = 'Organ' | 'Asset' | 'EquityToken' | 'ERC20VoteProcedure' | 'VoteProcedure' | 'NominationProcedure' | 'OrganigramClient';

predictContractAddress

Signature

predictContractAddress: (input: {

type: Omit<ContractName, "OrganigramClient">;

chainId: string;

salt: string;

deployer?: string;

}) => string

Utilities

Small helpers used across the library and the Organigram app.

capitalize

Signature

capitalize: (s: string) => string

createRandom32BytesHexId

Signature

createRandom32BytesHexId: () => `0x${string}`

handleJsonBigInt

Signature

handleJsonBigInt: (_key: string, value: unknown) => unknown

parseFiniteNumber

Signature

parseFiniteNumber: (value: number | string | null | undefined, fallback: number) => number