Créer une stratégie

Une stratégie est un ensemble de règles qui peut bloquer les demandes de signature. Les demandes de signature incluent les transactions blockchain et les demandes de signature de données, telles que les données typées EIP-712. Chaque règle stockée a une portée, des conditions et une réponse BLOCK. Les règles activées s'appliquent de manière cumulative : si une règle applicable correspond, la demande est refusée.

Si l'évaluation de stratégie aboutit et qu'aucune règle applicable ne renvoie de réponse BLOCK, la demande peut continuer après que UWaaS Wallet Manager (UWM) a authentifié l'appelant, autorisé le portefeuille et la clé et validé la demande de signature.

Pour plus d'informations sur UWaaS Wallet Manager, reportez-vous à Portefeuille universel en tant que service (UWaaS). Pour les champs et les opérations de demande d'API, reportez-vous à API Universal Wallet Manager, notamment :

Définir des conditions de règle

Une règle combine des conditions avec all, any et not. Vous pouvez imbriquer ces groupes pour définir une restriction :

all correspond à chaque condition enfant.
any correspond lorsqu'au moins une condition enfant correspond.
not correspond lorsque sa condition enfant ne correspond pas.

Définir des groupes de conditions en ligne. Les références de condition nommées ne sont pas prises en charge pour les règles de signature UWM.

Une feuille de condition indique un fait, un opérateur et une valeur. Utilisez path pour sélectionner une propriété imbriquée dans un fait. Les valeurs priority supérieures sont évaluées en premier.

{
  "fact": "to_address",
  "operator": "in",
  "value": ["<blocked-address>"]
}

L'opérateur in correspond lorsque le fait est égal à l'une des valeurs répertoriées. Utilisez all pour combiner cette condition avec une condition operation. Utilisez any lorsque l'une des conditions suivantes peut déclencher la restriction.

Opérateurs

Opérateur	Utilisez-le quand
`equal`, `notEqual`	Un fait scalaire doit être égal ou différent d'une valeur du même type.
`in`, `notIn`	Un fait scalaire doit apparaître ou non dans une liste de valeurs.
`contains`, `doesNotContain`	Un fait de tableau doit contenir ou non une valeur.
`lessThan`, `lessThanEquals` (`lessThanInclusive`)	Un fait numérique doit être inférieur ou inférieur ou égal à une valeur numérique.
`greaterThan`, `greaterThanEquals` (`greaterThanInclusive`)	Un fait numérique doit être supérieur ou égal à une valeur numérique.

Les comparaisons triées sur amount, amount_atomic et native_value_atomic utilisent l'arithmétique décimale exacte sur /evaluate et /internal/v1/authorize.

Utilisez des chaînes décimales pour les quantités atomiques et les seuils volumineux. Exemple :

{ "fact": "amount_atomic", "operator": "greaterThanEquals", "value": "1000000000000000000" }

UWM fournit amount_atomic en unités de base et ne le convertit pas en décimales de jeton. Le fait amount est pris en charge lorsqu'il est fourni par un appelant de /evaluate ; UWM ne l'ajoute pas aux faits de signature.

Les nombres JSON décimaux compris dans la plage numérique sécurisée sont acceptés. Envoyez des valeurs numériques plus grandes sous forme de chaînes ; les littéraux numériques plus grands sont rejetés. Les noms d'opérateur greaterThanInclusive et lessThanInclusive restent pris en charge. Les opérateurs equal et notEqual comparent les valeurs par type. D'autres faits conservent leur comportement de comparaison existant.

Décorateurs de tableau

Préfixez un opérateur avec un décorateur et le signe deux-points, tel que someFact:equal. Les décorateurs modifient la façon dont l'opérateur gère les tableaux ou leurs résultats.

Décorateur	Utilisez-le quand
`someFact`	Au moins un élément d'un fait de tableau correspond.
`everyFact`	Tous les éléments d'un tableau correspondent.
`someValue`	Le fait correspond à au moins un élément d'une valeur de tableau.
`everyValue`	Le fait correspond à chaque élément d'une valeur de tableau.
`swap`	La comparaison utilise la valeur comme fait et le fait comme valeur.
`not`	Le résultat de l'opérateur de base doit être négatif.

Par exemple, someFact:equal peut correspondre à un ID de jeton dans le tableau token_ids fourni pour un appel de batch ERC-1155 décodé :

{
  "fact": "token_ids",
  "operator": "someFact:equal",
  "value": "42"
}

Utilisez le groupe de conditions not pour la logique booléenne et le décorateur not: pour annuler un opérateur individuel. Les priorités de condition et de règle définissent l'ordre d'évaluation. Elles ne permettent pas à une règle de remplacer une autre règle correspondante BLOCK.

Définir la portée de la règle

Définissez scopelevels et targets pour indiquer les demandes de signature couvertes par une règle. Chaque portée sélectionnée doit correspondre. Les cibles d'une même portée sont des alternatives.

Portée	Cible requise	Utilisez-le pour
`global`	Aucun ; spécifier `scopelevels: ["global"]` par elle-même.	Restriction applicable à chaque demande de signature.
`org`	`targets.orgIds`	Restriction pour une ou plusieurs organisations.
`wallet`	`targets.walletIds`	Restriction pour un ou plusieurs portefeuilles.
`instance`	`targets.instanceIds`	Restriction pour une ou plusieurs instances réseau.
`asset`	`targets.assetIds`	Règles existantes de portée ressource ; conservées pour compatibilité.

Combiner les portées lorsqu'une règle dépend de plusieurs dimensions. Exemple :

scopelevels: ["org",
        "wallet"]

nécessite que les cibles d'organisation et de portefeuille correspondent. Une règle de portefeuille uniquement n'a pas de limite d'organisation implicite. Utilisez les ID renvoyés par UWM et non les noms d'affichage.

Pour restreindre une méthode de contrat, faites correspondre contract_address et function_selector dans les conditions. Ajoutez la portée instance si la même méthode requiert des restrictions différentes sur différents réseaux. La portée asset est conservée pour les règles existantes ; ces conditions ne l'exigent pas.

Pour targets.instanceIds, utilisez l'élément instanceId public affiché par le portefeuille ou l'API réseau de UWM. Il s'agit de l'élément infra_instance_id inscrit, et non de la clé de base de données numérique ou de l'ID chaîne. Mettez à jour les anciennes règles de portée instance qui utilisent une clé de base de données ; UWM envoie désormais uniquement l'identificateur d'instance publique.

Correspondance avec la demande de signature

Les conditions ne peuvent utiliser que les faits fournis pour operation de la demande. Le fait operation est disponible pour chaque demande de signature.

`operation`	Faits supplémentaires
`native-transfer`	`amount_atomic`, `to_address`
`erc20-transfer`	`amount_atomic`, `to_address`, `contract_address`
`contract-deployment`	`amount_atomic`, `init_code_hash`
`contract-call`	`contract_address`, `native_value_atomic`, `function_selector`, `calldata_hash`
`eip712`	`primary_type`, `verifying_contract`, `typed_data`

UWM reconnaît les appels transfer(address,uint256) ERC-20 canoniques avec zéro valeur native sans enregistrement de jeton. UWM ne lit plus capability.approved-token-contracts.

Le profil erc20-transfer fournit également native_value_atomic ("0"), function_selector ("0xa9059cbb") et calldata_hash. Ces faits permettent aux règles contract-call existantes de conserver toutes leurs restrictions.

Une opération erc20-transfer est également une opération contract-call pour les conditions d'opération. Les deux types de règle peuvent correspondre à la même demande, et toute BLOCK correspondante la refuse. Ce comportement s'applique aux conditions booléennes imbriquées, equal, notEqual, in et notIn sur les deux endpoints d'évaluation. D'autres faits conservent leur sémantique normale de l'égalité.

L'opération erc20-transfer correspond aux méthodes transfer, et non transferFrom ou ERC-1155. Incluez toujours le paramètre contract_address voulu dans les règles de jeton.

Les appels Canonical ERC-20 transferFrom, ERC-1155 safeTransferFrom et ERC-1155 safeBatchTransferFrom fournissent des faits supplémentaires contract-call :

Appeler	Faits supplémentaires
ERC-20 `transferFrom`	`owner_address`, `to_address`, `amount_atomic`
ERC-1155 `safeTransferFrom`	`owner_address`, `to_address`, `token_id`, `amount_atomic`
ERC-1155 `safeBatchTransferFrom`	Baies `owner_address`, `to_address`, parallèles `token_ids` et `amounts`

UWM décode uniquement les appels avec une disposition ABI canonique prise en charge. Les autres appels conservent les faits contract-call génériques.

owner_address est l'adresse source dans les données d'appel et non le portefeuille de signature. Un sélecteur identifie la disposition des données d'appel et non le comportement du contrat déployé. ERC-20 et ERC-721 partagent le sélecteur transferFrom, ainsi appliquer les conditions de montant uniquement à un contrat connu pour mettre en œuvre ERC-20. Les adresses et les sélecteurs sont normalisés en minuscules. Utilisez des valeurs de condition minuscules. Pour les appels par lots, ne totalisez pas les montants pour différents ID de jeton.

amount_atomic et native_value_atomic sont des chaînes décimales dans les unités de base ; la valeur native est en wei. Les valeurs entières EIP-712 sont également des chaînes décimales. Pour EIP-712, typed_data contient le domaine signé et le message. Une valeur path est relative à ce fait : utilisez $.message.value pour la valeur de message et $.domain.chainId pour l'ID de chaîne signé.

Les restrictions de portefeuille, d'organisation et de réseau appartiennent aux portées wallet, org et instance. Les métadonnées de signataire, de gaz et de nonce ne sont pas des faits de condition. La cible de portée asset n'ajoute pas de fait de condition asset.

Avant d'activer une règle de signature

Utilisez uniquement les faits répertoriés pour l'opération sous Correspondance avec la demande de signature. Incluez une condition operation lorsqu'une règle utilise des faits propres à une opération.

L'enregistrement d'une règle ne confirme pas que UWM peut l'évaluer lors de la signature. Par exemple, UWM ne fournit pas de fait tier. Une règle qui vérifie si tier est égal à gold peut entraîner l'échec de la signature avec une erreur 500 générique.

Si la signature échoue après l'activation d'une règle, vérifiez ses faits, conditions et portée. Corrigez la règle ou demandez à un administrateur autorisé de la désactiver s'il s'agit d'un espace réservé non prévu. La désactivation d'une restriction requise supprime sa protection.

Avant d'activer la règle en production, activez-la pour la portée prévue dans un contexte de test et vérifiez que les demandes de signature réelles sont autorisées ou bloquées comme prévu lors de leur soumission. L'adresse /evaluate seule ne vérifie pas le comportement lors de la signature car elle accepte les faits fournis par l'utilisateur, qui peuvent différer de ceux fournis lors de la signature.

Création d'une règle

Cet exemple bloque les transferts natifs vers une seule adresse pour une organisation. Remplacez les exemples d'ID et d'adresse par les valeurs de votre environnement. La règle est désactivée et ne bloque pas les demandes tant que vous ne l'activez pas. Vérifiez la portée et les conditions avant d'activer la règle.

{
  "name": "block-restricted-native-recipient",
  "description": "Block native transfers to the restricted recipient",
  "category": "transaction-policy",
  "enabled": false,
  "scopelevels": ["org"],
  "targets": {
    "orgIds": ["<organization-id>"]
  },
  "conditions": {
    "all": [
      {
        "fact": "operation",
        "operator": "equal",
        "value": "native-transfer",
        "priority": 100
      },
      {
        "fact": "to_address",
        "operator": "equal",
        "value": "0x3333333333333333333333333333333333333333",
        "priority": 1
      }
    ]
  },
  "response": {
    "type": "BLOCK",
    "params": {
      "reason": "restricted-recipient"
    }
  }
}

Placez d'abord la condition operation et affectez-lui une priorité plus élevée que les faits propres à l'opération. Lors de l'autorisation de signature, l'évaluation échoue si elle lit un fait manquant ; la demande n'est pas autorisée en mode silencieux.

Les endpoints d'évaluation vérifient les règles par rapport aux faits que vous soumettez. La signature en direct utilise les faits de la demande validée par UWM et les cibles de portée de son portefeuille résolu. Utilisez l'évaluation pour inspecter une condition, puis confirmez le résultat via le flux de signature prévu.