# 🧵 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
- [Postman UI](https://documenter.getpostman.com/view/23227807/2sB2qWH4FD)
- [Swagger UI Token City Blockchain API](../api-1.8.1/blockchain-api-token-city)
---
## ✨ 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
| :---------------------- | :------------------------------------------------ | :----- | :---------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------- |
| Get Available Events | `GET /v2/proxy/erir/corporate-event` | GET | - | List of available events and required data for each one | Retrieves all available corporate event types and their requirements |
| Create Corporate Event | `POST /v2/proxy/erir/corporate-event` | POST | `Event type, parameters, documents` | Corporate event ID, EIP712 object, required signatures | Creates a corporate event with supporting documents for ERIR review |
| Execute Corporate Event | `POST /v2/proxy/erir/corporate-event/:id/execute` | POST | `Corporate event ID` | Transaction ID, blockchain confirmation | Executes the ERIR-validated corporate event on blockchain |
---
## 🎨 Workflow Visualizations
### 🌊 Mermaid Sequence Diagram
```mermaid
sequenceDiagram
participant Client
participant GeneralAPI
participant ERIR
participant Blockchain
Client->>GeneralAPI: GET /v2/proxy/erir/corporate-event
GeneralAPI-->>Client: Available event types
Client->>GeneralAPI: POST /v2/proxy/erir/corporate-event
GeneralAPI->>ERIR: Submit for validation
ERIR-->>GeneralAPI: Validation result
GeneralAPI-->>Client: Corporate event ID
alt Event approved
Client->>GeneralAPI: POST /v2/proxy/erir/corporate-event/:id/execute
GeneralAPI->>Blockchain: Execute event transaction
Blockchain-->>GeneralAPI: TX_MINED
GeneralAPI-->>Client: Event executed
GeneralAPI-->>Client: Webhook: TX_MINED
else Event rejected
ERIR-->>Client: Rejection notice with reasons
end
```
---
## 📝 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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):**
```json
{
"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):**
```json
{
"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:**
```json
{
"executionNotes": "Executing inheritance transfer as approved by ERIR"
}
```
**Response:**
```json
{
"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:**
```json
{
"type": "TX_MINED",
"event": {
"txUUID": "tx_555b6666-e89b-12d3-a456-426614174666",
"txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
"corporateEventId": "event_987f6543-e89b-12d3-a456-426614174444",
"eventType": "FORCED_TRANSFER",
"blockNumber": 12345678,
"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
---
## ⚠️ Important Notes
1. **ERIR Approval Required**: All corporate events require ERIR validation before execution
2. **Documentation**: Provide complete, certified documents to avoid rejection
3. **Review Time**: Plan for 3-5 business day review period
4. **Validity Period**: Execute approved events within the validity window
5. **Irreversible**: Once executed, corporate events cannot be undone
6. **Compliance**: Ensure events comply with token's governing jurisdiction
7. **Notification**: Subscribe to webhooks for status updates
8. **Record Keeping**: ERIR maintains permanent records of all events
---
## 🔗 Related Endpoints
- [Get Corporate Events](https://documenter.getpostman.com/view/23227807/2sB2qWH4FD)
- [Create Corporate Event](https://documenter.getpostman.com/view/23227807/2sB2qWH4FD)
- [Execute Corporate Event](https://documenter.getpostman.com/view/23227807/2sB2qWH4FD)
- [Webhook Notifications](./send-transaction-and-receive-status-via-webhook)
---
## 🆘 Troubleshooting
### Corporate Event Rejected
If your event is rejected:
- ✓ Review rejection reasons carefully
- ✓ Ensure all documents are officially certified
- ✓ Verify documents are current and not expired
- ✓ Check that beneficiaries/parties have verified identities
- ✓ Provide additional supporting documentation
- ✓ Contact ERIR support for clarification
- ✓ Resubmit with corrections
### Execution Failed
If execution fails after approval:
- ✓ Check if approval has expired
- ✓ Verify sufficient gas is available
- ✓ Ensure addresses are still valid
- ✓ Check token is not paused
- ✓ Verify agent permissions are current
- ✓ Review blockchain transaction logs
- ✓ Contact technical support
### Document Verification Issues
If documents aren't accepted:
- ✓ Ensure PDFs are searchable (not scanned images only)
- ✓ Verify URLs are publicly accessible
- ✓ Check documents are in accepted languages
- ✓ Provide certified translations if needed
- ✓ Ensure signatures are visible and valid
- ✓ Include all referenced exhibits/attachments
### Approval Taking Too Long
If review exceeds estimated time:
- ✓ Check status via API for updates
- ✓ Verify all documents were submitted correctly
- ✓ Look for requests for additional information
- ✓ Contact ERIR support for status update
- ✓ Check if document re-submission is needed
---
## 📚 Additional Resources
- [ERC-3643 Corporate Actions](https://eips.ethereum.org/EIPS/eip-3643)
- [ERIR Documentation](https://documenter.getpostman.com/view/23227807/2sB2qWH4FD)
- [Securities Regulations Guide](https://www.esma.europa.eu/)
- [Recover Lost Account Guide](./recover-lost-account)
- [Create Valid Issuer Guide](./create-valid-issuer-on-erir)
---
## 💼 Use Case Examples
### Example 1: Inheritance Transfer
**Scenario:** Token holder passed away, heir needs to claim tokens
**Step 1 - Gather Documents:**
- Death certificate
- Probate court order
- Will or testament
- Heir identity verification
**Step 2 - Create Event:**
```json
{
"eventType": "FORCED_TRANSFER",
"parameters": {
"fromAddress": "0xDeceased...",
"toAddress": "0xHeir...",
"amount": "5000000000000000000"
}
}
```
**Step 3 - ERIR Review:**
- 4-day review period
- Approved after document verification
**Step 4 - Execute:**
5 tokens transferred to heir's account
**Result:** Compliant inheritance transfer with full audit trail.
---
### Example 2: Quarterly Dividend Payment
**Scenario:** Company declares $500,000 dividend for 10,000 token holders
**Step 1 - Board Resolution:**
- Approve dividend payment
- Set record date and payment date
- Prepare financial statements
**Step 2 - Create Event:**
```json
{
"eventType": "DIVIDEND_PAYMENT",
"parameters": {
"dividendPerToken": "50000000000000000",
"paymentDate": "2025-12-31",
"recordDate": "2025-12-15"
}
}
```
**Step 3 - ERIR Approval:**
- 3-day review
- Verified financial capacity
**Step 4 - Execute:**
- Smart contract distributes USDC to all holders
- Proportional to tokens held on record date
**Result:** Automated, compliant dividend distribution to all eligible holders.
---
### Example 3: AML Compliance - Account Freeze
**Scenario:** Suspicious activity detected on investor account
**Step 1 - Compliance Investigation:**
- AML team reviews transactions
- Prepares compliance report
- Obtains legal opinion
**Step 2 - Create Event:**
```json
{
"eventType": "FREEZE_ADDRESS",
"parameters": {
"address": "0xSuspicious...",
"reason": "AML investigation - suspicious transaction patterns"
}
}
```
**Step 3 - ERIR Fast-Track:**
- 1-day expedited review for compliance matters
- Approved based on AML documentation
**Step 4 - Execute:**
Account frozen immediately upon execution
**Result:** Rapid compliance action while maintaining regulatory oversight and audit trail.