Before an organisation can add Utila in the Console, the platform operator switches Utila on, and the Utila vault admin creates a service account that accepts calls only from DALP's addresses. Without the switch, Utila is not in the Console provider list. Without the service account and its allowed addresses, the first probe fails. Read Limits first to decide whether Utila fits.
Utila is a custody provider that holds keys in a vault and signs when its own policy allows it. In DALP, the platform files each transaction request in your Utila vault. Utila's approvers vote under your Utila policy, and the signing agent, which holds the service account's key share, signs the request designated to it. DALP tracks the request while it waits for a signature. DALP never asks Utila to sign a raw digest, the bare hash of a transaction, which Utila does not sign.
The Utila signing agent is the process that signs the requests DALP filed. Utila's own name for it is the Co-Signer, and its guide is Utila Co-Signer.
What the Utila vault admin prepares
A Utila service account is a non-human user that DALP signs in as. The vault admin creates it, and Utila describes the screens in Creating a Service Account.
Create the service account
As an admin of the vault, open Vault Settings, then Service Accounts, and add a service account. Enter a name and an email. DALP asks for the email in the “Service account email” field, so note it.
Add a public key
Utila controls the service account with RSA key pairs and asks you to paste the public half. You must add at least one key when you create the account, and an account holds up to three active keys. Keep the private half. You enter it in DALP as the “Service account private key (PEM)”, and DALP stores it with the configuration's credentials.
A second key lets you rotate without a gap. If you add one, give its private half to DALP as the “Standby private key (PEM)”. When Utila rejects the main key as no longer active, DALP authenticates with the standby key instead. The key signs the API token DALP presents to Utila, not the transactions.
Restrict the service account to DALP's addresses
Utila requires you to choose how the account may be accessed. It recommends trusted IPs only. Each entry is a single IPv4 or IPv6 address, and Utila does not support CIDR ranges, so the vault admin lists every address DALP calls Utila from, one by one. The platform operator provides that list, because only the operator knows which egress addresses the deployment uses. Take them from the outbound addresses of the network the DALP cluster runs in. DALP calls Utila at
https://api.utila.iounless the organisation sets its own “API base URL”, and uses port 443. A request from an address that is not listed is rejected, so a missing address shows up as a failed probe. Changing the list later needs an admin approval in Utila.Choose the role
Utila asks for a role in the last step, or lets you skip it. Utila's page does not list the roles, so take the role from your Utila policy: the account must be able to file and sign transactions in the vault. Assigning the role can need approval from further vault admins, so allow for that wait before you probe.
What the platform operator switches on
Utila is off in every deployment until the operator switches it on. Set global. in your Helm values, or CUSTODY_ outside the chart, as Prerequisites describes. Until you do, “Utila custody” is not in the Console provider list, and the platform refuses a new Utila configuration. The same switch leaves existing configurations signing if you switch it off later, so switching off closes intake and does not stop signing. Quarantine a configuration to stop it.
Give the vault admin the list of addresses DALP calls Utila from.
How each Console field maps to Utila
The organisation Owner fills these fields when adding the configuration, as Organisation custody describes. Every value comes from the vault admin's steps in Utila.
A chain ID can have only one Utila network. The form refuses two lines with the same chain ID. A chain with no line in “Networks” cannot sign, as The signing lanes explains.
Add the configuration
Add and probe
In the Console, open “Organisation settings”, then “Custody”. Select “Utila custody” in “Add custody provider”, fill in the fields in How each Console field maps to Utila, and select “Add and probe provider”. The platform probes Utila before the configuration accepts new accounts.
Rotate when a key changes
Open the configuration, change the fields that changed, and select Probe and rotate credentials. The platform probes the replacement before it saves it, so a failed probe leaves the stored credentials in place. Credential fields you leave empty keep their stored values. The other fields open with the stored values and are saved as the form holds them. After a rotation DALP keeps the current and the previous credential stored, and a later rotation removes older ones after a one-hour grace period.
Stop signing through a configuration
Use “Quarantine execution”, which Organisation custody describes. Quarantine stops new execution through the configuration, and “Recover execution” reverses it. It does not cancel a request already filed in Utila. In webhook mode the signing agent gets no decision from DALP for a quarantined configuration, so that request stays pending in Utila until it expires or you cancel it there.
The signing agent
The Utila signing agent is a component of the Utila CLI. Utila Co-Signer states how the agent works:
- It polls a vault and acts only on transactions that wait for a signature and are designated to its service account.
- Transfers created in the Utila console are not sent to it. Only transactions created through the API reach it, which is how DALP files them.
- It runs in one of two modes. In sign-all mode, it signs every transaction designated to the service account. In webhook mode, it forwards each transaction to a URL and signs or cancels as the reply says. Utila suggests sign-all mode for a first test.
- In webhook mode, if the endpoint is unreachable, times out or answers with anything other than 200, the agent neither signs nor cancels. The transaction stays pending.
The “Signing agent secret” field is optional, and you need it only when a signing agent asks DALP for a decision. When you set it, DALP stores it with the configuration's credentials. A signing agent that asks DALP for a decision must present that secret. DALP gives no decision to a wrong secret, to an unknown or quarantined configuration, or to a configuration of another organisation. DALP also answers only for a request it filed itself, and tells the agent not to sign when a field of the held request differs from what DALP filed. A request DALP never filed stays pending in Utila.
The signing agent does not judge the request. In webhook mode it asks DALP, and DALP says yes to every request it filed whose fields still match. That protects against a request changed after DALP filed it. It does not protect against DALP filing a request you would refuse, so put a Utila approval policy on the vault for any request that needs a person.
To run the agent and point it at DALP, see Utila signing agent.
The signing lanes
A signing lane is how a provider signs one kind of request on one chain. Utila declares the same lanes on every network that has a line in “Networks”.
For a typed payload or a smart-account operation, DALP asks Utila for the signature once a second for up to 300 seconds, then reports that signing failed and that the request may still be pending in Utila. When the request may wait for an approver, DALP checks for 15 seconds, then holds it as waiting for approval. A wallet transaction is filed and returns at once. A request that Utila declines, blocks by policy or cancels reads as rejected, and one that expires reads as expired.
Limits
- A chain with no network in “Networks” is refused, at creation and at “Add network”. The message names the fix.
- “Networks” needs at least one line, and the networks you list are the only ones Utila can serve. To add a chain to an existing configuration, rotate the credentials with the new line in “Networks”, then use Add network.
- The service account's allowed addresses are single addresses. A deployment with a changing egress address needs the list updated, with an admin approval in Utila, each time it changes.
- DALP holds a Utila request that waits for an approver as waiting for approval. When Utila reports the decision, by signed webhook (
POST /api/) or on DALP's own re-read, DALP resumes the request. A request still undecided at DALP's approval deadline ends as expired.webhooks/ utila - Switching Utila off closes new intake and leaves stored configurations signing. A quarantined configuration does not execute. A rotation saves the new credentials only after they pass the probe, so a failed rotation leaves the stored ones in use.
Troubleshooting
The probe fails
Read the reported error first. An authentication failure points to the service account email or the private key: confirm that the key is still active on the service account in Utila. A message that the vault, wallet or transaction is not found points to the vault ID, or to a service account whose role does not cover the vault. Then confirm that every address DALP calls Utila from is on the service account's list, because Utila rejects any other address. Correct the value and probe again. If the reported error does not explain the failure, send the error text to your DALP support contact. Questions about the vault, the service account or its allowed addresses go to Utila support.
The refusal says no Utila network is bound to a chain
The chain has no line in “Networks”. Rotate the credentials with a chain ID network name line for it, then add the
chain with “Add network”. The refusal asks you to probe again after you bind the chain.
A request stays pending in Utila
Utila holds a request until its approvers vote and its designated signer signs. If you use the signing agent in webhook mode, a webhook that is unreachable, times out or answers other than 200 leaves the request pending. A request created in the Utila console is never sent to the signing agent.
The Console refuses the signing agent secret
The secret is shorter than 32 characters. Enter a longer value, or leave the field empty. Use only letters, digits,
., _, ~ and -, because the signing agent sends the secret inside a URL.