Skip to main content

🧵 Create and Send Corporate Event

Welcome to the complete guide for the "Create and Send Corporate Event" workflow for the Token City API.

This workflow enables you to create corporate events, send them to ERIR for validation, and execute validated events on the blockchain.

🌟 Objective: Manage corporate actions for tokenized securities in compliance with regulatory requirements through ERIR validation.

📚 OpenAPI Documentation​

✨ Workflow Summary​

This workflow automates the process of creating and executing corporate events through ERIR validation:

  1. 🔹 Query available corporate event types
  2. 🔹 Create a corporate event with required documentation
  3. 🔹 ERIR validates the corporate event
  4. 🔹 Execute the validated event on blockchain

Prerequisites:

🔹 You have already created an Issuer on ERIR 🔹 You have already created and deployed a token project

🏷️ Corporate Event Types​

Token City supports various corporate event types for different business situations:

  1. Forced Transfer - Transfer tokens between accounts (e.g., inheritance, court orders)
  2. Burn Tokens - Destroy tokens from an account (e.g., buyback programs)
  3. Freeze/Unfreeze Address - Suspend or restore account trading capabilities
  4. Freeze/Unfreeze Token Amount - Lock specific token quantities for an address
  5. Recovery Address - Recover lost/compromised wallet funds
  6. Dividend Payment - Distribute profits to token holders

📋 Workflow Steps Table​

StepAPI OperationMethodParametersOutputsDescription
Get Available EventsGET /v2/proxy/erir/corporate-eventGET-List of available events and required data for each oneRetrieves all available corporate event types and their requirements
Create Corporate EventPOST /v2/proxy/erir/corporate-eventPOSTEvent type, parameters, documentsCorporate event ID, EIP712 object, required signaturesCreates a corporate event with supporting documents for ERIR review
Execute Corporate EventPOST /v2/proxy/erir/corporate-event/:id/executePOSTCorporate event IDTransaction ID, blockchain confirmationExecutes the ERIR-validated corporate event on blockchain

🎨 Workflow Visualizations​

🌊 Mermaid Sequence Diagram​

📝 Step-by-Step Implementation​

Step 1: Query Available Corporate Event Types​

Retrieve the list of corporate event types you can create and their requirements.

Endpoint: GET /v2/proxy/erir/corporate-event

Response:

{
  "events": [
    {
      "type": "FORCED_TRANSFER",
      "name": "Forced Transfer",
      "description": "Transfer tokens from one account to another",
      "requiredFields": ["fromAddress", "toAddress", "amount", "reason"],
      "requiredDocuments": ["courtOrder", "legalJustification"],
      "approvalRequired": true
    },
    {
      "type": "BURN_TOKENS",
      "name": "Burn Tokens",
      "description": "Destroy tokens from an account",
      "requiredFields": ["fromAddress", "amount", "reason"],
      "requiredDocuments": ["boardResolution", "buybackAgreement"],
      "approvalRequired": true
    },
    {
      "type": "FREEZE_ADDRESS",
      "name": "Freeze Address",
      "description": "Suspend trading for a specific address",
      "requiredFields": ["address", "reason"],
      "requiredDocuments": ["complianceReport", "suspensionOrder"],
      "approvalRequired": true
    },
    {
      "type": "DIVIDEND_PAYMENT",
      "name": "Dividend Payment",
      "description": "Distribute dividends to token holders",
      "requiredFields": ["dividendPerToken", "paymentDate", "recordDate"],
      "requiredDocuments": ["financialStatement", "boardResolution"],
      "approvalRequired": true
    }
  ]
}

Step 2: Create a Corporate Event​

Submit a corporate event to ERIR with all required documentation.

Example: Forced Transfer (Inheritance Case)​

Endpoint: POST /v2/proxy/erir/corporate-event

Request Body:

{
  "issuanceId": "issuance_456e7890-e89b-12d3-a456-426614174111",
  "eventType": "FORCED_TRANSFER",
  "parameters": {
    "fromAddress": "0xDeceasedAddress1234567890abcdef1234567890ab",
    "toAddress": "0xHeirAddress0987654321fedcba0987654321fedcba",
    "amount": "1000000000000000000",
    "reason": "Inheritance transfer following death of token holder"
  },
  "documents": {
    "courtOrder": "https://docs.acme.com/probate-court-order.pdf",
    "legalJustification": "https://docs.acme.com/inheritance-legal-opinion.pdf",
    "deathCertificate": "https://docs.acme.com/death-certificate.pdf",
    "willDocument": "https://docs.acme.com/last-will-testament.pdf"
  },
  "requestedBy": {
    "name": "John Heir",
    "email": "[email protected]",
    "role": "Beneficiary"
  }
}

Response:

{
  "corporateEventId": "event_987f6543-e89b-12d3-a456-426614174444",
  "eventType": "FORCED_TRANSFER",
  "status": "pending_review",
  "submittedAt": "2025-11-10T14:00:00Z",
  "estimatedReviewTime": "3-5 business days",
  "eip712TypedData": {
    "domain": {
      "name": "ERIRCorporateEvents",
      "version": "1.0.0",
      "chainId": 137
    },
    "types": {
      "ForcedTransfer": [
        { "name": "from", "type": "address" },
        { "name": "to", "type": "address" },
        { "name": "amount", "type": "uint256" },
        { "name": "eventId", "type": "bytes32" }
      ]
    },
    "primaryType": "ForcedTransfer",
    "message": {
      "from": "0xDeceasedAddress1234567890abcdef1234567890ab",
      "to": "0xHeirAddress0987654321fedcba0987654321fedcba",
      "amount": "1000000000000000000",
      "eventId": "0x987f6543..."
    }
  }
}

Example: Dividend Payment​

Request Body:

{
  "issuanceId": "issuance_456e7890-e89b-12d3-a456-426614174111",
  "eventType": "DIVIDEND_PAYMENT",
  "parameters": {
    "dividendPerToken": "50000000000000000",
    "paymentDate": "2025-12-31",
    "recordDate": "2025-12-15",
    "currency": "USDC",
    "totalDividend": "5000000000000000000000"
  },
  "documents": {
    "financialStatement": "https://docs.acme.com/q4-2025-financials.pdf",
    "boardResolution": "https://docs.acme.com/dividend-board-resolution.pdf",
    "auditReport": "https://docs.acme.com/audit-2025.pdf"
  },
  "requestedBy": {
    "name": "Jane CFO",
    "email": "[email protected]",
    "role": "Chief Financial Officer"
  }
}

Response:

{
  "corporateEventId": "event_111a2222-e89b-12d3-a456-426614174555",
  "eventType": "DIVIDEND_PAYMENT",
  "status": "pending_review",
  "submittedAt": "2025-11-10T14:30:00Z",
  "estimatedReviewTime": "2-4 business days"
}

Step 3: Wait for ERIR Validation​

ERIR will review the corporate event and supporting documents. You'll receive notifications via:

  • Email to the requestedBy address
  • Webhook notification (if subscribed)
  • Status updates available via API query

Status Query:

Endpoint: GET /v2/proxy/erir/corporate-event/{id}

Response (Approved):

{
  "corporateEventId": "event_987f6543-e89b-12d3-a456-426614174444",
  "eventType": "FORCED_TRANSFER",
  "status": "approved",
  "approvedAt": "2025-11-13T10:00:00Z",
  "approvedBy": "ERIR Compliance Team",
  "validUntil": "2025-11-20T10:00:00Z",
  "executionReady": true
}

Response (Rejected):

{
  "corporateEventId": "event_987f6543-e89b-12d3-a456-426614174444",
  "eventType": "FORCED_TRANSFER",
  "status": "rejected",
  "rejectedAt": "2025-11-13T10:00:00Z",
  "rejectionReasons": [
    "Court order document expired",
    "Beneficiary identity not verified",
    "Death certificate requires apostille"
  ],
  "canResubmit": true
}

Step 4: Execute the Approved Corporate Event​

Once approved, execute the event on the blockchain.

Endpoint: POST /v2/proxy/erir/corporate-event/{id}/execute

Path Parameters:

  • id: The corporate event ID from Step 2

Request Body:

{
  "executionNotes": "Executing inheritance transfer as approved by ERIR"
}

Response:

{
  "corporateEventId": "event_987f6543-e89b-12d3-a456-426614174444",
  "transactionId": "tx_555b6666-e89b-12d3-a456-426614174666",
  "status": "executing",
  "message": "Corporate event transaction submitted to blockchain",
  "estimatedCompletionTime": "2-5 minutes"
}

TX_MINED Webhook:

{
  "type": "TX_MINED",
  "event": {
    "txUUID": "tx_555b6666-e89b-12d3-a456-426614174666",
    "txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "timestamp": 1699612800
  }
}

💡 Key Concepts​

What are Corporate Events?​

Corporate events are significant actions affecting tokenized securities:

  • Mandatory Events: Required by law or regulation (e.g., forced transfer by court order)
  • Voluntary Events: Initiated by issuer (e.g., dividend payments, buybacks)
  • Compliance Events: Related to regulatory compliance (e.g., freezing suspicious accounts)

ERIR Validation Process​

  1. Submission: Event created with supporting documents
  2. Document Review: ERIR verifies authenticity and completeness
  3. Legal Review: Compliance with regulations checked
  4. Approval Decision: Event approved or rejected with feedback
  5. Execution Window: Approved events must be executed within validity period
  6. Post-Execution: ERIR records the blockchain transaction

Event Lifecycle​

  • Draft: Event created, not yet submitted
  • Pending Review: Submitted to ERIR, awaiting validation
  • Under Review: ERIR actively reviewing documents
  • Approved: Validated and ready for execution
  • Rejected: Not approved, can be resubmitted with corrections
  • Executing: Blockchain transaction in progress
  • Executed: Successfully completed on blockchain
  • Expired: Approval expired before execution

🔗 Related Endpoints​

📚 Additional Resources​