チェーンコード・イベント

ブロックチェーン・アプリケーション・ビルダーの拡張バージョンでは、トークン操作のチェーンコード・イベントを生成できます。

チェーンコード・イベントは、トランザクションの実行時に発行される特定の通知です。イベントには、ブロックチェーン台帳状態の特定の条件や変更について外部システムに通知するために使用できるトランザクション情報が含まれます。チェーンコード・イベントを使用すると、ブロックチェーン上にないアプリケーションとのリアルタイム統合および対話を可能にし、イベント主導のワークフローおよびブロックチェーン環境全体の監視を促進できます。チェーンコード・イベントには、イベント名とペイロードの2つのコンポーネントがあります。

チェーンコード・イベントは、すべてのブロックチェーン・アプリケーション・ビルダー仕様ファイルでサポートされています。チェーンコードイベントを有効にすると、スキャフォールドされたプロジェクト内のすべてのコントローラ関数がイベントを発行します(getterメソッドを除く)。たとえば、トークン・シナリオでは、トークンがミント、転送、書込みまたはロックされたときにチェーンコード・イベントが発行されます

次の例に示すように、仕様ファイルでブール型eventsパラメータを使用してチェーンコード・イベントを有効にします。

assets:
    - name: FiatMoneyTOK # Asset name
      type: token  # Asset type
      events: true  # Generate events for create, update and delete APIs

イベントを有効にすると、次の例に示すように、スキャフォールドされたチェーンコードプロジェクトのコントローラ関数にイベント作成メソッドが含まれます。

TypeScript:

@Validator(yup.string(), yup.string(), yup.string())
public async createAccount(org_id: string, user_id: string, token_type: string) {
  await this.Ctx.Auth.checkAuthorization("ACCOUNT.createAccount", "TOKEN", { org_id });
  await this.Ctx.Model.createEvent(EVENT_NAME.CREATE_ACCOUNT, { org_id, user_id, token_type });
  return await this.Ctx.Account.createAccount(org_id, user_id, token_type);
}

移動:

func (t *Controller) CreateAccount(org_id string, user_id string, token_type string, daily_limits ...account.AccountDailyLimits) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Account.CreateAccount", "TOKEN", map[string]string{"org_id": org_id})
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    err = t.Ctx.Model.CreateEvent(constants.CreateAccountEventName, map[string]interface{}{"org_id": org_id, "user_id": user_id, "token_type": token_type})
    if err != nil {
        return nil, err
    }
    return t.Ctx.Account.CreateAccount(org_id, user_id, token_type, daily_limits...)
}

チェーンコード・イベントでは、名前およびペイロード・コンポーネントに次のデフォルト値が使用されます。デフォルト値は必要に応じて変更できます。

EventName
コントローラ関数の名前。
ペイロード
コントローラ関数のすべての入力パラメータを含む JSONオブジェクト。
拡張トークン・タクソノミ・フレームワークおよびERC-1155標準で、新しいeventsパラメータもトークン詳細に追加されました。仕様ファイルのeventsパラメータがtrueに設定されている場合、生成されたトークンのeventsパラメータはtrueに設定されます。仕様ファイルのeventsパラメータがfalseに設定されているか、定義されていない場合、生成されたトークンのeventsパラメータはfalseに設定されます。次の例は、TypeScriptとGoの両方の新しいeventsパラメータを持つトークンを示しています。
{
    "metadata": {
        "paintingName": "monalisa",
        "description": "monalisa painting",
        "image": "image link",
        "painterName": "Leonardo da Vinci"
    },
    "assetType": "otoken",
    "events": true,
    "quantity": 1,
    "tokenId": "artnft",
    "tokenName": "artcollection",
    "tokenDesc": "artcollection nft",
    "tokenStandard": "erc1155+",
    "tokenType": "nonfungible",
    "tokenUnit": "whole",
    "behaviors": [
        "indivisible",
        "singleton",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "roles": {
        "minter_role_name": "minter",
        "burner_role_name": "burner"
    },
    "mintable": {
        "max_mint_quantity": 500
    },
    "owner": "oaccount~42e89f4c72dfde9502814876423c6da630d466e87436dd1aae201d347ad1288d",
    "createdBy": "oaccount~42e89f4c72dfde9502814876423c6da630d466e87436dd1aae201d347ad1288d",
    "creationDate": "2022-12-29T04:08:35.000Z",
    "isBurned": false,
    "tokenUri": "tu",
    "price": 10000,
    "onSaleFlag": false
}
{
    "AssetType": "otoken",
    "Behavior": [
        "indivisible",
        "singleton",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "CreatedBy": "oaccount~42e89f4c72dfde9502814876423c6da630d466e87436dd1aae201d347ad1288d",
    "CreationDate": "2022-12-29T09:57:03+05:30",
    "Events": true,
    "IsBurned": false,
    "Mintable": {
        "Max_mint_quantity": 500
    },
    "OnSaleFlag": false,
    "Owner": "oaccount~42e89f4c72dfde9502814876423c6da630d466e87436dd1aae201d347ad1288d",
    "Price": 100,
    "Quantity": 1,
    "Roles": {
        "burner_role_name": "burner",
        "minter_role_name": "minter"
    },
    "TokenDesc": "token description",
    "TokenId": "monalisa",
    "TokenMetadata": {
        "Description": "Mona Lisa Painting",
        "Image": "monalisa.jpeg",
        "PainterName": "Leonardo_da_Vinci",
        "PaintingName": "Mona_Lisa"
    },
    "TokenName": "artcollection",
    "TokenStandard": "erc1155+",
    "TokenType": "nonfungible",
    "TokenUnit": "whole",
    "TokenUri": "https://bafybeid6pmpp62bongoip5iy2skosvyxh3gr7r2e35x3ctvawjco6ddmsq\\\\ .ipfs.infura-ipfs.io/?filename=MonaLisa.jpeg"
}

イベントの生成

stub.setEventメソッドを使用すると、トランザクションの実行時にチェーンコードでイベントを作成および発行できます。次のコードは、メソッドのTypeScriptバージョンを示しています。
async setEvent(eventName: string, payload: Buffer): Promise<void>

この例では、eventNameはイベントに割り当てる名前で、payloadはイベントに関連付けられたデータです。ペイロードには、イベントとともに送信する情報(通常はJSON形式でシリアライズ)を含めることができます。

バッチ方法のチェーンコード・イベント

拡張されたERC-1155標準では、バッチ・メソッドがサポートされています。バッチ・メソッドは、パラメータとして渡される複数のトークンで動作します。バッチ・メソッドの場合、チェーンコード・イベントは、仕様ファイルでeventsパラメータがtrueに設定されているトークンのみに対して発行されます。

バッチ・メソッドで完了したトランザクションごとに、対応するチェーンコード・イベントが生成されます。各チェーンコード・イベントのペイロードには、トランザクション詳細が含まれます。たとえば、BatchTransferメソッドを使用して5つの異なるトークンの数量を転送すると、対応する5つのチェーンコード・イベントが発行されます。各イベントのペイロードには、トークン詳細および転送済数量と、すべてのバッチ転送に適用可能な共通パラメータが含まれます。

次の例は、拡張されたERC-1155標準を使用したイベントコードを示しています。
@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.array().of(yup.string()), yup.array().of(yup.number()))
  public async batchTransferFrom(
    fromOrgId: string,
    fromUserId: string,
    toOrgId: string,
    toUserId: string,
    tokenIds: string[],
    quantity: number[]
  ) {
    const fromAccountId = this.Ctx.ERC1155Account.generateAccountId(fromOrgId, fromUserId, ACCOUNT_TYPE.USER_ACCOUNT);
    const toAccountId = this.Ctx.ERC1155Account.generateAccountId(toOrgId, toUserId, ACCOUNT_TYPE.USER_ACCOUNT);
    let tokenAssets = [];
    for (let i = 0; i < tokenIds.length; i++) {
      const tokenAsset = await this.Ctx.ERC1155Token.get(tokenIds[i]);
      tokenAssets.push(tokenAsset);
    }
    await this.Ctx.Model.createEventForBatch(EVENT_NAME.BATCH_TRANSFER_FROM, { fromOrgId, fromUserId, toOrgId, toUserId }, quantity, tokenAssets);
    return await this.Ctx.ERC1155Token.batchTransferFrom(fromAccountId, toAccountId, tokenIds, quantity);
  }

複数資産のチェーンコード・イベント

拡張されたトークン・タクソノミ・フレームワークおよびERC-1155標準では、仕様ファイルでの複数のトークン・アセットの定義がサポートされています。チェーンコード・イベントの動作は、メソッドがトークン固有(トークンの作成や更新など)か共通(ミントや書込みなど)かによって異なります。

トークン固有のメソッドの場合、チェーンコード・イベントは、仕様ファイルでeventsパラメータがtrueに設定されているトークンのみに対して生成されます。

共通メソッドの場合、指定ファイルでeventsパラメータがtrueに設定されたトークンがある場合、チェーンコード・イベントはスキャフォールドされたプロジェクトで生成されます。実際のチェーンコード・イベントの動作は、メソッドに渡されるトークンIDパラメータの数に基づきます。

  • 単一のトークンIDがパラメータとして渡された場合、チェーンコード・イベントは、対応するトークン詳細のeventsパラメータがtrueに設定されている場合にのみ生成されます。
  • 複数のトークンIDがパラメータとして渡された場合、いずれかのトークン詳細のeventsパラメータがtrueに設定されている場合にのみチェーンコード・イベントが生成されます。
  • トークンIDがパラメータとして渡されない場合、チェーンコード・イベントは常に生成されます。
次に、2つのトークンを渡す必要がある一般的なメソッドを示します。このリストは、拡張トークン・タクソノミ・フレームワーク標準に適用されます。
  • addConversionRate(from_token_id: string, to_token_id: string, token_conversion_rate: number)
  • updateConversionRate(from_token_id: string, to_token_id: string, token_conversion_rate: number)
  • tokenConversion(from_token_id: string, to_token_id: string, to_org_id: string, to_user_id: string,token_quantity: number)
  • exchangeToken(fromTokenId: string, fromOrgId: string, fromUserId: string, fromTokenQuantity: number, toTokenId: string, toOrgId: string,toUserId: string,toTokenQuantity: number)
次のリストは、引数としてトークンを取得しない一般的なメソッドを示しています。次のリストは、拡張トークン・タクソノミ・フレームワーク標準に適用されます。
  • addTokenAdmin(org_id: string, user_id: string)
  • removeTokenAdmin(org_id: string, user_id: string)
  • addOrgAdmin(org_id: string, user_id: string)
  • removeOrgAdmin(org_id: string, user_id: string)
  • createAccount(org_id: string, user_id: string, token_type: string)
  • deleteHistoricalTransactions(time_to_expiration: Date)
  • initializeExchangePoolUser(org_id: string, user_id: string)
このリストは、拡張ERC-1155規格の引数としてトークンを取得しない一般的なメソッドを示しています。
  • addTokenAdmin(orgId: string, userId: string)
  • removeTokenAdmin(orgId: string, userId: string)
  • createAccount(orgId: string, userId: string, ftAccount: boolean, nftAccount: boolean)
  • createUserAccount(orgId: string, userId: string)
  • createTokenAccount(orgId: string, userId: string, tokenType: TokenType)
  • addTokenSysRole(orgId: string, userId: string, role: string)
  • removeTokenSysRole(orgId: string, userId: string, role: string)
  • transferTokenSysRole(fromOrgId: string, fromUserId: string, toOrgId: string, toUserId: string, role: string)
  • deleteHistoricalTransactions(time_to_expiration: Date)

TypeScriptチェーンコード・イベントのSDKメソッド

createEvent
このメソッドは、指定されたイベント名とペイロードに基づいてイベントを生成します。
public async createEvent(eventName: any, eventPayload: any, assets?: any)
パラメータ:
  • eventName: string– イベントの生成時に使用するイベント名。
  • eventPayload: map[string]interface{}– イベントの生成時に使用するイベント・ペイロード。
  • assets– オプションで、トークン・アセットをパラメータとしてメソッドに渡すことができます。
createEventForBatch
このメソッドは、mintBatchメソッドやburnBatchメソッドなどのバッチ操作のイベントを生成します。
public async createEventForBatch(eventName: any, eventPayload: any, quantities: number[], assets: any)
パラメータ:
  • eventName: string– イベントの生成時に使用するイベント名。
  • eventPayload: map[string]interface{}– イベントの生成時に使用するイベント・ペイロード。
  • quantities: number[]– バッチ・メソッド・トランザクションで使用するトークンの数を表す、各トークンIDに対応する金額のリスト。
  • assets– オプションで、トークン・アセットをパラメータとしてメソッドに渡すことができます。

チェーンコード・イベントのGo SDKメソッド

CreateEvent
このメソッドは、指定されたイベント名とペイロードに基づいてイベントを生成します。
func (m *Model) CreateEvent(eventName string, eventPayload map[string]interface{}, assets ...interface{})
パラメータ:
  • eventName: string– イベントの生成時に使用するイベント名。
  • eventPayload: map[string]interface{}– イベントの生成時に使用するイベント・ペイロード。
  • assets– オプションで、トークン・アセットをパラメータとしてメソッドに渡すことができます。
CreateEventForBatch
このメソッドは、mintBatchメソッドやburnBatchメソッドなどのバッチ操作のイベントを生成します。
func (m *Model) CreateEventForBatch(eventName string, eventPayload map[string]interface{}, quantities []float64, assets []interface{})
パラメータ:
  • eventName: string– イベントの生成時に使用するイベント名。
  • eventPayload: map[string]interface{}– イベントの生成時に使用するイベント・ペイロード。
  • quantities: []float64– バッチ・メソッド・トランザクションで使用するトークンの数を表す、各トークンIDに対応する金額のリスト。
  • assets– オプションで、トークン・アセットをパラメータとしてメソッドに渡すことができます。

ブロックチェーン・アプリケーション・ビルダーのチェーンコードでのイベント生成

仕様ファイルのeventsパラメータがtrueに設定されている場合、getter APIとして指定されているものを除き、すべてのコントローラAPIに対してチェーンコード・イベント・コードが生成されます。次の例は、TypeScriptとGoの両方でチェーンコード・イベントが有効になっているコントローラAPIを示しています。
@Validator(yup.string(), yup.string(), yup.string())
public async createAccount(org_id: string, user_id: string, token_type: string) {
  await this.Ctx.Auth.checkAuthorization("ACCOUNT.createAccount", "TOKEN", { org_id });
  await this.Ctx.Model.createEvent(EVENT_NAME.CREATE_ACCOUNT, { org_id, user_id, token_type });
  return await this.Ctx.Account.createAccount(org_id, user_id, token_type);
}
func (t *Controller) CreateAccount(org_id string, user_id string, token_type string, daily_limits ...account.AccountDailyLimits) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Account.CreateAccount", "TOKEN", map[string]string{"org_id": org_id})
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    err = t.Ctx.Model.CreateEvent(constants.CreateAccountEventName, map[string]interface{}{"org_id": org_id, "user_id": user_id, "token_type": token_type})
    if err != nil {
        return nil, err
    }
    return t.Ctx.Account.CreateAccount(org_id, user_id, token_type, daily_limits...)
}
チェーンコード・イベントは、次のデフォルト値で生成されます。これらの値は、必要に応じて変更できます。
  • EventName: コントローラ関数の名前。
  • Payload: コントローラ関数のすべての入力パラメータを含むJSONオブジェクト。