Creación de una Política

Una política es un juego de reglas que puede bloquear solicitudes de firma. Las solicitudes de firma incluyen transacciones de blockchain y solicitudes para firmar datos, como los datos escritos por EIP-712. Cada regla almacenada tiene un ámbito, condiciones y una respuesta BLOCK. Las reglas activadas se aplican de forma acumulativa: si alguna regla aplicable coincide, se deniega la solicitud.

Si la evaluación de la política finaliza correctamente y ninguna regla aplicable devuelve una respuesta BLOCK, la solicitud puede continuar después de que UWaaS Wallet Manager (UWM) autentica el emisor de llamada, autoriza la cartera y la clave y valida la solicitud de firma.

Para obtener información sobre el gestor de carteras UWaaS, consulte Cartera universal como servicio (UWaaS). Para ver los campos y las operaciones de solicitud de API, consulte las API de Universal Wallet Manager, que incluyen:

Definir condiciones de regla

Una regla combina las condiciones con all, any y not. Puede anidar estos grupos para definir una restricción:

all coincide cuando coincide cada condición secundaria.
any coincide cuando coincide al menos una condición secundaria.
not coincide cuando su condición secundaria no coincide.

Definición de grupos de criterios específicos en línea. Las referencias de condición con nombre no están soportadas para las reglas de firma de UWM.

Una hoja de condición especifica un hecho, un operador y un valor. Utilice path para seleccionar una propiedad anidada de un hecho. Los valores priority superiores se evalúan primero.

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

El operador in coincide cuando el hecho es igual a uno de los valores mostrados. Utilice all para combinar esta condición con una condición operation. Utilice any cuando una de varias condiciones pueda disparar la restricción.

Operadores

Operador	Utilícelo cuando
`equal`, `notEqual`	Un hecho escalar debe ser igual o diferente de un valor del mismo tipo.
`in`, `notIn`	Un hecho escalar debe aparecer o no en una lista de valores.
`contains`, `doesNotContain`	Un hecho de matriz debe contener o no un valor.
`lessThan`, `lessThanEquals` (`lessThanInclusive`)	Un hecho numérico debe ser menor o igual que un valor numérico.
`greaterThan`, `greaterThanEquals` (`greaterThanInclusive`)	Un hecho numérico debe ser mayor o igual que un valor numérico.

Las comparaciones ordenadas en amount, amount_atomic y native_value_atomic utilizan aritmética decimal exacta tanto en /evaluate como en /internal/v1/authorize.

Utilice cadenas decimales para cantidades atómicas y umbrales grandes. Por ejemplo:

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

UWM proporciona amount_atomic en unidades base y no lo convierte en decimales de token. El hecho amount está soportado cuando lo proporciona un emisor de llamada de /evaluate; UWM no lo agrega a los hechos de firma.

Se aceptan números JSON decimales dentro del rango numérico seguro. Enviar valores numéricos más grandes como cadenas; se rechazan literales numéricos más grandes. Los nombres de operador greaterThanInclusive y lessThanInclusive permanecen soportados. Los operadores equal y notEqual comparan los valores por tipo. Otros hechos mantienen su comportamiento de comparación existente.

Decoradores de matriz

Agregue un prefijo a un operador con un decorador y dos puntos, como someFact:equal. Los decoradores cambian la forma en que el operador maneja las matrices o su resultado.

Decorador	Usar cuando
`someFact`	Al menos un elemento de un hecho de matriz coincide.
`everyFact`	Cada elemento de un hecho de matriz coincide.
`someValue`	El hecho coincide con al menos un elemento de un valor de matriz.
`everyValue`	El hecho coincide con cada elemento de un valor de matriz.
`swap`	La comparación utiliza el valor como el hecho y el hecho como el valor.
`not`	El resultado del operador base se debe negar.

Por ejemplo, someFact:equal puede coincidir con un ID de token en la matriz token_ids proporcionada para una llamada por lotes ERC-1155 descodificada:

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

Utilice el grupo de condiciones not para la lógica booleana y el decorador not: para negar un operador individual. Las prioridades de condición y regla establecen el orden de evaluación. No permiten que una regla sustituya a otra BLOCK coincidente.

Definición del ámbito de regla

Defina scopelevels y targets para especificar las solicitudes de firma que cubre una regla. Todos los ámbitos seleccionados deben coincidir. Los objetivos dentro de un ámbito son alternativas.

Ámbito	Destino necesario	Utilícelo para
`global`	Ninguno; especificar `scopelevels: ["global"]` por sí mismo.	Restricción que se aplica a todas las solicitudes de firma.
`org`	`targets.orgIds`	Restricción para una o varias organizaciones.
`wallet`	`targets.walletIds`	Restricción para una o más carteras.
`instance`	`targets.instanceIds`	Restricción para una o más instancias de red.
`asset`	`targets.assetIds`	Reglas de ámbito de activos existentes que se conservan por compatibilidad.

Combinar ámbitos cuando una regla depende de más de una dimensión. Por ejemplo,

scopelevels: ["org",
        "wallet"]

necesita que coincidan tanto los destinos de organización como de cartera. Una regla de solo cartera no tiene un límite de organización implícito. Utilice los ID devueltos por UWM, no los nombres mostrados.

Para restringir un método de contrato, coincida con contract_address y function_selector en las condiciones. Agregue el ámbito instance si el mismo método requiere diferentes restricciones en redes diferentes. El ámbito asset se conserva para las reglas existentes; estas condiciones no lo requieren.

Para targets.instanceIds, utilice el instanceId público que muestra la cartera de UWM o la API de red. Éste es el infra_instance_id registrado, no la clave de base de datos numérica o el ID de cadena. Actualice las reglas de ámbito de instancia antiguas que utilizan una clave de base de datos; UWM ahora solo envía el identificador de instancia pública.

Coincidencia de la solicitud de firma

Las condiciones solo pueden utilizar los hechos proporcionados para operation de la solicitud. El hecho operation está disponible para cada solicitud de firma.

`operation`	Hechos adicionales
`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 reconoce las llamadas canónicas ERC-20 transfer(address,uint256) con un valor nativo cero sin registro de token. UWM ya no lee capability.approved-token-contracts.

El perfil erc20-transfer también proporciona native_value_atomic ("0"), function_selector ("0xa9059cbb") y calldata_hash. Estos hechos permiten que las reglas contract-call existentes conserven todas sus restricciones.

Una operación erc20-transfer también es contract-call para las condiciones de operación. Ambos tipos de reglas pueden coincidir con la misma solicitud, y cualquier BLOCK coincidente lo rechaza. Este comportamiento se aplica a condiciones booleanas anidadas, equal, notEqual, in, notIn y en ambos puntos finales de evaluación. Otros hechos mantienen su semántica normal de igualdad.

La operación erc20-transfer coincide con los métodos transfer, no con transferFrom o ERC-1155. Incluya siempre el contract_address deseado en las reglas de token.

Las llamadas canónicas ERC-20 transferFrom, ERC-1155 safeTransferFrom y ERC-1155 safeBatchTransferFrom proporcionan datos adicionales de contract-call:

Llamada	Hechos adicionales
ERC-20 `transferFrom`	`owner_address`, `to_address`, `amount_atomic`
ERC-1155 `safeTransferFrom`	`owner_address`, `to_address`, `token_id`, `amount_atomic`
ERC-1155 `safeBatchTransferFrom`	Matrices `owner_address`, `to_address`, paralelas `token_ids` y `amounts`

UWM solo decodifica llamadas con un diseño canónico ABI soportado. Otras llamadas conservan los hechos genéricos de contract-call.

owner_address es la dirección de origen en los datos de la llamada, no la cartera de firma. Un selector identifica el diseño de datos de llamada, no el comportamiento del contrato desplegado. ERC-20 y ERC-721 comparten el selector transferFrom, por lo que aplican condiciones de importe solo a un contrato conocido por implementar ERC-20. Las direcciones y los selectores se normalizan a minúsculas; utilice valores de condición en minúsculas. Para las llamadas por lotes, no realice importes totales para distintos ID de token.

amount_atomic y native_value_atomic son cadenas decimales en unidades base; el valor nativo está en wei. Los valores enteros EIP-712 también son cadenas decimales. Para EIP-712, typed_data contiene el dominio y el mensaje firmados. Un valor path es relativo a ese hecho: utilice $.message.value para el valor del mensaje y $.domain.chainId para el identificador de cadena firmado.

Las restricciones de red, organización y cartera pertenecen a los ámbitos wallet, org y instance. Los metadatos de firmante, gas y nonce no son hechos de condición. El destino de ámbito asset no agrega un hecho de condición asset.

Antes de activar una regla de firma

Utilice solo los hechos enumerados para la operación en Coincidir con la solicitud de firma. Incluya una condición operation cuando una regla utilice hechos específicos de la operación.

Al guardar una regla, no se confirma que UWM pueda evaluarla durante la firma. Por ejemplo, UWM no proporciona un hecho tier. Una regla que comprueba si tier es igual a gold puede hacer que la firma falle con un error genérico de 500.

Si la firma falla después de activar una regla, revise sus hechos, condiciones y ámbito. Corrija la regla o solicite a un administrador autorizado que la desactive si se trata de un marcador de posición no deseado. La desactivación de una restricción necesaria elimina su protección.

Antes de activar la regla en producción, actívela para el ámbito deseado en un contexto de prueba y verifique que las solicitudes de firma reales estén permitidas o bloqueadas según lo previsto cuando se envíen. El punto final /evaluate por sí solo no verifica el comportamiento durante la firma porque acepta hechos proporcionados por el usuario, que pueden ser diferentes de los proporcionados durante la firma.

Crear regla

Este ejemplo bloquea las transferencias nativas a una dirección para una organización. Sustituya los ID y la dirección de ejemplo por los valores de su entorno. La regla está desactivada y no bloqueará las solicitudes hasta que la active. Revise el ámbito y las condiciones antes de activar la regla.

{
  "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"
    }
  }
}

Ponga la condición operation en primer lugar y asígnela una prioridad más alta que los hechos específicos de la operación. Durante la firma de la autorización, la evaluación falla si lee un hecho faltante; la solicitud no se permite silenciosamente.

Los puntos finales de evaluación comprueban las reglas según los hechos que envíe. La firma en directo utiliza hechos de la solicitud validada de UWM y los destinos de ámbito de su cartera resuelta. Utilice la evaluación para inspeccionar una condición y, a continuación, confirme el resultado mediante el flujo de firma previsto.