Evénements de code chaîne

La version améliorée de Blockchain App Builder peut générer des événements de code chaîne pour les opérations de jeton.

Les événements de code chaîne sont des notifications spécifiques émises lors de l'exécution des transactions. Les événements incluent des informations de transaction qui peuvent être utilisées pour informer les systèmes externes de conditions spécifiques ou de modifications de l'état du registre de blockchain. Vous pouvez utiliser les événements de code chaîne pour permettre l'intégration et l'interaction en temps réel avec des applications ne figurant pas sur la chaîne de blocs, et pour faciliter les workflows et la surveillance basés sur les événements dans l'environnement de chaîne de blocs. Les événements de code chaîne sont constitués de deux composants : le nom de l'événement et la charge utile.

Les événements de code chaîne sont pris en charge pour tous les fichiers de spécification Blockchain App Builder. Si vous activez les événements de code chaîne, toutes les fonctions de contrôleur de votre projet échafaudé émettront des événements, à l'exception des méthodes get. Par exemple, dans un scénario de jeton, des événements de code chaîne sont émis lorsque des jetons sont extraits, transférés, brûlés ou verrouillés

Vous utilisez le paramètre booléen events dans le fichier de spécification pour activer les événements de code chaîne, comme indiqué dans l'exemple suivant.

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

Si vous activez des événements, les fonctions du contrôleur dans votre projet de code chaîne échafaudé incluront des méthodes de création d'événements, comme indiqué dans les exemples suivants.

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);
}

Exécuter

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...)
}

Les événements de code chaîne utilisent les valeurs par défaut suivantes pour le nom et les composants de charge utile. Vous pouvez modifier les valeurs par défaut si nécessaire.

EventName
Nom de la fonction de contrôleur.
Charge utile
Objet JSON contenant tous les paramètres d'entrée de la fonction de contrôleur.
Un nouveau paramètre events a également été ajouté aux détails du jeton dans la structure de taxonomie de jeton étendue et les normes ERC-1155. Si le paramètre events du fichier de spécification est défini sur True, le paramètre events du jeton généré est défini sur True. Si le paramètre events dans le fichier de spécification est défini sur False ou n'est pas défini, le paramètre events dans le jeton généré est défini sur False. Les exemples suivants montrent un jeton avec le nouveau paramètre events pour TypeScript et Go.
{
    "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"
}

Génération d'événements

La méthode stub.setEvent permet au code chaîne de créer et d'émettre un événement lorsqu'une transaction est exécutée. Le code suivant indique la version TypeScript de la méthode.
async setEvent(eventName: string, payload: Buffer): Promise<void>

Dans cet exemple, eventName est le nom à affecter à l'événement et payload est les données associées à l'événement. La charge utile peut contenir toutes les informations que vous souhaitez envoyer avec l'événement, généralement sérialisées au format JSON.

Evénements de code chaîne pour les méthodes par lots

La norme ERC-1155 améliorée prend en charge les méthodes par lots. Les méthodes par lots fonctionnent sur plusieurs jetons transmis en tant que paramètres. Pour les méthodes par lots, les événements de code chaîne sont émis uniquement pour les jetons pour lesquels le paramètre events est défini sur true dans le fichier de spécification.

Pour chaque transaction effectuée dans la méthode par lots, un événement de code chaîne correspondant est généré. La charge utile de chaque événement de code chaîne contient les détails de la transaction. Par exemple, si vous utilisez la méthode BatchTransfer pour transférer des quantités de cinq jetons différents, cinq événements de code chaîne correspondants sont émis. La charge utile de chaque événement contient les détails du jeton et la quantité transférée, ainsi que les paramètres communs applicables à tous les transferts par lots.

L'exemple suivant illustre le code d'événement utilisant la norme ERC-1155 améliorée.
@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);
  }

Evénements de code chaîne pour plusieurs ressources

La structure de taxonomie de jeton améliorée et les normes ERC-1155 prennent en charge la définition de plusieurs ressources de jeton dans un fichier de spécification. Le comportement de l'événement de code chaîne est différent selon qu'une méthode est propre à un jeton (comme la création ou la mise à jour d'un jeton) ou commune (comme la frappe ou la gravure).

Pour les méthodes propres aux jetons, les événements de code chaîne sont générés uniquement pour les jetons pour lesquels le paramètre events est défini sur true dans le fichier de spécification.

Pour les méthodes courantes, les événements de code chaîne sont générés dans le projet échafaudé si le paramètre events est défini sur true dans le fichier de spécification pour un jeton. Le comportement réel de l'événement de code chaîne est basé sur le nombre de paramètres d'ID de jeton transmis à la méthode.

  • Si un seul ID de jeton est transmis en tant que paramètre, les événements de code chaîne sont générés uniquement si le paramètre events dans les détails de jeton correspondants est défini sur True.
  • Si plusieurs ID de jeton sont transmis en tant que paramètres, les événements de code chaîne sont générés uniquement si le paramètre events de l'un des détails de jeton est défini sur True.
  • Si aucun ID de jeton n'est transmis en tant que paramètre, les événements de code chaîne sont toujours générés.
La liste suivante présente les méthodes courantes qui doivent recevoir deux jetons. Cette liste s'applique à la norme étendue Token Taxonomy Framework.
  • 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)
La liste suivante présente les méthodes courantes qui ne prennent pas de jetons comme arguments. La liste suivante s'applique à la norme étendue Token Taxonomy Framework.
  • 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)
Cette liste présente les méthodes courantes qui ne prennent pas les jetons comme arguments pour la norme ERC-1155 étendue.
  • 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 Méthodes SDK pour les événements de code chaîne

createEvent
Cette méthode génère des événements en fonction d'un nom d'événement et d'une charge utile spécifiés.
public async createEvent(eventName: any, eventPayload: any, assets?: any)
Paramètres :
  • eventName: string : nom d'événement à utiliser lors de la génération d'événements.
  • eventPayload: map[string]interface{} : charge utile d'événement à utiliser lors de la génération d'événements.
  • assets : la ressource de jeton peut éventuellement être transmise en tant que paramètre à la méthode.
createEventForBatch
Cette méthode génère des événements pour les opérations de batch, telles que les méthodes mintBatch ou burnBatch.
public async createEventForBatch(eventName: any, eventPayload: any, quantities: number[], assets: any)
Paramètres :
  • eventName: string : nom d'événement à utiliser lors de la génération d'événements.
  • eventPayload: map[string]interface{} : charge utile d'événement à utiliser lors de la génération d'événements.
  • quantities: number[] : liste des montants, correspondant à chaque ID de jeton, qui représentent le nombre de jetons à utiliser dans les transactions de méthode par lots.
  • assets : la ressource de jeton peut éventuellement être transmise en tant que paramètre à la méthode.

Méthodes Go SDK pour les événements de code chaîne

CreateEvent
Cette méthode génère des événements en fonction d'un nom d'événement et d'une charge utile spécifiés.
func (m *Model) CreateEvent(eventName string, eventPayload map[string]interface{}, assets ...interface{})
Paramètres :
  • eventName: string : nom d'événement à utiliser lors de la génération d'événements.
  • eventPayload: map[string]interface{} : charge utile d'événement à utiliser lors de la génération d'événements.
  • assets : la ressource de jeton peut éventuellement être transmise en tant que paramètre à la méthode.
CreateEventForBatch
Cette méthode génère des événements pour les opérations de batch, telles que les méthodes mintBatch ou burnBatch.
func (m *Model) CreateEventForBatch(eventName string, eventPayload map[string]interface{}, quantities []float64, assets []interface{})
Paramètres :
  • eventName: string : nom d'événement à utiliser lors de la génération d'événements.
  • eventPayload: map[string]interface{} : charge utile d'événement à utiliser lors de la génération d'événements.
  • quantities: []float64 : liste des montants, correspondant à chaque ID de jeton, qui représentent le nombre de jetons à utiliser dans les transactions de méthode par lots.
  • assets : la ressource de jeton peut éventuellement être transmise en tant que paramètre à la méthode.

Génération d'événements dans Blockchain App Builder Chaincode

Si le paramètre events du fichier de spécification est défini sur True, le code d'événement de code chaîne est généré pour toutes les API de contrôleur, à l'exception de celles désignées comme API get. Les exemples suivants montrent des API de contrôleur avec des événements de code chaîne activés pour TypeScript et Go.
@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...)
}
Les événements de code chaîne sont générés avec les valeurs par défaut suivantes. Vous pouvez modifier ces valeurs si nécessaire.
  • EventName : nom de la fonction de contrôleur.
  • Payload : objet JSON contenant tous les paramètres d'entrée de la fonction de contrôleur.