Your own asset, issued and redeemed from your back office.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {ERC20Pausable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";

/// @title A tokenised asset for a consortium network (CryptoRail tokenisation pack, FR-PLT-11)
/// @notice An ERC-20 whose units only move between holders the compliance role has allowed.
/// The issuer role issues, a holder redeems by burning with a reference the issuer's back office
/// reconciles, and the administrator pauses every movement. Every operation emits an event.
contract TokenisedAsset is ERC20, ERC20Pausable, AccessControl {
    /// @notice May issue new units to an allowed holder.
    bytes32 public constant ISSUER_ROLE = keccak256("ISSUER_ROLE");
    /// @notice May add holders to the allowlist and remove them from it.
    bytes32 public constant COMPLIANCE_ROLE = keccak256("COMPLIANCE_ROLE");

    uint8 private immutable _DECIMALS;

    /// @notice Whether an address may hold, send and receive units.
    mapping(address holder => bool) public allowed;

    /// @notice Units issued to `to`; `ref` is the issuer's own reference (an order, a subscription).
    event Issued(address indexed to, uint256 amount, bytes32 indexed ref);
    /// @notice Units burnt by `holder`; `ref` is what the issuer's back office pays out against.
    event Redeemed(address indexed holder, uint256 amount, bytes32 indexed ref);
    event HolderAllowed(address indexed holder);
    event HolderDisallowed(address indexed holder);

    /// @notice A transfer, an issuance or a redemption involved an address that is not allowed.
    error HolderNotAllowed(address holder);

    constructor(
        string memory name_,
        string memory symbol_,
        uint8 decimals_,
        address admin,
        address issuer,
        address compliance
    ) ERC20(name_, symbol_) {
        _DECIMALS = decimals_;
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _grantRole(ISSUER_ROLE, issuer);
        _grantRole(COMPLIANCE_ROLE, compliance);
    }

    function decimals() public view override returns (uint8) {
        return _DECIMALS;
    }

    /// @notice Issues `amount` new units to the allowed holder `to`.
    function issue(address to, uint256 amount, bytes32 ref) external onlyRole(ISSUER_ROLE) {
        _mint(to, amount);
        emit Issued(to, amount, ref);
    }

    /// @notice Burns `amount` of the caller's units; the issuer pays out against `ref` off chain.
    function redeem(uint256 amount, bytes32 ref) external {
        _burn(msg.sender, amount);
        emit Redeemed(msg.sender, amount, ref);
    }

    function allowHolder(address holder) external onlyRole(COMPLIANCE_ROLE) {
        allowed[holder] = true;
        emit HolderAllowed(holder);
    }

    /// @notice A disallowed holder keeps its balance but can neither send, receive nor redeem.
    function disallowHolder(address holder) external onlyRole(COMPLIANCE_ROLE) {
        allowed[holder] = false;
        emit HolderDisallowed(holder);
    }

    function pause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _pause();
    }

    function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _unpause();
    }

    /// @dev Every movement passes here: issuance (from zero), redemption (to zero) and transfers.
    function _update(address from, address to, uint256 value) internal override(ERC20, ERC20Pausable) {
        if (from != address(0) && !allowed[from]) revert HolderNotAllowed(from);
        if (to != address(0) && !allowed[to]) revert HolderNotAllowed(to);
        super._update(from, to, value);
    }
}

# Compiler settings are pinned so the committed artifact is reproducible (FR-PLT-10).
# The Besu consortium network of the journeys runs the London rules, hence the EVM version;
# no metadata hash, so the bytecode does not depend on the machine's paths.
[profile.default]
src = "src"
out = "out"
cache_path = "cache"
libs = ["node_modules"]
remappings = ["@openzeppelin/contracts/=node_modules/@openzeppelin/contracts/"]
solc_version = "0.8.30"
evm_version = "london"
optimizer = true
optimizer_runs = 200
bytecode_hash = "none"
cbor_metadata = false
auto_detect_solc = false
offline = false

# contracts/: OpenZeppelin pinned through npm, compiled with Foundry
pnpm install --frozen-lockfile
pnpm --filter @cryptorail/contracts compile
# -> contracts/artifacts/TokenisedAsset.json: ABI, bytecode,
#    compiler settings, OpenZeppelin version (committed)

# What CI runs on every change: the committed artifact
# must be exactly what the source compiles to
pnpm --filter @cryptorail/contracts compile:check

# Where the asset will live: known before it exists,
# so the policy can name it
node packages/pack-tokenisation/dist/bin.js predict \
  --deployer <administrator address> --nonce 0

# Deploy it, register its ABI and its address under a name,
# subscribe the back office to every event
CRYPTORAIL_API_KEY=<admin key> \
node packages/pack-tokenisation/dist/bin.js setup \
  --url <service URL> --chain 1338 \
  --deployer-identity <administrator identity id> \
  --name "Pilot Bond 2027" --symbol PB27 --decimals 2 \
  --admin <address> --issuer <address> --compliance <address> \
  --webhook <back office URL>
# It prints the address, the contract id (asset-pb27)
# and the webhook's secret once

// What the setup does, call by call
import { deployData, TOKENISED_ASSET } from '@cryptorail/pack-tokenisation'

// 1. The ABI, straight from the build
const abi = await cryptorail.POST('/v1/abis', {
  body: { fragments: TOKENISED_ASSET.abi },
})

// 2. The deployment: the bytecode with its constructor arguments,
//    signed by the administrator's identity, under your policy
const deploy = await cryptorail.POST('/v1/transactions', {
  params: { header: { 'idempotency-key': 'deploy-asset-pb27' } },
  body: {
    chainId: 1338,
    actor: { kind: 'identity', identityId: administratorId },
    target: {
      kind: 'deploy',
      bytecode: deployData({ name: 'Pilot Bond 2027', symbol: 'PB27',
        decimals: 2, admin, issuer, compliance }),
      abiId: abi.data!.id,
    },
  },
})
// Once CONFIRMED, the transaction carries deployedAddress

// 3. The address, under a name of yours
const asset = await cryptorail.POST('/v1/contracts', {
  body: { chainId: 1338, address: deployedAddress,
    label: 'asset-pb27', abiId: abi.data!.id },
})

import { issuancePolicy } from '@cryptorail/pack-tokenisation'

const policy = issuancePolicy({
  version: 'issuance-2026-10',      // recorded with every decision
  asset: predictedAddress,          // from the predict command
  decimals: 2,
  approvalThreshold: '10000',       // from 10,000 units the board approves
  dailyCap: '30000',                // all issuances of a UTC day
  approverIds: [boardMemberId],
})

// Service configuration:
// adapters: { policy: { kind: 'rules', options: policy } }

// Every function of the contract is now a call by name
const call = (identityId, fn, args, key) =>
  cryptorail.POST('/v1/transactions', {
    params: { header: { 'idempotency-key': key } },
    body: {
      chainId: 1338,
      actor: { kind: 'identity', identityId },
      target: { kind: 'contract', contractId: assetId,
        function: fn, args },
    },
  })

// Compliance allows a holder
await call(complianceId, 'allowHolder', [alice], 'kyc-alice')

// The issuer issues against the order it settles: 5,000.00 PB27
await call(issuerId, 'issue',
  [alice, '500000', toBytes32('ORDER-1001')], 'order-1001')

// A holder redeems against a redemption request
await call(aliceId, 'redeem',
  ['200000', toBytes32('REDEMPTION-42')], 'redemption-42')

// Reads, by name too
await cryptorail.POST('/v1/contracts/{id}/call', {
  params: { path: { id: assetId } },
  body: { function: 'balanceOf', args: [alice] },
})

// An issuance to an address compliance has not allowed:
// the contract would refuse it, so nothing is signed or sent
{
  "state": "PREPARATION_FAILED",
  "failure": {
    "stage": "preparation",
    "cause": "preparation.simulation-reverted",
    "message": "the call would revert with HolderNotAllowed(address)",
    "suggestedAction": "check the arguments and the contract state; …",
    …
  }
}
// While paused the contract answers EnforcedPause();
// over the day's cap the policy answers policy.limit-exceeded

// 20,000 PB27 waits: PENDING_APPROVAL. The board member reads
// the decoded call (to, amount, ref) and signs exactly that
const approval = await cryptorail.GET('/v1/approvals/{transactionId}', {
  params: { path: { transactionId } },
})
const signature = await wallet.request({
  method: 'eth_signTypedData_v4',
  params: [boardMemberAddress, JSON.stringify(approval.data!.typedData)],
})
await cryptorail.POST('/v1/approvals/{transactionId}/signatures', {
  params: { path: { transactionId } },
  body: { approverId: boardMemberId, signature },
})
// Quorum reached: the issuance is signed and confirmed

// In the back office's webhook endpoint, after verifyWebhook(...)
for (const event of JSON.parse(rawBody).events) {
  // event.payload: { contractLabel: 'asset-pb27',
  //   eventName: 'Redeemed',
  //   params: { holder, amount, ref }, … }
  // Issued, Transfer, Redeemed, HolderAllowed, HolderDisallowed,
  // Paused, Unpaused, RoleGranted, RoleRevoked: all of them
  // event.id is stable: apply each one exactly once
}