@openzeppelin/compact-contracts 0.1.0

package/access/ZOwnablePK.compact

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.1.0 (access/ZOwnablePK.compact)
+
+pragma language_version >= 0.21.0;
+
+/**
+ * @module ZOwnablePK
+ * @description A shielded, public key-derived Ownable module.
+ *
+ * `ZOwnablePK` provides a privacy-preserving access control mechanism
+ * for contracts with a single administrative user. Unlike traditional
+ * `Ownable` implementations that store or expose the owner's public key
+ * on-chain, this module stores only a commitment to a hashed identifier
+ * derived from the owner's public key and a secret nonce.
+ * For the strongest security guarantees, use an Air-Gapped Public Key.
+ *
+ * @notice This module explicitly supports commitments derived from public keys;
+ * however, it may be possible to use contract addresses when contract-to-contract
+ * calls become available. This will be revisited when it's known if/how witnesses
+ * are used from a contract address context.
+ *
+ * @dev Features:
+ * - Obfuscated owner identity: The owner's public key is never revealed on-chain.
+ * - Stateless verification: The contract never needs access to the full public key.
+ * - Built-in support for transfer and renounce functionality.
+ * - Instance-specific salts to prevent cross-contract correlation.
+ * - Deterministic hashing with `persistentHash` to support zero-knowledge verification.
+ *
+ * @dev Commitment structure:
+ * ```
+ * id = SHA256(pk, secretNonce)
+ * commitment = SHA256(id, instanceSalt, counter, "ZOwnablePK:shield:")
+ * ```
+ * The commitment changes on each transfer due to the incrementing `counter`,
+ * providing unlinkability across ownership changes.
+ *
+ * @dev Security Considerations:
+ * - The `secretNonce` must be kept private. Loss of the nonce prevents the
+ *   owner from proving ownership or transferring it.
+ * - Ownership validation is entirely circuit-based using witness-provided values.
+ * - The `_instanceSalt` is immutable and used to differentiate deployments.
+ *
+ * @notice Best used for single-admin contracts with privacy requirements.
+ * It is not designed for multi-owner or role-based access control.
+ */
+module ZOwnablePK {
+  import CompactStandardLibrary;
+  import "../security/Initializable" prefix Initializable_;
+
+  /**
+   * @ledger _ownerCommitment
+   * @description Stores the current hashed commitment representing the owner.
+   * This commitment is derived from the public identifier (e.g., `SHA256(pk, nonce)`),
+   * the `instanceSalt`, the transfer `counter`, and a domain separator.
+   *
+   * A commitment of `default<Bytes<32>>` (i.e., zero) indicates the contract is unowned.
+   */
+  export ledger _ownerCommitment: Bytes<32>;
+  /**
+   * @ledger _counter
+   * @description Internal transfer counter used to prevent commitment reuse.
+   *
+   * Increments by 1 on every successful ownership transfer. Combined with `id` and
+   * `instanceSalt` to compute unique owner commitments over time.
+   */
+  export ledger _counter: Counter;
+  /**
+   * @sealed @ledger _instanceSalt
+   * @description A per-instance value provided at initialization used to namespace
+   * commitments for this contract instance.
+   *
+   * This salt prevents commitment collisions across contracts that might otherwise use
+   * the same owner identifiers or domain parameters. It is immutable after initialization.
+   */
+  export sealed ledger _instanceSalt: Bytes<32>;
+
+  /**
+   * @witness wit_secretNonce
+   * @description A private per-user nonce used in deriving the shielded owner identifier.
+   *
+   * Combined with the user's public key as `SHA256(pk, nonce)` to produce an obfuscated,
+   * unlinkable identity commitment. Users are encouraged to rotate this value on ownership changes.
+   */
+  export witness wit_secretNonce(): Bytes<32>;
+
+  /**
+   * @description Initializes the contract by setting the initial owner via `ownerId`
+   * and storing the `instanceSalt` that acts as a privacy additive for preventing
+   * duplicate commitments among other contracts implementing ZOwnablePK.
+   *
+   * @warning The `ownerId` must be calculated prior to contract deployment using the SHA256 hashing algorithm.
+   * Using any other algorithm will result in a permanent loss of contract access.
+   *
+   * @circuitInfo k=14, rows=14933
+   *
+   * Requirements:
+   *
+   * - Contract is not initialized.
+   * - `ownerId` is not zero.
+   *
+   * @param {Bytes<32>} ownerId - The owner's unique identifier SHA256(pk, nonce).
+   * @param {Bytes<32>} instanceSalt - Contract salt to prevent duplicate commitments if
+   * users reuse their PK and secretNonce witness (not recommended).
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize(ownerId: Bytes<32>, instanceSalt: Bytes<32>): [] {
+    Initializable_initialize();
+
+    assert(ownerId != default<Bytes<32>>, "ZOwnablePK: invalid id");
+    _instanceSalt = disclose(instanceSalt);
+    _transferOwnership(ownerId);
+  }
+
+  /**
+   * @description Returns the current commitment representing the contract owner.
+   * The full commitment is: `SHA256(SHA256(pk, nonce), instanceSalt, counter, domain)`.
+   *
+   * @circuitInfo k=10, rows=57
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @returns {Bytes<32>} The current owner's commitment.
+   */
+  export circuit owner(): Bytes<32> {
+    Initializable_assertInitialized();
+    return _ownerCommitment;
+  }
+
+  /**
+   * @description Transfers ownership to `newOwnerId`.
+   * `newOwnerId` must be precalculated and given to the current owner off chain.
+   *
+   * @circuitInfo k=16, rows=39240
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - Caller is the current owner.
+   * - `newOwnerId` is not an empty array.
+   *
+   * @param {Bytes<32>} newOwnerId - The new owner's unique identifier (`SHA256(pk, nonce)`).
+   * @returns {[]} Empty tuple.
+   */
+  export circuit transferOwnership(newOwnerId: Bytes<32>): [] {
+    Initializable_assertInitialized();
+
+    assertOnlyOwner();
+    assert(newOwnerId != default<Bytes<32>>, "ZOwnablePK: invalid id");
+    _transferOwnership(newOwnerId);
+  }
+
+  /**
+   * @description Leaves the contract without an owner.
+   * It will not be possible to call `assertOnlyOwner` circuits anymore.
+   * Can only be called by the current owner.
+   *
+   * @circuitInfo k=15, rows=24442
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - Caller is the current owner.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit renounceOwnership(): [] {
+    Initializable_assertInitialized();
+
+    assertOnlyOwner();
+    _ownerCommitment.resetToDefault();
+  }
+
+  /**
+   * @description Throws if called by any account whose id hash `SHA256(pk, nonce)` does not match
+   * the stored owner commitment.
+   * Use this to only allow the owner to call specific circuits.
+   *
+   * @circuitInfo k=15, rows=24437
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - Caller's id (`SHA256(pk, nonce)`) when used in `_computeOwnerCommitment` equals
+   * the stored `_ownerCommitment`, thus verifying themselves as the owner.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertOnlyOwner(): [] {
+    Initializable_assertInitialized();
+
+    const nonce = wit_secretNonce();
+    const callerAsEither =
+            Either<ZswapCoinPublicKey, ContractAddress> { is_left: true,
+                                                          left: ownPublicKey(),
+                                                          right: ContractAddress { bytes: pad(32, "") } };
+    const id = _computeOwnerId(callerAsEither, nonce);
+    assert(_ownerCommitment == _computeOwnerCommitment(id, _counter),
+           "ZOwnablePK: caller is not the owner"
+           );
+  }
+
+  /**
+   * @description Computes the owner commitment from the given `id` and `counter`.
+   *
+   * ## Owner ID (`id`)
+   * The `id` is expected to be computed off-chain as:
+   * `id = SHA256(pk, nonce)`
+   *
+   * - `pk`: The owner's public key.
+   * - `nonce`: A secret nonce scoped to the instance, ideally rotated with each transfer.
+   *
+   * ## Commitment Derivation
+   * `commitment = SHA256(id, instanceSalt, counter, domain)`
+   *
+   * - `id`: See above.
+   * - `instanceSalt`: A unique per-deployment salt, stored during initialization.
+   * This prevents commitment collisions across deployments.
+   * - `counter`: Incremented with each ownership transfer, ensuring uniqueness
+   * even with repeated `id` values. Cast to `Field` then `Bytes<32>` for hashing.
+   * - `domain`: Domain separator `"ZOwnablePK:shield:"` (padded to 32 bytes) to prevent
+   * hash collisions when extending the module or using similar commitment schemes.
+   *
+   * @circuitInfo k=14, rows=14853
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @param {Bytes<32>} id - The unique identifier of the owner calculated by `SHA256(pk, nonce)`.
+   * @param {Uint<64>} counter - The current counter or round. This increments by `1`
+   * after every transfer to prevent duplicate commitments given the same `id`.
+   * @returns {Bytes<32>} The commitment derived from `id` and `counter`.
+   */
+  export circuit _computeOwnerCommitment(id: Bytes<32>, counter: Uint<64>,): Bytes<32> {
+    Initializable_assertInitialized();
+    return persistentHash<Vector<4, Bytes<32>>>(
+             [id, _instanceSalt, counter as Field as Bytes<32>, pad(32, "ZOwnablePK:shield:")]
+             );
+  }
+
+  /**
+   * @description Computes the unique identifier (`id`) of the owner from their
+   * public key and a secret nonce.
+   *
+   * ## ID Derivation
+   * `id = SHA256(pk, nonce)`
+   *
+   * - `pk`: The public key of the caller. This is passed explicitly to allow
+   * for off-chain derivation, testing, or scenarios where the caller is
+   * different from the subject of the computation.
+   * We recommend using an Air-Gapped Public Key.
+   * - `nonce`: A secret nonce tied to the identity. The generation strategy is
+   * left to the user, offering different security/convenience trade-offs.
+   *
+   * The result is a 32-byte commitment that uniquely identifies the owner.
+   * This value is later used in owner commitment hashing,
+   * and acts as a privacy-preserving alternative to a raw public key.
+   *
+   * @notice This module allows ownership to be tied to an identity commitment derived
+   * from a public key and secret nonce.
+   * While typically used with user public keys, this mechanism may also
+   * support contract addresses as identifiers in future contract-to-contract
+   * interactions. Both are treated as 32-byte values (`Bytes<32>`).
+   *
+   * Requirements:
+   *
+   * - `pk` is not a ContractAddress.
+   *
+   * @param {Either<ZswapCoinPublicKey, ContractAddress>} pk - The public key of the identity being committed.
+   * @param {Bytes<32>} nonce - A private nonce to scope the commitment.
+   * @returns {Bytes<32>} The computed owner ID.
+   */
+  export pure circuit _computeOwnerId(
+                        pk: Either<ZswapCoinPublicKey, ContractAddress>,
+                        nonce: Bytes<32>
+                        ): Bytes<32> {
+    assert(pk.is_left, "ZOwnablePK: contract address owners are not yet supported");
+
+    return persistentHash<Vector<2, Bytes<32>>>([pk.left.bytes, nonce]);
+  }
+
+  /**
+   * @description Transfers ownership to owner id `newOwnerId` without
+   * enforcing permission checks on the caller.
+   *
+   * @circuitInfo k=14, rows=14823
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @param {Bytes<32>} newOwnerId - The unique identifier of the new owner
+   * calculated by `SHA256(pk, nonce)`.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _transferOwnership(newOwnerId: Bytes<32>): [] {
+    Initializable_assertInitialized();
+
+    _counter.increment(1);
+    _ownerCommitment = disclose(_computeOwnerCommitment(newOwnerId, _counter));
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@openzeppelin/compact-contracts",
+  "version": "0.1.0",
+  "description": "OpenZeppelin Compact contract library",
+  "keywords": [
+    "openzeppelin",
+    "compact",
+    "midnight",
+    "contracts",
+    "security"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenZeppelin/compact-contracts.git"
+  },
+  "license": "MIT",
+  "author": "OpenZeppelin Community <maintainers@openzeppelin.org>",
+  "bugs": {
+    "url": "https://github.com/OpenZeppelin/compact-contracts/issues"
+  },
+  "homepage": "https://docs.openzeppelin.com/contracts-compact/",
+  "type": "module",
+  "imports": {
+    "#test-utils/address.js": "./test-utils/address.js"
+  },
+  "scripts": {
+    "compact": "compact-compiler --exclude '*/archive/*'",
+    "compact:access": "compact-compiler --dir access",
+    "compact:archive": "compact-compiler --dir archive",
+    "compact:security": "compact-compiler --dir security",
+    "compact:token": "compact-compiler --dir token",
+    "compact:utils": "compact-compiler --dir utils",
+    "build": "compact-builder --hierarchical --out dist --clean-dist --exclude '*/archive/*' --exclude 'Mock*' --exclude '*.mock.compact' --copy package.json --copy ../README.md && find dist -type d -empty -delete",
+    "test": "SKIP_ZK=true yarn run compact && vitest run",
+    "test:coverage": "SKIP_ZK=true yarn run compact && vitest run --coverage",
+    "types": "tsc -p tsconfig.json --noEmit",
+    "clean": "git clean -fXd"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@openzeppelin/compact-cli": "^0.0.2"
+  },
+  "devDependencies": {
+    "@openzeppelin/compact-simulator": "^0.0.1",
+    "@tsconfig/node24": "^24.0.4",
+    "@types/node": "25.7.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  }
+}

package/security/Initializable.compact

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.1.0 (security/Initializable.compact)
+
+pragma language_version >= 0.21.0;
+
+/**
+ * @module Initializable
+ * @description Initializable provides a simple mechanism that mimics the functionality of a constructor.
+ */
+module Initializable {
+  import CompactStandardLibrary;
+
+  export ledger _isInitialized: Boolean;
+
+  /**
+   * @description Initializes the state thus ensuring the calling circuit can only be called once.
+   *
+   * @circuitInfo k=10, rows=38
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit initialize(): [] {
+    assertNotInitialized();
+    _isInitialized = true;
+  }
+
+  /**
+   * @description Asserts that the contract has been initialized, throwing an error if not.
+   *
+   * @circuitInfo k=10, rows=31
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertInitialized(): [] {
+    assert(_isInitialized, "Initializable: contract not initialized");
+  }
+
+  /**
+   * @description Asserts that the contract has not been initialized, throwing an error if it has.
+   *
+   * @circuitInfo k=10, rows=35
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertNotInitialized(): [] {
+    assert(!_isInitialized, "Initializable: contract already initialized");
+  }
+}

package/security/Pausable.compact

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.1.0 (security/Pausable.compact)
+
+pragma language_version >= 0.21.0;
+
+/**
+ * @module Pausable
+ * @description Pausable allows the implementing contract to implement
+ * an emergency stop mechanism. Only circuits that call `assertPaused`
+ * or `assertNotPaused` will be affected by this mechanism.
+ */
+module Pausable {
+  import CompactStandardLibrary;
+
+  export ledger _isPaused: Boolean;
+
+  /**
+   * @description Returns true if the contract is paused, and false otherwise.
+   *
+   * @circuitInfo k=10, rows=32
+   *
+   * @return {Boolean} True if paused.
+   */
+  export circuit isPaused(): Boolean {
+    return _isPaused;
+  }
+
+  /**
+   * @description Makes a circuit only callable when the contract is paused.
+   *
+   * @circuitInfo k=10, rows=31
+   *
+   * Requirements:
+   *
+   * - Contract must be paused.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertPaused(): [] {
+    assert(_isPaused, "Pausable: not paused");
+  }
+
+  /**
+   * @description Makes a circuit only callable when the contract is not paused.
+   *
+   * @circuitInfo k=10, rows=35
+   *
+   * Requirements:
+   *
+   * - Contract must not be paused.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertNotPaused(): [] {
+    assert(!_isPaused, "Pausable: paused");
+  }
+
+  /**
+   * @description Triggers a stopped state.
+   *
+   * @circuitInfo k=10, rows=38
+   *
+   * Requirements:
+   *
+   * - Contract must not be paused.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _pause(): [] {
+    assertNotPaused();
+    _isPaused = true;
+  }
+
+  /**
+   * @description Lifts the pause on the contract.
+   *
+   * @circuitInfo k=10, rows=34
+   *
+   * Requirements:
+   *
+   * - Contract must be paused.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _unpause(): [] {
+    assertPaused();
+    _isPaused = false;
+  }
+}